diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 7392520e5..01f141b5b 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -14,7 +14,7 @@ updates: # The windowsHide patch (package.json patchedDependencies, #2160/#1989) is # keyed to one playwright-core version; a minor or major bump drops it and # brings back Windows console flashes. Patch updates still flow. The 1.64 - # migration (re-key the patch, the Dia/cookie qualification pins, the + # migration (re-key the patch, the cookie qualification pins, the # arm64 artifact name) is owned by Garry, revisit 2026-11-15 (#2923). ignore: - dependency-name: "playwright" diff --git a/.github/scripts/dia-gui-readiness.c b/.github/scripts/dia-gui-readiness.c deleted file mode 100644 index b046dec49..000000000 --- a/.github/scripts/dia-gui-readiness.c +++ /dev/null @@ -1,138 +0,0 @@ -#define _DARWIN_C_SOURCE -#define _POSIX_C_SOURCE 200809L -#include -#include -#include -#include -#include -#include -#include -#include -#include -#ifdef __APPLE__ -#include -#include -#endif - -struct root_fact { - const char *state; - const char *kind; - int owner_matches; - int ancestor_blocked; -}; - -static const char *kind_of(mode_t mode) { - if (S_ISDIR(mode)) return "directory"; - if (S_ISREG(mode)) return "file"; - if (S_ISLNK(mode)) return "symlink"; - return "other"; -} - -static struct root_fact inspect_root(int home, const char *relative, uid_t owner) { - struct root_fact fact = {"unavailable", NULL, -1, 0}; - char components[256]; - if (strlen(relative) >= sizeof(components)) return fact; - memcpy(components, relative, strlen(relative) + 1); - int directory = dup(home); - if (directory < 0) return fact; - char *state = NULL; - char *component = strtok_r(components, "/", &state); - while (component) { - char *next = strtok_r(NULL, "/", &state); - struct stat before; - if (fstatat(directory, component, &before, AT_SYMLINK_NOFOLLOW) != 0) { - if (errno == ENOENT) fact.state = "absent"; - break; - } - fact.kind = kind_of(before.st_mode); - fact.owner_matches = before.st_uid == owner; - if (!next) { fact.state = "present"; break; } - if (!S_ISDIR(before.st_mode) || before.st_uid != owner) { fact.ancestor_blocked = 1; break; } - int child = openat(directory, component, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK); - struct stat after; - if (child < 0) { fact.ancestor_blocked = 1; break; } - if (fstat(child, &after) != 0 || after.st_dev != before.st_dev || after.st_ino != before.st_ino - || !S_ISDIR(after.st_mode) || after.st_uid != owner) { - close(child); - fact.ancestor_blocked = 1; - break; - } - close(directory); - directory = child; - fact.kind = NULL; - fact.owner_matches = -1; - component = next; - } - close(directory); - return fact; -} - -static const char *boolean_or_null(int value) { - return value < 0 ? "null" : value ? "true" : "false"; -} - -static void print_browser_roots(int home, uid_t owner) { - const char *names[] = {"chrome", "chromium", "arc", "dia", "comet", "brave", "edge", "safari", "cookies"}; - const char *paths[] = {"Library/Application Support/Google/Chrome", "Library/Application Support/Chromium", - "Library/Application Support/Arc", "Library/Application Support/Dia", "Library/Application Support/Comet", - "Library/Application Support/BraveSoftware/Brave-Browser", "Library/Application Support/Microsoft Edge", "Library/Safari", "Library/Cookies"}; - printf("{"); - for (size_t index = 0; index < sizeof(names) / sizeof(names[0]); index++) { - struct root_fact fact = inspect_root(home, paths[index], owner); - printf("%s\"%s\":{\"state\":\"%s\",\"kind\":", index ? "," : "", names[index], fact.state); - if (fact.kind) printf("\"%s\"", fact.kind); else printf("null"); - printf(",\"ownerMatches\":%s,\"ancestorBlocked\":%s}", boolean_or_null(fact.owner_matches), boolean_or_null(fact.ancestor_blocked)); - } - printf("}"); -} - -#ifdef __APPLE__ -static int dictionary_boolean(CFDictionaryRef dictionary, CFStringRef key) { - CFTypeRef value = CFDictionaryGetValue(dictionary, key); - return value && CFGetTypeID(value) == CFBooleanGetTypeID() ? CFBooleanGetValue(value) : -1; -} - -int main(int argc, char **argv) { - int browser_roots = argc == 2 && strcmp(argv[1], "--browser-roots") == 0; - if (argc != 1 && !browser_roots) return 2; - uid_t uid = getuid(); - struct passwd *account = getpwuid(uid); - char registered[PATH_MAX], environment[PATH_MAX]; - const char *home = getenv("HOME"); - int home_matches = account && home && realpath(account->pw_dir, registered) && realpath(home, environment) - && strcmp(registered, account->pw_dir) == 0 && strcmp(registered, environment) == 0; - int home_fd = home_matches ? open(registered, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK) : -1; - struct stat home_info; - home_matches = home_fd >= 0 && fstat(home_fd, &home_info) == 0 && S_ISDIR(home_info.st_mode) && home_info.st_uid == uid; - SessionAttributeBits attributes = 0; - OSStatus status = SessionGetInfo(callerSecuritySession, NULL, &attributes); - CFDictionaryRef quartz = CGSessionCopyCurrentDictionary(); - int same_uid = -1, login_done = -1, on_console = -1; - if (quartz) { - CFTypeRef value = CFDictionaryGetValue(quartz, kCGSessionUserIDKey); - long long session_uid = -1; - if (value && CFGetTypeID(value) == CFNumberGetTypeID() && CFNumberGetValue(value, kCFNumberLongLongType, &session_uid)) same_uid = session_uid == uid; - if (same_uid == 1) { - login_done = dictionary_boolean(quartz, kCGSessionLoginDoneKey); - on_console = dictionary_boolean(quartz, kCGSessionOnConsoleKey); - } - } - printf("{\"protocol\":1,\"supported\":true,\"identity\":{\"effectiveUidMatches\":%s,\"homeMatchesRegistered\":%s},", - boolean_or_null(geteuid() == uid), boolean_or_null(home_matches)); - printf("\"security\":{\"status\":%d,\"graphicAccess\":%s,\"rootSession\":%s,\"tty\":%s,\"remote\":%s},", - (int)status, boolean_or_null(status ? -1 : !!(attributes & sessionHasGraphicAccess)), boolean_or_null(status ? -1 : !!(attributes & sessionIsRoot)), - boolean_or_null(status ? -1 : !!(attributes & sessionHasTTY)), boolean_or_null(status ? -1 : !!(attributes & sessionIsRemote))); - printf("\"quartz\":{\"present\":%s,\"sameUid\":%s,\"loginDone\":%s,\"onConsole\":%s},\"browserRoots\":", - boolean_or_null(quartz != NULL), boolean_or_null(same_uid), boolean_or_null(login_done), boolean_or_null(on_console)); - if (browser_roots && home_matches) print_browser_roots(home_fd, uid); else printf("null"); - printf("}\n"); - if (home_fd >= 0) close(home_fd); - if (quartz) CFRelease(quartz); - return 0; -} -#else -int main(void) { - printf("{\"protocol\":1,\"supported\":false}\n"); - return 2; -} -#endif diff --git a/.github/scripts/dia-launch-driver.mjs b/.github/scripts/dia-launch-driver.mjs deleted file mode 100644 index ef4538f3b..000000000 --- a/.github/scripts/dia-launch-driver.mjs +++ /dev/null @@ -1,231 +0,0 @@ -import { createHash } from 'node:crypto'; -import { closeSync, constants, createReadStream, fstatSync, lstatSync, openSync, readdirSync, readSync, realpathSync } from 'node:fs'; -import { createRequire } from 'node:module'; -import { release } from 'node:os'; -import path from 'node:path'; -import { spawnSync } from 'node:child_process'; -import { assertOwnedDiaProfile, browserOperationTimedOut, browserPreflightError, browserRootFacts, browserStartupFacts, browserStderrFacts, - nativeDiaLaunchOptions, observeBrowserLaunches, ownsFreshAccount, parseDirectoryRecord, - readFreshAccountConfiguration, stopOwnedBrowserGroup, validateQualificationHost } from './qualify-dia-macos.ts'; - -const require = createRequire(import.meta.url); -const sha256 = async file => { - const hash = createHash('sha256'); - for await (const chunk of createReadStream(file)) hash.update(chunk); - return hash.digest('hex'); -}; - -export function normalizedLaunchHashes(args, env, ownedPaths) { - const paths = Object.entries(ownedPaths).sort(([, left], [, right]) => right.length - left.length); - const normalize = value => { - const equals = value.startsWith('--') ? value.indexOf('=') : -1; - const prefix = equals >= 0 ? value.slice(0, equals + 1) : ''; - const candidate = equals >= 0 ? value.slice(equals + 1) : value; - for (const [role, owned] of paths) { - if (candidate === owned || candidate.startsWith(owned + path.sep)) return prefix + '<' + role + '>' + candidate.slice(owned.length); - } - return value; - }; - const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex'); - return { argvSha256: hash(args.map(normalize)), environmentSha256: hash(Object.entries(env).sort(([a], [b]) => a.localeCompare(b)) - .map(([key, value]) => [key, normalize(value)])) }; -} - -export function compareDiaLaunchReceipts(left, right) { - const invalid = { comparable: false, qualificationCredit: false, reason: 'incomplete_or_incompatible_arms' }; - if (!left?.launcher?.accountGuid || left.launcher.accountGuid === right?.launcher?.accountGuid) return invalid; - const fingerprints = []; - for (const [receipt, runtime] of [[left, 'bun'], [right, 'node']]) { - const qualification = receipt?.qualification; - const control = receipt?.backgroundPreflight?.comparisonControl; - const source = qualification?.launchComparison?.source; - const config = receipt?.launchComparison; - if (config?.mode !== 'launch-only' || config.runtime !== runtime || config.qualificationCredit !== false - || receipt.backgroundPreflight?.status !== 'passed' || !control?.ready || qualification?.launchComparison?.qualificationCredit !== false - || qualification.keychainStage !== 'completed' || qualification.isolation?.registeredIdentity !== true - || qualification.isolation?.sharedRegisteredHome !== true || qualification.artifact?.signatureVerified !== true - || qualification.artifact?.gatekeeperNotarized !== true || qualification.artifact?.macosCompatibility?.compatible !== true - || qualification.platform?.os !== 'darwin' || qualification.platform?.architecture !== 'arm64' - || qualification.platform?.bun !== '1.4.2' || qualification.platform?.playwright !== '1.62.1' - || !/^\d+(?:\.\d+){1,2}$/.test(qualification.artifact.macosCompatibility.hostVersion) - || qualification.artifact?.architectures?.includes('arm64') !== true - || ['serviceStopped', 'userDomainStopped', 'userProcessesStopped', 'accountRemoved', 'groupRemoved', 'stagingRemoved'].some(key => receipt.launcherCleanup?.[key] !== true) - || ['ownedBrowsersStopped', 'sourceProfileRemoved', 'keychainRestored', 'mountDetached', 'fixtureRemoved'].some(key => qualification.cleanup?.[key] !== true) - || ['pass', 'fail', 'skip'].some(key => receipt.counts?.[key] !== 0 || qualification.counts?.[key] !== 0)) return invalid; - for (const [result, purpose] of [[control, 'control'], [source, 'source']]) { - const policy = result?.launchAttempts?.[0]; - if (result?.protocol !== 1 || result.purpose !== purpose || result.samplingEnabled !== false || result.rootCount !== 1 - || result.supervisor?.closed !== true || result.supervisor?.exitCode !== 0 || result.cleanup?.confirmed !== true - || result.cleanup?.childClosed !== true || result.cleanup?.groupAbsent !== true || result.cleanup?.launchSettled !== true || result.launchAttempts?.length !== 1 - || result.cleanup?.groups?.length !== 1 || result.cleanup.groups[0].absenceConfirmed !== true || result.cleanup.groups[0].childCloseObserved !== true - || typeof result.ready !== 'boolean' || typeof result.launchReturned !== 'boolean' - || policy?.sandboxRequired !== true || policy?.sandboxDisablingFlag !== false || policy?.pipeFlag !== true || policy?.tcpDebuggingFlag !== false - || policy?.mockKeychainFlag !== false || policy?.passwordStoreFlag !== false || policy?.firstRunSuppressed !== false - || policy?.headlessFlag !== true || policy?.expectedProfile !== true || policy?.detached !== true || policy?.shellDisabled !== true - || policy?.stdioCount !== 5 || policy?.extraPipeDescriptors !== true || policy?.profileArgumentCount !== 1 - || result.driver?.runtime !== runtime || result.driver?.version !== (runtime === 'bun' ? '1.4.2' : '24.18.0') - || result.driver?.os !== 'darwin' || result.driver?.architecture !== 'arm64' || result.driver?.playwright !== '1.62.1' - || result.driver?.release !== qualification.platform.release - || result.driver?.executableSha256 !== config.executableSha256 || result.driver?.driverSha256 !== config.driverSha256 - || result.driver?.helpersSha256 !== config.helpersSha256 || (result.ready && (!result.protocolResponded || !result.startupPages?.allowed || !result.postProbePages?.allowed)) - || ![result.argvSha256, result.environmentSha256, config.executableSha256, config.driverSha256, config.helpersSha256].every(value => /^[a-f0-9]{64}$/.test(value))) return invalid; - } - const hashes = [receipt.launcher?.sourceRevision, receipt.launcher?.archiveSha256, receipt.launcher?.destinationSha256, - qualification.artifact.sha256, qualification.artifact.executableSha256]; - if (!/^[a-f0-9]{40}$/.test(hashes[0]) || !hashes.slice(1).every(value => /^[a-f0-9]{64}$/.test(value))) return invalid; - fingerprints.push(JSON.stringify({ hashes, platform: qualification.platform, compatibility: qualification.artifact.macosCompatibility, - version: qualification.artifact.version, bundle: qualification.artifact.bundleId, team: qualification.artifact.team, - driver: config.driverSha256, helpers: config.helpersSha256, controlArgs: control.argvSha256, controlEnv: control.environmentSha256, - sourceArgs: source.argvSha256, sourceEnv: source.environmentSha256 })); - } - if (fingerprints[0] !== fingerprints[1]) return { ...invalid, reason: 'comparison_inputs_differ' }; - const bun = left.qualification.launchComparison.source.ready === true; - const node = right.qualification.launchComparison.source.ready === true; - return { comparable: true, qualificationCredit: false, outcome: bun ? node ? 'both_ready' : 'bun_only_ready' : node ? 'node_only_ready' : 'neither_ready' }; -} - -export async function runProtectedLaunch(executable, profile, env, purpose, ownedPaths) { - const result = { protocol: 1, purpose, stage: 'runtime_import', launchReturned: false, protocolResponded: false, ready: false, - timedOut: false, error: null, samplingEnabled: false, cleanup: { childClosed: false, groupAbsent: false, confirmed: false } }; - const { chromium } = await import('playwright'); - const cp = require('node:child_process'); - const original = cp.spawn; - cp.spawn = function(command, args, options) { - if (command === executable) Object.assign(result, normalizedLaunchHashes(args, options.env, ownedPaths)); - return original.call(this, command, args, options); - }; - const observer = observeBrowserLaunches(new Map([[executable, profile]])); - let context; - let timer; - let launchSettled = false; - try { - result.stage = 'launch'; - const launch = chromium.launchPersistentContext(profile, nativeDiaLaunchOptions(executable, env)); - void launch.then(() => { launchSettled = true; }, () => { launchSettled = true; }); - context = await Promise.race([launch, - new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('operation_timeout')), 30_000); })]); - clearTimeout(timer); - result.launchReturned = true; - result.stage = 'ownership'; - if (observer.children.length !== 1) throw new Error('source_process_ownership_unconfirmed'); - result.stage = 'startup_pages'; - const urls = context.pages().map(page => page.url()); - result.startupPages = { ...browserStartupFacts(urls, 'http://127.0.0.1:1'), allowed: urls.every(url => url === 'about:blank') }; - if (!result.startupPages.allowed) throw new Error('onboarding_or_external_page'); - result.stage = 'protocol_probe'; - if (!context.pages()[0]) throw new Error('source_protocol_page_unavailable'); - result.protocolResponded = await Promise.race([context.pages()[0].evaluate(() => 1).then(value => value === 1), - new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('operation_timeout')), 5000); })]); - clearTimeout(timer); - const after = context.pages().map(page => page.url()); - result.postProbePages = { ...browserStartupFacts(after, 'http://127.0.0.1:1'), allowed: after.every(url => url === 'about:blank') }; - if (!result.postProbePages.allowed) throw new Error('onboarding_or_external_page'); - result.ready = result.protocolResponded; - result.stage = 'ready'; - } catch (error) { - const reasons = browserStderrFacts(observer.children).flatMap(facts => Object.entries(facts.reasonCounts ?? {}) - .filter(([, count]) => count > 0).map(([reason]) => reason)); - result.error = browserPreflightError(error, reasons); - result.timedOut = browserOperationTimedOut(error); - } finally { - clearTimeout(timer); - const deadline = performance.now() + 5_000; - observer.stop(); - result.rootCount = observer.children.length; - result.launchAttempts = observer.attempts; - result.rootsBeforeCleanup = browserRootFacts(observer.children); - result.stderrBeforeCleanup = browserStderrFacts(observer.children); - if (context) void context.close().catch(() => {}); - const groups = []; - for (const child of observer.children) { - const facts = { pid: child.pid, signalSent: false, absenceConfirmed: false, childCloseObserved: false }; - try { await stopOwnedBrowserGroup(child, deadline, facts); } - catch { facts.failed = true; } - groups.push(facts); - } - result.cleanup.groups = groups; - result.cleanup.childClosed = observer.children.length === 1 && observer.children.every(child => child.closeObserved); - result.cleanup.groupAbsent = groups.length === 1 && groups.every(group => group.absenceConfirmed); - result.cleanup.launchSettled = launchSettled; - result.cleanup.confirmed = result.cleanup.childClosed && result.cleanup.groupAbsent && launchSettled; - result.rootsAfterCleanup = browserRootFacts(observer.children); - result.stderrAfterCleanup = browserStderrFacts(observer.children); - if (launchSettled) { observer.restore(); cp.spawn = original; } - } - return result; -} - -export function readComparisonRequest() { - const buffer = Buffer.alloc(16 * 1024 + 1); - let length = 0; - while (length < buffer.length) { - const read = readSync(0, buffer, length, buffer.length - length, null); - if (!read) break; - length += read; - } - if (length > 16 * 1024) throw new Error('invalid_driver_request'); - const request = JSON.parse(buffer.subarray(0, length).toString()); - if (!request || !['control', 'source'].includes(request.purpose) - || Object.keys(request).some(key => !(request.purpose === 'control' ? ['purpose'] : ['purpose', 'assetRoot', 'executableName', 'executableSha256']).includes(key))) throw new Error('invalid_driver_request'); - return request; -} - -async function main() { - validateQualificationHost(process.env); - const request = readComparisonRequest(); - const account = readFreshAccountConfiguration(process.argv[2], 'comparison-driver'); - const config = account.launchComparison; - const runtimeVersion = process.versions.bun ?? process.versions.node; - if ((config.runtime === 'bun' ? process.versions.bun !== '1.4.2' : Boolean(process.versions.bun) || runtimeVersion !== '24.18.0') - || process.arch !== 'arm64' || require('playwright/package.json').version !== '1.62.1') throw new Error('invalid_driver_runtime'); - if (await sha256(process.execPath) !== config.executableSha256 || await sha256(import.meta.filename) !== config.driverSha256 - || await sha256(path.join(import.meta.dirname, 'qualify-dia-macos.ts')) !== config.helpersSha256) throw new Error('driver_inputs_changed'); - const identity = spawnSync('/usr/bin/dscl', ['.', '-read', '/Users/' + account.account, 'UniqueID', 'PrimaryGroupID', 'NFSHomeDirectory', 'GeneratedUID'], - { env: account.environment, encoding: 'utf8', timeout: 5000, maxBuffer: 64 * 1024 }); - if (identity.error || identity.status !== 0 || !ownsFreshAccount(parseDirectoryRecord(identity.stdout), account)) throw new Error('driver_identity_unconfirmed'); - let executable = account.destinationExecutable; - let profile = path.join(account.temporary, 'probe/chromium'); - let temporary = account.temporary; - const ownedPaths = { home: account.home, snapshot: account.snapshot, temporary: account.temporary, work: account.work }; - if (request.purpose === 'source') { - const root = request.assetRoot; - if (typeof root !== 'string' || realpathSync(root) !== root || path.dirname(root) !== account.temporary || !path.basename(root).startsWith('dia-') - || lstatSync(root).uid !== account.uid || typeof request.executableName !== 'string' || !request.executableName - || path.basename(request.executableName) !== request.executableName || ['.', '..'].includes(request.executableName)) throw new Error('invalid_source_request'); - executable = realpathSync(path.join(root, 'Dia.app/Contents/MacOS', request.executableName)); - if (!executable.startsWith(path.join(root, 'Dia.app/Contents/MacOS') + path.sep) - || !/^[a-f0-9]{64}$/.test(request.executableSha256) || await sha256(executable) !== request.executableSha256) throw new Error('source_identity_unconfirmed'); - profile = path.join(account.home, 'Library/Application Support/Dia/User Data'); - if (realpathSync(profile) !== profile || lstatSync(profile).uid !== account.uid) throw new Error('source_profile_unowned'); - if (JSON.stringify(readdirSync(profile)) !== JSON.stringify(['.gstack-dia-owner'])) throw new Error('source_profile_not_fresh'); - const descriptor = openSync(path.join(profile, '.gstack-dia-owner'), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); - const marker = Buffer.alloc(65); - let bytes; - try { - const entry = fstatSync(descriptor); - if (!entry.isFile() || entry.uid !== account.uid || entry.nlink !== 1 || entry.size !== 64 || (entry.mode & 0o077) !== 0) throw new Error('source_profile_unowned'); - bytes = readSync(descriptor, marker, 0, marker.length, 0); - } finally { closeSync(descriptor); } - if (bytes !== 64) throw new Error('source_profile_unowned'); - const info = lstatSync(profile, { bigint: true }); - assertOwnedDiaProfile({ home: account.home, profile, uid: account.uid, dev: info.dev, ino: info.ino, nonce: marker.subarray(0, bytes).toString() }); - temporary = path.join(root, 't'); - ownedPaths.assets = root; - } else { - if (await sha256(executable) !== account.destinationSha256) throw new Error('control_identity_unconfirmed'); - try { lstatSync(profile); throw new Error('control_profile_not_fresh'); } - catch (error) { if (error.code !== 'ENOENT') throw error; } - } - const env = { HOME: account.home, TMPDIR: temporary, PATH: '/usr/bin:/bin:/usr/sbin:/sbin', LANG: 'en_US.UTF-8' }; - const result = await runProtectedLaunch(executable, profile, env, request.purpose, ownedPaths); - result.driver = { runtime: config.runtime, version: runtimeVersion, architecture: process.arch, os: process.platform, release: release(), - executableSha256: config.executableSha256, driverSha256: config.driverSha256, helpersSha256: config.helpersSha256, playwright: '1.62.1' }; - return result; -} - -if (import.meta.main) { - main().then(result => { process.stdout.write(JSON.stringify(result) + '\n'); }, () => { - process.stdout.write(JSON.stringify({ protocol: 1, ready: false, error: 'driver_admission_failed', cleanup: { confirmed: false } }) + '\n'); - process.exitCode = 2; - }); -} diff --git a/.github/scripts/qualify-dia-macos.ts b/.github/scripts/qualify-dia-macos.ts deleted file mode 100644 index b5fc3b9e3..000000000 --- a/.github/scripts/qualify-dia-macos.ts +++ /dev/null @@ -1,1430 +0,0 @@ -import { createHash, randomBytes } from 'node:crypto'; -import { spawnSync, type ChildProcess } from 'node:child_process'; -import { accessSync, chmodSync, closeSync, constants, createReadStream, existsSync, fstatSync, linkSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'; -import { createRequire } from 'node:module'; -import { homedir, release } from 'node:os'; -import path from 'node:path'; -import type { BrowserContext } from 'playwright'; - -const require = createRequire(import.meta.url); -const repository = path.resolve(import.meta.dirname, '../..'); -export const DIA_DOWNLOAD = 'https://releases.diabrowser.com/release/Dia-latest.dmg'; -export const FRESH_WORK_PREFIX = '/private/tmp/dn-'; - -export interface FreshAccount { - work: string; home: string; temporary: string; snapshot: string; bun: string; destinationExecutable?: string; - uid: number; gid: number; account: string; guid: string; groupGuid: string; label: string; - sourceRevision: string; archiveSha256: string; bunSha256: string; destinationSha256?: string; - configFile: string; environment: Record; - launchComparison?: { mode: 'launch-only'; runtime: 'bun' | 'node'; executable: string; executableSha256: string; - driverSha256: string; helpersSha256: string }; - guiReadiness?: { mode: 'gui-readiness-only'; executable: string; executableSha256: string; sourceSha256: string }; -} - -export function parseDirectoryRecord(output: string): Record { - const result: Record = {}; - for (const line of output.trim().split('\n')) { - const match = line.match(/^([A-Za-z]+):\s+(.+)$/); - if (!match || Object.hasOwn(result, match[1])) throw new Error('invalid_directory_record'); - result[match[1]] = match[2].trim(); - } - return result; -} - -export function ownsFreshAccount(record: Record, account: Pick): boolean { - return record.GeneratedUID?.toUpperCase() === account.guid.toUpperCase() && record.UniqueID === String(account.uid) - && record.PrimaryGroupID === String(account.gid) && record.NFSHomeDirectory === account.home; -} - -export function validateGuiReadinessAuthority(account: FreshAccount, role: 'coordinator' | 'comparison-driver') { - if (account.guiReadiness === undefined) return; - if (!account.guiReadiness || account.guiReadiness.mode !== 'gui-readiness-only' || account.launchComparison !== undefined - || account.destinationExecutable !== undefined || account.destinationSha256 !== undefined || role !== 'coordinator' - || account.guiReadiness.executable !== path.join(account.work, 'bin/gui-readiness') - || ![account.guiReadiness.executableSha256, account.guiReadiness.sourceSha256].every(value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value))) { - throw new Error('gui_readiness_authority_invalid'); - } -} - -export function readFreshAccountConfiguration(configFile: string, role: 'coordinator' | 'comparison-driver' = 'coordinator'): FreshAccount { - const work = path.dirname(configFile); - if (!path.isAbsolute(configFile) || path.basename(configFile) !== 'account.json' || path.dirname(work) !== '/private/tmp' - || !path.basename(work).startsWith(path.basename(FRESH_WORK_PREFIX)) || realpathSync(work) !== work) throw new Error('unsafe_fresh_account_configuration'); - const parent = lstatSync(work); - const info = lstatSync(configFile); - if (!parent.isDirectory() || parent.uid !== 0 || (parent.mode & 0o022) !== 0 || !info.isFile() || info.uid !== 0 - || info.nlink !== 1 || (info.mode & 0o022) !== 0 || info.size > 64 * 1024 || realpathSync(configFile) !== configFile) throw new Error('unsafe_fresh_account_configuration'); - const account: FreshAccount = JSON.parse(readFileSync(configFile, 'utf8')); - validateGuiReadinessAuthority(account, role); - if (role === 'comparison-driver' && (!account.launchComparison || account.launchComparison.mode !== 'launch-only' - || !['bun', 'node'].includes(account.launchComparison.runtime) - || account.launchComparison.executable !== path.join(work, 'bin', account.launchComparison.runtime) - || ![account.launchComparison.executableSha256, account.launchComparison.driverSha256, account.launchComparison.helpersSha256] - .every(value => /^[a-f0-9]{64}$/.test(value)))) throw new Error('comparison_driver_authority_missing'); - const expectedRuntime = role === 'comparison-driver' ? account.launchComparison!.executable : account.bun; - if (account.work !== work || account.configFile !== configFile || account.home !== path.join(work, 'home') - || account.temporary !== path.join(work, 'tmp') || account.snapshot !== repository || account.snapshot !== path.join(work, 'repo') - || account.bun !== path.join(work, 'bin/bun') || realpathSync(process.execPath) !== expectedRuntime - || !Number.isSafeInteger(account.uid) || account.uid < 20_000 || account.uid >= 60_000 || account.gid !== account.uid - || process.getuid?.() !== account.uid || process.geteuid?.() !== account.uid || process.getgid?.() !== account.gid - || !/^[a-z][a-z0-9]{8,24}$/.test(account.account) || !/^[A-F0-9-]{36}$/.test(account.guid) - || process.env.GSTACK_DIA_EXPECT_UID !== String(account.uid) || process.env.GSTACK_DIA_SOURCE_REVISION !== account.sourceRevision - || realpathSync(homedir()) !== account.home || realpathSync(process.env.HOME!) !== account.home - || realpathSync(process.env.RUNNER_TEMP!) !== account.temporary) throw new Error('fresh_identity_mismatch'); - for (const directory of [account.home, account.temporary, account.snapshot]) { - const entry = lstatSync(directory); - if (!entry.isDirectory() || entry.uid !== account.uid || (entry.mode & 0o022) !== 0 || realpathSync(directory) !== directory) throw new Error('fresh_directory_ownership_mismatch'); - } - if (!account.guiReadiness && (typeof account.destinationExecutable !== 'string' || !/^[a-f0-9]{64}$/.test(account.destinationSha256 ?? '') - || !account.destinationExecutable.startsWith(path.join(work, 'browser') + path.sep) - || realpathSync(account.destinationExecutable) !== account.destinationExecutable)) throw new Error('staged_executable_escape'); - return account; -} - -export function parseGuiReadiness(value: unknown, browserRootsExpected: boolean) { - const exact = (item: any, keys: string[]) => item !== null && typeof item === 'object' && !Array.isArray(item) - && Object.keys(item).length === keys.length && keys.every(key => Object.hasOwn(item, key)); - const nullableBoolean = (item: unknown) => item === null || typeof item === 'boolean'; - const result: any = value; - if (!exact(result, ['protocol', 'supported', 'identity', 'security', 'quartz', 'browserRoots']) || result.protocol !== 1 || result.supported !== true - || !exact(result.identity, ['effectiveUidMatches', 'homeMatchesRegistered']) || Object.values(result.identity).some(item => typeof item !== 'boolean') - || !exact(result.security, ['status', 'graphicAccess', 'rootSession', 'tty', 'remote']) || !Number.isInteger(result.security.status) - || result.security.status < -2_147_483_648 || result.security.status > 2_147_483_647 - || ['graphicAccess', 'rootSession', 'tty', 'remote'].some(key => result.security.status === 0 ? typeof result.security[key] !== 'boolean' : result.security[key] !== null) - || !exact(result.quartz, ['present', 'sameUid', 'loginDone', 'onConsole']) || typeof result.quartz.present !== 'boolean' - || ['sameUid', 'loginDone', 'onConsole'].some(key => !nullableBoolean(result.quartz[key])) - || (!result.quartz.present && ['sameUid', 'loginDone', 'onConsole'].some(key => result.quartz[key] !== null)) - || (result.quartz.sameUid !== true && (result.quartz.loginDone !== null || result.quartz.onConsole !== null))) throw new Error('invalid_gui_readiness_receipt'); - if (browserRootsExpected && result.identity.homeMatchesRegistered) { - if (!exact(result.browserRoots, ['chrome', 'chromium', 'arc', 'dia', 'comet', 'brave', 'edge', 'safari', 'cookies'])) throw new Error('invalid_gui_readiness_receipt'); - for (const fact of Object.values(result.browserRoots) as any[]) { - if (!exact(fact, ['state', 'kind', 'ownerMatches', 'ancestorBlocked']) || !['present', 'absent', 'unavailable'].includes(fact.state) - || ![null, 'directory', 'file', 'symlink', 'other'].includes(fact.kind) || !nullableBoolean(fact.ownerMatches) || typeof fact.ancestorBlocked !== 'boolean' - || (fact.state === 'absent' && (fact.kind !== null || fact.ownerMatches !== null || fact.ancestorBlocked)) - || (fact.state === 'present' && (fact.kind === null || typeof fact.ownerMatches !== 'boolean' || fact.ancestorBlocked)) - || (fact.kind === null && fact.ownerMatches !== null)) throw new Error('invalid_gui_readiness_receipt'); - } - } else if (result.browserRoots !== null) throw new Error('invalid_gui_readiness_receipt'); - return { ...result, usableGui: result.identity.effectiveUidMatches && result.identity.homeMatchesRegistered - && result.security.status === 0 && result.security.graphicAccess && result.quartz.present && result.quartz.sameUid === true && result.quartz.loginDone === true }; -} - -export async function runGuiReadiness(executable: string, executableSha256: string, source: string, sourceSha256: string, - browserRoots: boolean, env: Record, milliseconds = 5000, execute: typeof spawnSync = spawnSync) { - if (!Number.isFinite(milliseconds) || milliseconds < 1) throw new Error('gui_readiness_budget_exhausted'); - const deadline = performance.now() + Math.min(5000, milliseconds); - if (await sha256(executable) !== executableSha256 || await sha256(source) !== sourceSha256) throw new Error('gui_readiness_inputs_changed'); - const timeout = Math.floor(deadline - performance.now()); - if (timeout < 1) throw new Error('gui_readiness_budget_exhausted'); - const result = execute(executable, browserRoots ? ['--browser-roots'] : [], { env, encoding: 'utf8', timeout, - killSignal: 'SIGKILL', maxBuffer: 16 * 1024 }); - const execution = { exitCode: result.status, timedOut: (result.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT', - stdoutBytes: Buffer.byteLength(result.stdout || ''), stderrBytes: Buffer.byteLength(result.stderr || '') }; - if (result.error || result.status !== 0) return { available: false, reason: 'gui_readiness_probe_failed', execution }; - try { return { available: true, observation: parseGuiReadiness(JSON.parse(result.stdout), browserRoots), execution }; } - catch { return { available: false, reason: 'gui_readiness_receipt_rejected', execution }; } -} - -export function safeDiaComparisonResponse(value: unknown): boolean { - const keys = new Set(['protocol', 'purpose', 'stage', 'launchReturned', 'protocolResponded', 'ready', 'timedOut', 'error', 'samplingEnabled', - 'cleanup', 'startupPages', 'postProbePages', 'argvSha256', 'environmentSha256', 'rootCount', 'launchAttempts', 'rootsBeforeCleanup', - 'stderrBeforeCleanup', 'stderrAfterCleanup', 'rootsAfterCleanup', 'driver', 'childClosed', 'groupAbsent', 'launchSettled', 'confirmed', 'groups', 'pid', 'signalSent', - 'absenceConfirmed', 'childCloseObserved', 'failed', 'initialSignalFailure', 'reason', 'code', 'errno', 'closeObserved', 'exitCode', 'signal', - 'count', 'categories', 'truncated', 'allowed', 'admissionOpen', 'argumentsArray', 'pipeFlag', 'profileArgumentCount', 'expectedProfile', - 'detached', 'shellDisabled', 'stdioCount', 'extraPipeDescriptors', 'headlessFlag', 'blankStartupArgument', 'tcpDebuggingFlag', 'mockKeychainFlag', - 'passwordStoreFlag', 'firstRunSuppressed', 'sandboxRequired', 'sandboxDisablingFlag', 'available', 'bytesSeen', 'bytesInspected', - 'discardedLongLines', 'ended', 'reasonCounts', ...Object.keys(BROWSER_STDERR_REASONS), 'runtime', 'version', 'architecture', 'os', 'release', - 'executableSha256', 'driverSha256', 'helpersSha256', 'playwright']); - const strings = new Set(['control', 'source', 'runtime_import', 'launch', 'ownership', 'startup_pages', 'protocol_probe', 'ready', - 'probe_before_signal', 'signal', 'join_child_close', 'probe_after_signal', 'completed', 'signal_or_probe_failed', 'cleanup_deadline', - 'child_close_timeout', 'child_close_unconfirmed', 'group_still_live', 'ESRCH', 'EPERM', 'EACCES', 'EINVAL', 'ENOSYS', 'ETIMEDOUT', - 'unclassified', 'SIGABRT', 'SIGTRAP', 'SIGSEGV', 'SIGBUS', 'SIGKILL', 'SIGTERM', 'SIGILL', 'other', 'blank', 'other_about', - 'chromium_new_tab', 'chromium_onboarding', 'chromium_internal', 'dia_internal', 'extension', 'loopback_web', 'external_web', 'file', - 'data', 'other_scheme', 'invalid', 'bun', 'node', 'arm64', 'darwin', ...Object.keys(BROWSER_STDERR_REASONS), 'module_unavailable', - 'module_export_unavailable', 'module_format_error', 'launch_policy_rejected', 'ownership_unconfirmed', 'startup_page_rejected', - 'render_mismatch', 'operation_timeout', 'executable_unavailable', 'permission_denied', 'invalid_runtime_range', 'runtime_type_error', - 'target_closed', 'protocol_error', 'unclassified_browser_error']); - const safe = (item: unknown): boolean => item === null || typeof item === 'boolean' - || (typeof item === 'number' && Number.isSafeInteger(item)) - || (typeof item === 'string' && (strings.has(item) || /^[a-f0-9]{64}$/.test(item) || /^\d{1,3}(?:\.\d{1,3}){1,2}$/.test(item))) - || (Array.isArray(item) && item.length <= 64 && item.every(safe)) - || (typeof item === 'object' && !Array.isArray(item) && item !== null && Object.entries(item).every(([key, child]) => keys.has(key) && safe(child))); - return safe(value); -} - -export async function runDiaLaunchComparison(account: FreshAccount, purpose: 'control' | 'source', source?: { - assetRoot: string; executableName: string; executableSha256: string; -}, execute: typeof spawnSync = spawnSync, milliseconds = 40_000) { - const deadline = performance.now() + Math.min(40_000, milliseconds); - if (!Number.isFinite(milliseconds) || !Number.isFinite(deadline) || milliseconds < 1) throw new Error('comparison_budget_exhausted'); - const config = account.launchComparison; - if (!config || config.mode !== 'launch-only' || !['bun', 'node'].includes(config.runtime) - || config.executable !== path.join(account.work, 'bin', config.runtime)) throw new Error('comparison_driver_authority_missing'); - if (await sha256(config.executable) !== config.executableSha256 - || await sha256(path.join(account.snapshot, '.github/scripts/dia-launch-driver.mjs')) !== config.driverSha256 - || await sha256(path.join(account.snapshot, '.github/scripts/qualify-dia-macos.ts')) !== config.helpersSha256) throw new Error('comparison_driver_inputs_changed'); - const args = [...(config.runtime === 'bun' ? ['--no-env-file', '--no-install', '--no-macros', '--config=/dev/null'] : []), - path.join(account.snapshot, '.github/scripts/dia-launch-driver.mjs'), account.configFile]; - const timeout = Math.floor(deadline - performance.now()); - if (timeout < 1) throw new Error('comparison_budget_exhausted'); - const result = execute(config.executable, args, { env: account.environment, cwd: account.snapshot, - input: JSON.stringify({ purpose, ...source }), encoding: 'utf8', timeout, killSignal: 'SIGKILL', maxBuffer: 64 * 1024 }); - const failed = { protocol: 1, purpose, ready: false, launchReturned: false, error: 'driver_exchange_failed', - cleanup: { confirmed: false }, supervisor: { closed: !result.error && result.status !== null, exitCode: result.status, - timedOut: (result.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT', stderrBytes: Buffer.byteLength(result.stderr || '') } }; - if (result.error || result.status !== 0) return failed; - try { - const response = JSON.parse(result.stdout); - const keys = ['protocol', 'purpose', 'stage', 'launchReturned', 'protocolResponded', 'ready', 'timedOut', 'error', 'samplingEnabled', 'cleanup', 'startupPages', 'postProbePages', - 'argvSha256', 'environmentSha256', 'rootCount', 'launchAttempts', 'rootsBeforeCleanup', 'stderrBeforeCleanup', 'stderrAfterCleanup', 'rootsAfterCleanup', 'driver']; - if (!response || !safeDiaComparisonResponse(response) || Object.keys(response).some(key => !keys.includes(key)) || response.protocol !== 1 || response.purpose !== purpose - || response.samplingEnabled !== false || response.driver?.runtime !== config.runtime - || response.driver?.version !== (config.runtime === 'bun' ? '1.4.2' : '24.18.0') || response.driver?.architecture !== 'arm64' - || response.driver?.os !== 'darwin' || response.driver?.playwright !== '1.62.1' - || response.driver?.executableSha256 !== config.executableSha256 || response.driver?.driverSha256 !== config.driverSha256 - || response.driver?.helpersSha256 !== config.helpersSha256 || typeof response.ready !== 'boolean' - || typeof response.launchReturned !== 'boolean' || typeof response.cleanup?.confirmed !== 'boolean') return failed; - if (response.ready && (response.launchReturned !== true || response.protocolResponded !== true - || response.startupPages?.allowed !== true || response.postProbePages?.allowed !== true)) return failed; - if (response.cleanup.confirmed && (response.cleanup.childClosed !== true || response.cleanup.groupAbsent !== true || response.cleanup.launchSettled !== true || response.rootCount !== 1 - || response.cleanup.groups?.length !== 1 || response.cleanup.groups[0].absenceConfirmed !== true || response.cleanup.groups[0].childCloseObserved !== true - || response.rootsAfterCleanup?.length !== 1 || response.rootsAfterCleanup[0].closeObserved !== true - || response.launchAttempts?.length !== 1 || response.launchAttempts[0].sandboxRequired !== true || response.launchAttempts[0].sandboxDisablingFlag !== false - || response.launchAttempts[0].pipeFlag !== true || !/^[a-f0-9]{64}$/.test(response.argvSha256) || !/^[a-f0-9]{64}$/.test(response.environmentSha256))) return failed; - return { ...response, supervisor: { closed: true, exitCode: 0, timedOut: false, stderrBytes: Buffer.byteLength(result.stderr || '') } }; - } catch { return failed; } -} - -export function createOwnedDiaProfile(home: string) { - const uid = process.getuid?.(); - for (const directory of [home, path.join(home, 'Library'), path.join(home, 'Library/Application Support')]) { - try { lstatSync(directory); } catch (error: any) { - if (error.code !== 'ENOENT' || directory === home) throw error; - mkdirSync(directory, { mode: 0o700 }); - } - const info = lstatSync(directory); - if (!info.isDirectory() || info.uid !== uid || (info.mode & 0o022) !== 0 || realpathSync(directory) !== directory) throw new Error('unsafe_profile_ancestor'); - } - const browserRoot = path.join(home, 'Library/Application Support/Dia'); - mkdirSync(browserRoot, { mode: 0o700 }); - const profile = path.join(browserRoot, 'User Data'); - mkdirSync(profile, { mode: 0o700 }); - const info = lstatSync(profile, { bigint: true }); - const nonce = randomBytes(32).toString('hex'); - writeFileSync(path.join(profile, '.gstack-dia-owner'), nonce, { mode: 0o600, flag: 'wx' }); - return { home, profile, uid, dev: info.dev, ino: info.ino, nonce }; -} - -export function assertOwnedDiaProfile(ownership: ReturnType) { - const { home, profile, uid, dev, ino, nonce } = ownership; - if (uid === undefined || uid !== process.getuid?.() || profile !== path.join(home, 'Library/Application Support/Dia/User Data') - || !/^[a-f0-9]{64}$/.test(nonce)) throw new Error('profile_ownership_unconfirmed'); - for (const directory of [home, path.join(home, 'Library'), path.join(home, 'Library/Application Support'), path.dirname(profile), profile]) { - const info = lstatSync(directory); - if (!info.isDirectory() || info.uid !== uid || (info.mode & 0o022) !== 0 || realpathSync(directory) !== directory) throw new Error('profile_ownership_unconfirmed'); - } - const info = lstatSync(profile, { bigint: true }); - if (info.dev !== dev || info.ino !== ino) throw new Error('profile_ownership_unconfirmed'); - const fd = openSync(path.join(profile, '.gstack-dia-owner'), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); - try { - const marker = fstatSync(fd); - if (!marker.isFile() || marker.uid !== uid || marker.nlink !== 1 || (marker.mode & 0o077) !== 0 || marker.size !== 64) throw new Error('profile_ownership_unconfirmed'); - const buffer = Buffer.alloc(65); - if (readSync(fd, buffer, 0, 65, 0) !== 64 || buffer.subarray(0, 64).toString() !== nonce) throw new Error('profile_ownership_unconfirmed'); - const after = fstatSync(fd); - if (after.size !== marker.size || after.mtimeMs !== marker.mtimeMs || after.ctimeMs !== marker.ctimeMs) throw new Error('profile_ownership_unconfirmed'); - } finally { closeSync(fd); } -} - -export function removeOwnedDiaProfile(ownership: ReturnType, browsersStopped: boolean) { - if (!browsersStopped) throw new Error('owned_browsers_not_stopped'); - assertOwnedDiaProfile(ownership); - rmSync(ownership.profile, { recursive: true }); - try { lstatSync(ownership.profile); } catch (error: any) { if (error.code === 'ENOENT') return; throw error; } - throw new Error('owned_profile_still_present'); -} - -export function assertDiaSocketPath(sourceProfile: string): void { - if (Buffer.byteLength(path.join(sourceProfile, 'SingletonSocket')) >= 100) throw new Error('fixture_socket_path_too_long'); -} - -export function inspectMachOArchitectures(file: string, milliseconds = 10_000) { - if (!Number.isFinite(milliseconds) || milliseconds < 1) throw new Error('macho_read_budget_exhausted'); - const deadline = performance.now() + milliseconds; - if (realpathSync(file) !== file) throw new Error('unsafe_macho_file'); - const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); - let bytesRead = 0; - try { - const before = fstatSync(fd, { bigint: true }); - if (!before.isFile() || before.size < 8n || before.size > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('unsafe_macho_file'); - const size = Number(before.size); - const read = (offset: number, length: number) => { - if (performance.now() >= deadline || bytesRead + length > 4096) throw new Error('macho_read_budget_exhausted'); - if (!Number.isSafeInteger(offset) || offset < 0 || offset > size - length) throw new Error('invalid_macho_header'); - const buffer = Buffer.alloc(length); - if (readSync(fd, buffer, 0, length, offset) !== length) throw new Error('invalid_macho_header'); - bytesRead += length; - return buffer; - }; - const thin = (offset: number, sliceSize: number, expectedCpu?: number, expectedSubtype?: number) => { - const magic = read(offset, 4).readUInt32BE(0); - const little = magic === 0xcefaedfe || magic === 0xcffaedfe; - const wide = magic === 0xfeedfacf || magic === 0xcffaedfe; - if (![0xfeedface, 0xcefaedfe, 0xfeedfacf, 0xcffaedfe].includes(magic)) throw new Error('invalid_macho_header'); - const headerSize = wide ? 32 : 28; - if (sliceSize < headerSize) throw new Error('invalid_macho_header'); - const header = read(offset, headerSize); - const word = (at: number) => little ? header.readUInt32LE(at) : header.readUInt32BE(at); - const cpu = word(4); - const subtype = word(8); - if ((expectedCpu !== undefined && cpu !== expectedCpu) || (expectedSubtype !== undefined && subtype !== expectedSubtype) - || Boolean(cpu & 0x01000000) !== wide || word(12) !== 2 || word(20) > sliceSize - headerSize - || word(16) * 8 > word(20) || word(20) % (wide ? 8 : 4) !== 0) throw new Error('invalid_macho_header'); - const names: Record = { '7:3': 'i386', '16777223:3': 'x86_64', '16777223:8': 'x86_64h', - '16777228:0': 'arm64', '16777228:1': 'arm64v8', '16777228:2': 'arm64e' }; - const architecture = names[cpu + ':' + (subtype & 0x00ffffff)]; - if (!architecture) throw new Error('unsupported_macho_architecture'); - return architecture; - }; - const header = read(0, 8); - const magic = header.readUInt32BE(0); - const fat = [0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic); - const architectures: string[] = []; - let format = 'thin'; - if (!fat) architectures.push(thin(0, size)); - else { - const little = magic === 0xbebafeca || magic === 0xbfbafeca; - const wide = magic === 0xcafebabf || magic === 0xbfbafeca; - format = wide ? 'fat64' : 'fat32'; - const count = little ? header.readUInt32LE(4) : header.readUInt32BE(4); - if (count < 1 || count > 32) throw new Error('invalid_macho_header'); - const entrySize = wide ? 32 : 20; - const tableEnd = 8 + count * entrySize; - const table = read(8, count * entrySize); - const word = (at: number) => little ? table.readUInt32LE(at) : table.readUInt32BE(at); - const wideWord = (at: number) => little ? table.readBigUInt64LE(at) : table.readBigUInt64BE(at); - const ranges: Array<{ offset: bigint; end: bigint }> = []; - for (let index = 0; index < count; index++) { - const at = index * entrySize; - const offset = wide ? wideWord(at + 8) : BigInt(word(at + 8)); - const sliceSize = wide ? wideWord(at + 16) : BigInt(word(at + 12)); - const align = word(at + (wide ? 24 : 16)); - const end = offset + sliceSize; - if (offset < BigInt(tableEnd) || sliceSize < 28n || end > before.size || align > 63 - || offset % (1n << BigInt(align)) !== 0n || (wide && word(at + 28) !== 0) - || ranges.some(range => offset < range.end && end > range.offset)) throw new Error('invalid_macho_header'); - ranges.push({ offset, end }); - const architecture = thin(Number(offset), Number(sliceSize), word(at), word(at + 4)); - if (architectures.includes(architecture)) throw new Error('invalid_macho_header'); - architectures.push(architecture); - } - } - const after = fstatSync(fd, { bigint: true }); - const current = lstatSync(file, { bigint: true }); - if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size - || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs || current.dev !== before.dev || current.ino !== before.ino - || !current.isFile() || realpathSync(file) !== file) throw new Error('macho_changed_during_inspection'); - if (performance.now() >= deadline) throw new Error('macho_read_budget_exhausted'); - return { method: 'bounded_macho_headers', format, architectures, slices: architectures.length, bytesRead }; - } finally { closeSync(fd); } -} - -export function writePrivateReceipt(file: string, value: unknown, replace = false): void { - const directory = path.dirname(file); - const owner = process.getuid?.(); - const parent = lstatSync(directory); - if (!path.isAbsolute(file) || path.resolve(file) !== file || realpathSync(directory) !== directory - || !parent.isDirectory() || parent.uid !== owner || (parent.mode & 0o022) !== 0) throw new Error('unsafe_receipt_directory'); - if (replace && existsSync(file)) { - const previous = lstatSync(file); - if (!previous.isFile() || previous.uid !== owner || realpathSync(file) !== file || (previous.mode & 0o022) !== 0) throw new Error('unsafe_receipt_replacement'); - } - const text = JSON.stringify(value, null, 2) + '\n'; - if (Buffer.byteLength(text) > 1024 * 1024) throw new Error('receipt_too_large'); - const temporary = path.join(directory, '.dia-receipt-' + randomBytes(12).toString('hex') + '.json'); - writeFileSync(temporary, text, { mode: 0o600, flag: 'wx' }); - try { - if (replace) renameSync(temporary, file); - else linkSync(temporary, file); - } finally { - if (existsSync(temporary)) unlinkSync(temporary); - } -} - -export function validateQualificationHost(env: NodeJS.ProcessEnv, platform = process.platform, architecture = process.arch): void { - if (platform !== 'darwin' || architecture !== 'arm64' || env.CI !== 'true' || env.GITHUB_ACTIONS !== 'true' - || env.RUNNER_ENVIRONMENT !== 'github-hosted' || env.RUNNER_OS !== 'macOS' || env.RUNNER_ARCH !== 'ARM64' - || env.GSTACK_DIA_NATIVE_QUALIFY !== '1' || !env.RUNNER_TEMP || !env.GITHUB_RUN_ID || !env.GITHUB_RUN_ATTEMPT) { - throw new Error('disposable_arm64_macos_ci_required'); - } -} - -export function nativeDiaLaunchOptions(executablePath: string, env: Record) { - return { - executablePath, env, headless: true, chromiumSandbox: true, timeout: 30_000, serviceWorkers: 'block' as const, - ignoreDefaultArgs: ['--use-mock-keychain', '--password-store=basic', '--no-first-run'], - args: ['--disable-sync', '--no-default-browser-check', '--profile-directory=Default'], - handleSIGINT: false, handleSIGTERM: false, handleSIGHUP: false, - }; -} - -export function hasSandboxDisablingArgument(args: string[]): boolean { - return args.some((arg, index) => /^--(?:no-sandbox|no-zygote-sandbox|disable-(?:[a-z0-9-]+-)?sandbox|single-process|in-process-gpu)(?:=|$)/i.test(arg) - || (/^--disable-features(?:=|$)/i.test(arg) && /sandbox/i.test(arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : args[index + 1] ?? ''))); -} - -export function allowedFixturePage(url: string, origin: string): boolean { - if (url === 'about:blank') return true; - try { const page = new URL(url); return !page.username && !page.password && page.origin === origin && new URL(origin).hostname === '127.0.0.1'; } - catch { return false; } -} - -export function browserStartupCategory(value: string): string { - if (value === 'about:blank') return 'blank'; - try { - const url = new URL(value); - if (url.protocol === 'about:') return 'other_about'; - if (url.protocol === 'chrome:' || url.protocol === 'chrome-untrusted:') { - if (['newtab', 'new-tab-page'].includes(url.hostname)) return 'chromium_new_tab'; - if (['intro', 'welcome', 'first-run', 'signin', 'sync-confirmation', 'profile-picker'].includes(url.hostname)) return 'chromium_onboarding'; - return 'chromium_internal'; - } - if (url.protocol === 'dia:') return 'dia_internal'; - if (url.protocol === 'chrome-extension:') return 'extension'; - if (['http:', 'https:'].includes(url.protocol)) return ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname) ? 'loopback_web' : 'external_web'; - if (url.protocol === 'file:') return 'file'; - if (url.protocol === 'data:') return 'data'; - return 'other_scheme'; - } catch { return 'invalid'; } -} - -const BROWSER_STDERR_REASONS = { - default_profile_policy: /DevTools remote debugging requires a non-default data directory\./i, - debugging_pipe_unavailable: /Remote debugging pipe file descriptors are not open\./i, - keychain_interaction_disallowed: /\berrSecInteractionNotAllowed\b|User interaction is not allowed\./, - keychain_interaction_required: /\berrSecInteractionRequired\b/, - keychain_access_failed: /\berrSecAuthFailed\b|KeychainReauthorize failed\. Cannot retrieve item\./, - dynamic_library_error: /Library not loaded:|dyld(?:\[\d+\])?:|no suitable image found/i, - code_signing_error: /code signature (?:invalid|not valid)|mapped file has no cdhash|library load disallowed by system policy|CODESIGNING/i, - graphics_or_bootstrap_error: /(?:CGSConnection|WindowServer|bootstrap_check_in)[^\r\n]{0,160}(?:failed|failure|denied|invalid)|Failed to (?:connect to|initialize) (?:the )?WindowServer/i, - browser_profile_unavailable: /ProcessSingleton|SingletonLock|user data directory is already in use/i, -} as const; - -type BrowserStderrReason = keyof typeof BROWSER_STDERR_REASONS; - -export function browserStderrReasons(text: string): BrowserStderrReason[] { - const bounded = text.slice(0, 65_536); - return (Object.keys(BROWSER_STDERR_REASONS) as BrowserStderrReason[]).filter(reason => BROWSER_STDERR_REASONS[reason].test(bounded)); -} - -export function createBrowserStderrCapture() { - const reasonCounts = Object.fromEntries(Object.keys(BROWSER_STDERR_REASONS).map(reason => [reason, 0])) as Record; - let bytesSeen = 0; - let bytesInspected = 0; - let pending = ''; - let droppingLine = false; - let discardedLongLines = 0; - let ended = false; - const classify = (line: string) => { for (const reason of browserStderrReasons(line)) reasonCounts[reason]++; }; - return { - consume(chunk: Buffer | string) { - const size = Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk); - bytesSeen = Math.min(Number.MAX_SAFE_INTEGER, bytesSeen + size); - const remaining = 65_536 - bytesInspected; - if (remaining < 1) return; - const buffer = Buffer.isBuffer(chunk) ? chunk.subarray(0, remaining) : Buffer.from(chunk.slice(0, remaining)).subarray(0, remaining); - bytesInspected += buffer.length; - for (const character of buffer.toString('utf8')) { - if (character === '\n') { - if (!droppingLine) classify(pending); - pending = ''; - droppingLine = false; - } else if (!droppingLine) { - pending += character; - if (pending.length >= 4096) { - classify(pending); - pending = ''; - droppingLine = true; - discardedLongLines++; - } - } - } - }, - end() { if (!droppingLine) classify(pending); pending = ''; ended = true; }, - clear() { pending = ''; }, - snapshot() { - const counts = { ...reasonCounts }; - if (!droppingLine) for (const reason of browserStderrReasons(pending)) counts[reason]++; - return { bytesSeen, bytesInspected, truncated: bytesSeen > bytesInspected || discardedLongLines > 0, discardedLongLines, ended, reasonCounts: counts }; - }, - }; -} - -export function browserOperationTimedOut(error: unknown): boolean { - return error instanceof Error && (error.name === 'TimeoutError' - || ['native_operation_timed_out', 'operation_timeout', 'qualification_budget_exhausted'].includes(error.message)); -} - -export function browserPreflightError(error: unknown, stderrReasons: readonly BrowserStderrReason[] = []): string { - const message = error instanceof Error ? error.message : ''; - const code = (error as { code?: string } | null)?.code; - if (['MODULE_NOT_FOUND', 'ERR_MODULE_NOT_FOUND'].includes(code ?? '')) return 'module_unavailable'; - if (code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') return 'module_export_unavailable'; - if (['ERR_REQUIRE_ESM', 'ERR_UNKNOWN_FILE_EXTENSION', 'ERR_INVALID_PACKAGE_CONFIG'].includes(code ?? '')) return 'module_format_error'; - if (/\bbrowser_launch_policy_rejected\b/.test(message)) return 'launch_policy_rejected'; - if (['background_browser_ownership_failed', 'source_process_ownership_unconfirmed', 'destination_process_ownership_unconfirmed'].includes(message)) return 'ownership_unconfirmed'; - if (['background_browser_startup_page_rejected', 'onboarding_or_external_page'].includes(message)) return 'startup_page_rejected'; - if (message === 'background_browser_render_failed') return 'render_mismatch'; - const causalReasons = [...stderrReasons, ...browserStderrReasons(message)]; - const causal = (Object.keys(BROWSER_STDERR_REASONS) as BrowserStderrReason[]).find(reason => causalReasons.includes(reason)); - if (causal) return causal; - if (browserOperationTimedOut(error)) return 'operation_timeout'; - if (code === 'ENOENT' || /Executable doesn't exist|spawn .* ENOENT/.test(message)) return 'executable_unavailable'; - if (['EACCES', 'EPERM'].includes(code ?? '') || /spawn .* EACCES/.test(message)) return 'permission_denied'; - if (code === 'ERR_OUT_OF_RANGE' || (error instanceof Error && error.name === 'RangeError')) return 'invalid_runtime_range'; - if (error instanceof Error && error.name === 'TypeError') return 'runtime_type_error'; - if (/ProcessSingleton|SingletonLock|profile.*in use/i.test(message)) return 'browser_profile_unavailable'; - if (/WindowServer|CGSConnection|audit session|bootstrap_check_in/i.test(message)) return 'graphics_or_bootstrap_error'; - if (/Target page, context or browser has been closed|Browser closed|Target closed/.test(message)) return 'target_closed'; - if (/Protocol error/.test(message)) return 'protocol_error'; - return 'unclassified_browser_error'; -} - -export function macosCompatibility(plist: unknown, host: string) { - const properties = plist && typeof plist === 'object' ? plist as Record : {}; - const version = (value: unknown) => typeof value === 'string' && /^\d{1,3}(?:\.\d{1,3}){0,2}$/.test(value.trim()) ? value.trim() : null; - const hostVersion = version(host); - const minimumSystemVersion = version(properties.LSMinimumSystemVersion); - const minimumArm64Version = version(properties.LSMinimumSystemVersionByArchitecture?.arm64); - const requirements = [minimumSystemVersion, minimumArm64Version].filter((value): value is string => value !== null); - const malformed = (properties.LSMinimumSystemVersion !== undefined && minimumSystemVersion === null) - || (properties.LSMinimumSystemVersionByArchitecture !== undefined && (!properties.LSMinimumSystemVersionByArchitecture - || typeof properties.LSMinimumSystemVersionByArchitecture !== 'object' || Array.isArray(properties.LSMinimumSystemVersionByArchitecture))) - || (properties.LSMinimumSystemVersionByArchitecture?.arm64 !== undefined && minimumArm64Version === null); - const compatible = hostVersion && requirements.length && !malformed ? requirements.every(minimum => { - const actual = hostVersion.split('.').map(Number); - const required = minimum.split('.').map(Number); - for (let index = 0; index < 3; index++) { - const difference = (actual[index] ?? 0) - (required[index] ?? 0); - if (difference) return difference > 0; - } - return true; - }) : null; - return { hostVersion, minimumSystemVersion, minimumArm64Version, compatible }; -} - -export function browserStartupFacts(urls: string[], origin: string) { - return { count: urls.length, categories: urls.slice(0, 64).map(browserStartupCategory), truncated: urls.length > 64, - allowed: urls.every(url => allowedFixturePage(url, origin)) }; -} - -export function browserRootFacts(children: Array<{ pid: number; closeObserved?: boolean; process: { exitCode: number | null; signalCode: string | null } }>) { - return children.slice(0, 64).map(child => ({ pid: child.pid, exitCode: Number.isInteger(child.process.exitCode) ? child.process.exitCode : null, - ...(child.closeObserved === undefined ? {} : { closeObserved: child.closeObserved }), - signal: child.process.signalCode == null ? null - : ['SIGABRT', 'SIGTRAP', 'SIGSEGV', 'SIGBUS', 'SIGKILL', 'SIGTERM', 'SIGILL'].includes(child.process.signalCode) ? child.process.signalCode : 'other' })); -} - -export function browserCleanupError(error: unknown) { - const code = (error as { code?: unknown } | null)?.code; - const errno = (error as { errno?: unknown } | null)?.errno; - const reason = error instanceof Error && error.message === 'owned_process_group_still_live' ? 'group_still_live' - : error instanceof Error && error.message === 'cleanup_budget_exhausted' ? 'cleanup_deadline' - : error instanceof Error && error.message === 'operation_timeout' ? 'child_close_timeout' - : error instanceof Error && error.message === 'owned_child_close_unconfirmed' ? 'child_close_unconfirmed' : 'signal_or_probe_failed'; - return { reason, code: typeof code === 'string' && ['ESRCH', 'EPERM', 'EACCES', 'EINVAL', 'ENOSYS', 'ETIMEDOUT'].includes(code) ? code : 'unclassified', - errno: typeof errno === 'number' && Number.isSafeInteger(errno) ? errno : null }; -} - -export function browserGroupFacts(output: string, uid: number, pgid: number) { - if (!Number.isSafeInteger(uid) || uid < 0 || !Number.isSafeInteger(pgid) || pgid < 1) throw new Error('invalid_group_snapshot_target'); - const processes: Array<{ pid: number; ppid: number; state: string }> = []; - let foreignUidCount = 0; - for (const line of output.split('\n').filter(line => line.trim())) { - const fields = line.match(/^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s*$/); - if (!fields) throw new Error('invalid_group_snapshot'); - if (Number(fields[4]) !== pgid) continue; - if (Number(fields[1]) !== uid) { foreignUidCount++; continue; } - const pid = Number(fields[2]); - const ppid = Number(fields[3]); - if (!Number.isSafeInteger(pid) || pid < 1 || !Number.isSafeInteger(ppid)) throw new Error('invalid_group_snapshot'); - processes.push({ pid, ppid, state: ['I', 'R', 'S', 'T', 'U', 'Z', 'D', 'X'].includes(fields[5][0]) ? fields[5][0] : 'other' }); - } - return { available: true, count: processes.length, foreignUidCount, zombies: processes.filter(process => process.state === 'Z').length, - live: processes.filter(process => process.state !== 'Z').length, truncated: processes.length > 64, processes: processes.slice(0, 64) }; -} - -export function playwrightModuleLoadFacts(snapshot: string, error: unknown) { - const detail = error as { name?: unknown; code?: unknown; message?: unknown } | null; - const names = ['Error', 'ResolveMessage', 'BuildMessage', 'SyntaxError', 'TypeError', 'RangeError', 'TimeoutError']; - const codes = ['MODULE_NOT_FOUND', 'ERR_MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED', 'ERR_REQUIRE_ESM', 'ERR_UNKNOWN_FILE_EXTENSION', - 'ERR_INVALID_PACKAGE_CONFIG', 'ENOENT', 'EACCES', 'EPERM', 'ERR_OUT_OF_RANGE']; - const message = typeof detail?.message === 'string' ? detail.message : ''; - const module = ['playwright', 'playwright-core', './lib/bootstrap', './lib/coreBundle'] - .find(name => message.includes("'" + name + "'") || message.includes('"' + name + '"')) ?? 'unclassified'; - const files = Object.fromEntries(['playwright/package.json', 'playwright/index.mjs', 'playwright/index.js', 'playwright-core/package.json', - 'playwright-core/index.mjs', 'playwright-core/index.js', 'playwright-core/lib/bootstrap.js', 'playwright-core/lib/coreBundle.js'].map(name => { - const file = path.join(snapshot, 'node_modules', name); - const facts = { exists: false, readable: false, ownedByCurrentUid: false, insideSnapshot: false }; - try { - const info = lstatSync(file); - facts.exists = true; - facts.ownedByCurrentUid = info.uid === process.getuid?.(); - facts.insideSnapshot = realpathSync(file).startsWith(realpathSync(snapshot) + path.sep); - accessSync(file, constants.R_OK); - facts.readable = true; - } catch {} - return [name, facts]; - })); - return { errorType: typeof detail?.name === 'string' && names.includes(detail.name) ? detail.name : 'unclassified', - errorCode: typeof detail?.code === 'string' && codes.includes(detail.code) ? detail.code : 'unclassified', requestedModule: module, files }; -} - -export function parseKeychainPaths(output: string, allowEmpty = false): string[] { - const paths = output.split('\n').map(line => line.trim()).filter(Boolean).map(line => { - const value = JSON.parse(line); - if (typeof value !== 'string' || !path.isAbsolute(value)) throw new Error('invalid_keychain_snapshot'); - return value; - }); - if (!paths.length && !allowEmpty) throw new Error('empty_keychain_snapshot'); - return paths; -} - -export function parseDefaultKeychain(result: { status: number | null; stdout: string; stderr: string; error?: unknown }): string[] { - if (!result.error && result.status === 1 && !result.stdout.trim() - && /^security: SecKeychainCopy(?:DomainDefault user|Default): A default keychain could not be found\.$/.test(result.stderr.trim())) return []; - if (result.error || result.status !== 0 || (!result.stdout.trim() && result.stderr.trim())) throw new Error('user_default_keychain_unavailable'); - const paths = parseKeychainPaths(result.stdout, true); - if (paths.length > 1) throw new Error('invalid_default_keychain_snapshot'); - return paths; -} - -export function prepareKeychainHome(home: string, uid = process.getuid?.()) { - if (uid === undefined || realpathSync(home) !== home || !lstatSync(home).isDirectory() || lstatSync(home).uid !== uid) throw new Error('keychain_home_unsafe'); - const directories = ['Library', 'Library/Preferences', 'Library/Keychains']; - const before = Object.fromEntries(directories.map(name => [name, existsSync(path.join(home, name))])); - for (const name of directories) { - const directory = path.join(home, name); - if (!existsSync(directory)) mkdirSync(directory, { mode: 0o700 }); - const info = lstatSync(directory); - if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== uid || (info.mode & 0o022) !== 0 || realpathSync(directory) !== directory) throw new Error('keychain_home_unsafe'); - } - return { before, directoriesReady: true }; -} - -type KeychainResult = { status: number | null; stdout: string; stderr: string; error?: unknown }; -type KeychainExecutor = (args: string[], timeout: number) => KeychainResult; - -function keychainCommand(env: Record, args: string[], deadline: number, execute?: KeychainExecutor, onDispatch?: () => void): KeychainResult { - const timeout = Math.floor(deadline - performance.now()); - if (!Number.isFinite(timeout) || timeout < 1) throw new Error('user_keychain_probe_timeout'); - onDispatch?.(); - return execute ? execute(args, timeout) : spawnSync('/usr/bin/security', args, { - env, encoding: 'utf8', timeout, maxBuffer: 1024 * 1024, - }); -} - -function requireOwnedKeychains(paths: string[], allowedRoots: string[]) { - for (const keychain of paths) { - const resolved = existsSync(keychain) ? realpathSync(keychain) : path.resolve(keychain); - if (!allowedRoots.some(root => resolved.startsWith(realpathSync(root) + path.sep))) throw new Error('keychain_outside_owned_home_refused'); - } -} - -export function captureUserKeychains(env: Record, allowedRoots: string[], milliseconds = 10_000, - execute?: KeychainExecutor) { - const deadline = performance.now() + milliseconds; - const probe = (args: string[]) => keychainCommand(env, args, deadline, execute); - const search = probe(['list-keychains', '-d', 'user']); - if (search.error || search.status !== 0 || (!search.stdout.trim() && search.stderr.trim())) throw new Error('user_keychain_search_unavailable'); - const snapshot = { search: parseKeychainPaths(search.stdout, true), default: parseDefaultKeychain(probe(['default-keychain', '-d', 'user'])) }; - requireOwnedKeychains([...snapshot.search, ...snapshot.default], allowedRoots); - return snapshot; -} - -export function observeFixtureKeychain(env: Record, allowedRoots: string[], keychain: string, expected: string, - milliseconds = 10_000, execute?: KeychainExecutor, service: 'Gstack Native Probe' | 'Dia Safe Storage' = 'Gstack Native Probe') { - requireOwnedKeychains([keychain], allowedRoots); - const info = lstatSync(keychain); - if (!info.isFile() || info.isSymbolicLink() || info.uid !== process.getuid?.()) throw new Error('fixture_keychain_not_owned'); - const expectedPath = realpathSync(keychain); - const deadline = performance.now() + milliseconds; - const result = { searchCount: null as number | null, searchPathMatches: false, defaultCount: null as number | null, - defaultPathMatches: false, explicitReadAttempted: false, explicitReadSucceeded: false, explicitReadMatches: false, - lookupReadAttempted: false, lookupReadSucceeded: false, lookupReadMatches: false, - preferencesDirectoryExists: existsSync(path.join(env.HOME, 'Library/Preferences')), - preferencesFileExists: existsSync(path.join(env.HOME, 'Library/Preferences/com.apple.security.plist')) }; - try { - const search = keychainCommand(env, ['list-keychains', '-d', 'user'], deadline, execute); - if (search.error || search.status !== 0 || (!search.stdout.trim() && search.stderr.trim())) throw new Error('search_unavailable'); - const paths = parseKeychainPaths(search.stdout, true); - result.searchCount = paths.length; - requireOwnedKeychains(paths, allowedRoots); - result.searchPathMatches = paths.length === 1 && realpathSync(paths[0]) === expectedPath; - } catch {} - try { - const paths = parseDefaultKeychain(keychainCommand(env, ['default-keychain', '-d', 'user'], deadline, execute)); - result.defaultCount = paths.length; - requireOwnedKeychains(paths, allowedRoots); - result.defaultPathMatches = paths.length === 1 && realpathSync(paths[0]) === expectedPath; - } catch {} - try { - const read = keychainCommand(env, ['find-generic-password', '-s', service, '-w', keychain], deadline, execute, - () => { result.explicitReadAttempted = true; }); - result.explicitReadSucceeded = !read.error && read.status === 0; - result.explicitReadMatches = result.explicitReadSucceeded && read.stdout.trim() === expected; - } catch {} - if (service === 'Dia Safe Storage' && result.searchPathMatches && result.defaultPathMatches && result.explicitReadMatches) { - try { - const read = keychainCommand(env, ['find-generic-password', '-s', service, '-w'], deadline, execute, - () => { result.lookupReadAttempted = true; }); - result.lookupReadSucceeded = !read.error && read.status === 0; - result.lookupReadMatches = result.lookupReadSucceeded && read.stdout.trim() === expected; - } catch {} - } - return result; -} - -export function observeDiaKeychainEnvironments(environments: { keychainHome: Record; profileHome: Record }, - allowedRoots: string[], keychain: string, expected: string, milliseconds = 20_000, - execute?: (env: Record, args: string[], timeout: number) => KeychainResult) { - const deadline = performance.now() + milliseconds; - const environmentsObserved: Record | { unavailable: true }> = {}; - for (const label of ['keychainHome', 'profileHome'] as const) { - const env = environments[label]; - try { - environmentsObserved[label] = observeFixtureKeychain(env, allowedRoots, keychain, expected, Math.min(10_000, deadline - performance.now()), - execute ? (args, timeout) => execute(env, args, timeout) : undefined, 'Dia Safe Storage'); - } catch { environmentsObserved[label] = { unavailable: true }; } - } - let firstFailure: { environment: 'keychainHome' | 'profileHome'; check: 'search_path' | 'explicit_read' } | undefined; - for (const label of ['keychainHome', 'profileHome'] as const) { - const facts = environmentsObserved[label]; - if (!('searchPathMatches' in facts) || !facts.searchPathMatches) firstFailure ??= { environment: label, check: 'search_path' }; - } - const keychainFacts = environmentsObserved.keychainHome; - if (!('explicitReadMatches' in keychainFacts) || !keychainFacts.explicitReadMatches) firstFailure ??= { environment: 'keychainHome', check: 'explicit_read' }; - return { environments: environmentsObserved, firstFailure }; -} - -export function fixtureKeychainRestoreCommands(snapshot: { search: string[]; default: string[] }, keychain: string, created: boolean): string[][] { - if (created && [...snapshot.search, ...snapshot.default].some(original => path.resolve(original) === path.resolve(keychain))) throw new Error('fixture_keychain_not_fresh'); - return [ - ...(snapshot.default.length ? [['default-keychain', '-d', 'user', '-s', ...snapshot.default]] : []), - ...(created ? [['delete-keychain', keychain]] : []), - ['list-keychains', '-d', 'user', '-s', ...snapshot.search], - ]; -} - -export function observeBrowserLaunches(expected: ReadonlyMap) { - const childProcess = require('node:child_process'); - const original = childProcess.spawn; - const children: Array<{ process: ChildProcess; executable: string; pid: number; closed: Promise; closeObserved: boolean; - stderr?: ReturnType }> = []; - const attempts: Array> = []; - const detachStderr: Array<() => void> = []; - let accepting = true; - childProcess.spawn = function(command: string, args: string[], options: any) { - if (!expected.has(command)) return original.call(this, command, args, options); - const argumentsArray = Array.isArray(args); - const sandboxRequired = process.platform === 'darwin'; - const sandboxDisablingFlag = argumentsArray && hasSandboxDisablingArgument(args); - attempts.push({ admissionOpen: accepting, argumentsArray, pipeFlag: argumentsArray && args.includes('--remote-debugging-pipe'), - profileArgumentCount: argumentsArray ? args.filter(arg => arg.startsWith('--user-data-dir')).length : null, - expectedProfile: argumentsArray && args.includes('--user-data-dir=' + expected.get(command)), - detached: options?.detached === true, shellDisabled: options?.shell === undefined || options.shell === false, - stdioCount: Array.isArray(options?.stdio) ? options.stdio.length : null, - extraPipeDescriptors: Array.isArray(options?.stdio) && options.stdio[3] === 'pipe' && options.stdio[4] === 'pipe', - headlessFlag: argumentsArray && args.some(arg => /^--headless(?:=|$)/.test(arg)), - blankStartupArgument: argumentsArray && args.includes('about:blank'), - tcpDebuggingFlag: argumentsArray && args.some(arg => /^--remote-debugging-port(?:=|$)/.test(arg)), - mockKeychainFlag: argumentsArray && args.some(arg => /^--use-mock-keychain(?:=|$)/.test(arg)), - passwordStoreFlag: argumentsArray && args.some(arg => /^--password-store(?:=|$)/.test(arg)), - firstRunSuppressed: argumentsArray && args.some(arg => /^--no-first-run(?:=|$)/.test(arg)), sandboxRequired, sandboxDisablingFlag }); - if (!accepting || !Array.isArray(args) || !args.includes('--remote-debugging-pipe') - || (sandboxRequired && sandboxDisablingFlag) - || args.filter(arg => arg.startsWith('--user-data-dir')).length !== 1 || !args.includes('--user-data-dir=' + expected.get(command)) - || options?.detached !== true || (options.shell !== undefined && options.shell !== false) || !Array.isArray(options?.stdio) - || options.stdio.length !== 5 || options.stdio[3] !== 'pipe' || options.stdio[4] !== 'pipe' - || args.some(arg => /^--(?:remote-debugging-port|use-mock-keychain|password-store|no-first-run)(?:=|$)/.test(arg))) { - throw new Error('browser_launch_policy_rejected'); - } - const child: ChildProcess = original.call(this, command, args, options); - if (child.pid) { - let resolveClose!: () => void; - const closed = new Promise(resolve => { resolveClose = resolve; }); - const observed = { process: child, executable: command, pid: child.pid, closed, closeObserved: false, - stderr: child.stderr ? createBrowserStderrCapture() : undefined }; - child.once('close', () => { observed.closeObserved = true; resolveClose(); }); - const stderr = observed.stderr; - if (stderr && child.stderr) { - const stream = child.stderr; - stream.on('data', stderr.consume); - stream.once('end', stderr.end); - detachStderr.push(() => { stream.off('data', stderr.consume); stream.off('end', stderr.end); stderr.clear(); }); - } - children.push(observed); - } - return child; - }; - return { children, attempts, stop() { accepting = false; }, restore() { childProcess.spawn = original; for (const detach of detachStderr) detach(); } }; -} - -export function browserStderrFacts(children: ReturnType['children']) { - return children.slice(0, 64).map(child => ({ pid: child.pid, available: Boolean(child.stderr), ...child.stderr?.snapshot() })); -} - -export async function joinOwnedBrowserClose(child: ReturnType['children'][number], deadline: number) { - const remaining = deadline - performance.now(); - if (!Number.isFinite(remaining) || remaining <= 0) throw new Error('cleanup_budget_exhausted'); - await bounded(child.closed, remaining); - if (!child.closeObserved) throw new Error('owned_child_close_unconfirmed'); -} - -export async function stopOwnedBrowserGroup(child: ReturnType['children'][number], deadline: number, - facts: Record, signal: (pid: number, signal: 0 | 'SIGKILL') => unknown = (pid, signal) => process.kill(pid, signal)) { - if (!Number.isSafeInteger(child.pid) || child.pid <= 1 || child.pid === process.pid) throw new Error('owned_browser_pid_unconfirmed'); - if (!Number.isFinite(deadline) || performance.now() >= deadline) throw new Error('cleanup_budget_exhausted'); - facts.stage = 'probe_before_signal'; - try { - signal(-child.pid, 0); - facts.stage = 'signal'; - signal(-child.pid, 'SIGKILL'); - facts.signalSent = true; - } catch (error: any) { - if (error.code !== 'ESRCH') facts.initialSignalFailure = { stage: facts.stage, ...browserCleanupError(error) }; - } - facts.stage = 'join_child_close'; - await joinOwnedBrowserClose(child, deadline); - facts.childCloseObserved = child.closeObserved; - facts.stage = 'probe_after_signal'; - while (true) { - try { signal(-child.pid, 0); } - catch (error: any) { - if (error.code !== 'ESRCH') throw error; - facts.absenceConfirmed = true; - facts.stage = 'completed'; - return; - } - const remaining = deadline - performance.now(); - if (remaining <= 0) throw new Error('owned_process_group_still_live'); - await new Promise(resolve => setTimeout(resolve, Math.min(50, remaining))); - } -} - -export async function observePendingBrowserLaunch(launch: () => Promise, observe: (deadline: number) => void, - deadline: number, delay = 10_000): Promise { - const sampleDeadline = Math.min(deadline, performance.now() + 25_000); - const timer = setTimeout(() => { - if (performance.now() + 1000 >= sampleDeadline) return; - observe(sampleDeadline); - }, delay); - try { return await launch(); } - finally { clearTimeout(timer); } -} - -export function classifyNativeWaitSample(output: string) { - const families = { - security_keychain: /\b(?:SecKeychain\w*|SecItem\w*|securityd|Security)\b|libsecurity_keychain/, - appkit_bootstrap: /\b(?:AppKit|NSApplication\w*|SkyLight|HIToolbox|CGSConnection\w*|bootstrap_\w+)\b/, - network: /\b(?:CFNetwork|NSURLSession\w*|nw_connection_\w*)\b|Network\.framework/, - runloop: /\b(?:CFRunLoop\w*|__CFRunLoop\w*|NSRunLoop\w*|mach_msg\w*|__psynch_cvwait|__ulock_wait|kevent\w*)\b/, - }; - const frameCounts = Object.fromEntries(Object.keys(families).map(name => [name, 0])); - const mainThreadFrameCounts = { ...frameCounts }; - let callGraphSeen = false; - let mainThreadSeen = false; - let mainThread = false; - let frames = 0; - const shape = { graphLines: 0, nonemptyGraphLines: 0, threadTokenLines: 0, numericPrefixLines: 0, imageAnnotatedLines: 0, - nonAsciiGraphLines: 0, unrecognizedGraphLines: 0, graphEnd: 'missing', binaryImagesSeen: /^Binary Images:/m.test(output) }; - if (Buffer.byteLength(output) > 1024 * 1024) return { available: false, reason: 'sample_output_oversized' }; - for (const line of output.split('\n')) { - if (/^Call graph:\s*$/.test(line)) { callGraphSeen = true; shape.graphEnd = 'eof'; continue; } - if (!callGraphSeen) continue; - if (/^(?:Total number in stack|Sort by top of stack|Binary Images:)/.test(line)) { - shape.graphEnd = line.startsWith('Binary Images:') ? 'binary_images' : line.startsWith('Total number') ? 'totals' : 'top_of_stack'; - break; - } - shape.graphLines++; - if (line.trim()) shape.nonemptyGraphLines++; - if (/\bThread[_\s]/.test(line)) shape.threadTokenLines++; - if (/^\s*\d+\s/.test(line)) shape.numericPrefixLines++; - if (/\(in [^)]+\)/.test(line)) shape.imageAnnotatedLines++; - if (/[^\x00-\x7f]/.test(line)) shape.nonAsciiGraphLines++; - if (/^\s*\d+\s+Thread_/.test(line)) { - mainThread = /\bcom\.apple\.main-thread\b/.test(line); - mainThreadSeen ||= mainThread; - continue; - } - if (!/^\s*[+|:! ]*\d+\s+\S/.test(line)) { if (line.trim()) shape.unrecognizedGraphLines++; continue; } - frames++; - for (const [name, pattern] of Object.entries(families)) { - if (!pattern.test(line)) continue; - frameCounts[name]++; - if (mainThread) mainThreadFrameCounts[name]++; - } - } - return { available: callGraphSeen && frames > 0, callGraphSeen, mainThreadSeen, frames, frameCounts, mainThreadFrameCounts, shape }; -} - -export function sampleOwnedDiaWait(child: ReturnType['children'][number], uid: number, expectedExecutable: string, - deadline: number, env: Record, spawn: typeof spawnSync = spawnSync) { - const result: Record = { available: false, reason: 'target_not_live_owned_child', attempted: false }; - if (child.executable !== expectedExecutable || path.basename(expectedExecutable) !== 'Dia' || !Number.isSafeInteger(child.pid) || child.pid < 1 - || child.process.pid !== child.pid || child.closeObserved || child.process.exitCode !== null || child.process.signalCode !== null - || uid !== process.getuid?.() || uid !== process.geteuid?.() || !Number.isFinite(deadline)) return result; - const until = Math.min(deadline, performance.now() + 5_000); - const timeout = (limit: number) => { - const value = Math.floor(Math.min(limit, until - performance.now())); - if (value < 1) throw new Error('sample_budget_exhausted'); - return value; - }; - try { - const identity = spawn('/bin/ps', ['-p', String(child.pid), '-o', 'uid=,pid=,ppid=,state=,ucomm='], { - env, encoding: 'utf8', timeout: timeout(2_000), maxBuffer: 16 * 1024, killSignal: 'SIGKILL', - }); - if (identity.error || identity.status !== 0 || typeof identity.stdout !== 'string') { result.reason = 'ownership_probe_unavailable'; return result; } - const row = identity.stdout.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+([IRSUTD][^\s]*)\s+Dia$/); - if (!row || Number(row[1]) !== uid || Number(row[2]) !== child.pid || Number(row[3]) !== process.pid) return result; - result.ownedLiveChildConfirmed = true; - result.attempted = true; - const sample = spawn('/usr/bin/sample', [String(child.pid), '1', '10', '-file', '/dev/stdout'], { - env, encoding: 'utf8', timeout: timeout(5_000), maxBuffer: 1024 * 1024, killSignal: 'SIGKILL', - }); - const stdout = typeof sample.stdout === 'string' ? sample.stdout : ''; - const stderr = typeof sample.stderr === 'string' ? sample.stderr : ''; - result.exitCode = sample.status; - result.stdoutBytes = Buffer.byteLength(stdout); - result.stderrBytes = Buffer.byteLength(stderr); - result.timedOut = (sample.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT'; - if (sample.error || sample.status !== 0) { - result.reason = /not permitted|permission denied|(?:unable|failed) to (?:get|obtain).*task|task_for_pid.*fail|requires root/i.test((stdout + '\n' + stderr).slice(0, 65_536)) - ? 'sampling_permission_denied' : result.timedOut ? 'sampling_timeout' : 'sampling_failed'; - return result; - } - result.waitFamilies = classifyNativeWaitSample(stdout); - result.available = result.waitFamilies.available; - result.reason = result.available ? 'sampled' : result.waitFamilies.reason ?? (!result.waitFamilies.callGraphSeen ? 'sample_call_graph_missing' - : result.waitFamilies.shape.nonemptyGraphLines === 0 ? 'sample_graph_empty' - : result.waitFamilies.shape.unrecognizedGraphLines === 0 ? 'sample_no_stack_frames' : 'sample_graph_unrecognized'); - } catch { result.reason = 'sampling_unavailable_or_budget_exhausted'; } - return result; -} - -async function sha256(file: string): Promise { - const hash = createHash('sha256'); - for await (const chunk of createReadStream(file)) hash.update(chunk); - return hash.digest('hex'); -} - -async function bounded(operation: Promise, milliseconds: number): Promise { - let timer: ReturnType; - try { - return await Promise.race([operation, new Promise((_, reject) => { - timer = setTimeout(() => reject(new Error('operation_timeout')), milliseconds); - })]); - } finally { clearTimeout(timer!); } -} - -export async function qualifyDia(isolation: { root: string; configFile: string }): Promise> { - validateQualificationHost(process.env); - const account = readFreshAccountConfiguration(isolation.configFile); - if (account.guiReadiness || !account.destinationExecutable || !account.destinationSha256) throw new Error('browser_qualification_authority_required'); - if (Bun.version !== '1.4.2' || require('playwright/package.json').version !== '1.62.1') throw new Error('pinned_runtimes_required'); - const runnerTemp = realpathSync(process.env.RUNNER_TEMP!); - const output = path.join(runnerTemp, 'dia-native-qualification.json'); - if (existsSync(output)) throw new Error('fresh_receipt_path_required'); - const root = realpathSync(isolation.root); - if (path.dirname(root) !== runnerTemp || !path.basename(root).startsWith('dia-')) throw new Error('fixture_root_unowned'); - const home = account.home; - const temporary = path.join(root, 't'); - const sourceProfile = path.join(home, 'Library/Application Support/Dia/User Data'); - const destinationProfile = path.join(root, 'd'); - const keychain = path.join(root, 'fixture.keychain-db'); - const mount = path.join(root, 'm'); - const image = path.join(root, 'Dia.dmg'); - const app = path.join(root, 'Dia.app'); - const environment = { HOME: home, PATH: '/usr/bin:/bin:/usr/sbin:/sbin', LANG: 'en_US.UTF-8', TMPDIR: temporary }; - const deadline = performance.now() + 9 * 60_000; - let cleaning = false; - let cleanupDeadline = 0; - let stage = 'fixture_preflight'; - let mounted = false; - let keychainCreated = false; - let keychainChanged = false; - let originalSearch: string[] = []; - let originalDefault: string[] = []; - let source: BrowserContext | undefined; - let destination: BrowserContext | undefined; - let observer: ReturnType | undefined; - let launchAttempts = 0; - let comparisonAttempted = false; - let comparisonSource: Record | undefined; - let profileCreationAttempted = false; - let profileOwnership: ReturnType | undefined; - let server: ReturnType | undefined; - let browserRole: 'source' | 'destination' | undefined; - const attemptStarts: Partial> = {}; - const receipt: Record = { - status: 'incomplete', reason: 'not_run', runId: process.env.GITHUB_RUN_ID, runAttempt: process.env.GITHUB_RUN_ATTEMPT, - platform: { os: 'darwin', architecture: 'arm64', release: release(), bun: Bun.version, playwright: '1.62.1' }, - isolation: { registeredHomeAtStartup: true, sharedRegisteredHome: true, registeredIdentity: false, - productionLookupMocked: false, keychainCommandHome: 'fresh_registered_home' }, - artifact: { url: DIA_DOWNLOAD }, expectedCases: 8, - cases: Object.fromEntries(['headless_without_account_interaction', 'synthetic_session_created', 'native_encrypted_cookie_persisted', - 'dia_profile_and_domain_discovered', 'native_keychain_decryption_and_verified_import', 'default_storage_preserved', - 'wrong_identity_not_verified', 'explicit_storage_reset'].map(name => [name, 'not_run'])), counts: { pass: 0, fail: 0, skip: 0 }, - coverage: { mockKeychain: false, nativeKeychainRead: false, nativePermissionPrompts: false, accountLogin: false, sync: false, browserProfileImport: false }, - browsers: { source: { stage: 'not_started', launchReturned: false }, destination: { stage: 'not_started', launchReturned: false } }, - cleanup: { ownedBrowsersStopped: false, sourceProfileRemoved: false, keychainRestored: false, mountDetached: false, fixtureRemoved: false }, - }; - const run = (command: string, args: string[], milliseconds = 10_000, env = environment) => { - const remaining = (cleaning ? cleanupDeadline : deadline) - performance.now(); - const timeout = Math.floor(Math.min(milliseconds, remaining)); - if (!Number.isFinite(timeout) || timeout < 1) throw new Error('qualification_budget_exhausted'); - const result = spawnSync(command, args, { env, encoding: 'utf8', timeout, maxBuffer: 1024 * 1024 }); - if (result.error || result.status !== 0) { - receipt[cleaning ? 'cleanupCommandFailure' : 'commandFailure'] ??= { command: path.basename(command), operation: args[0], exitCode: result.status, - timedOut: (result.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT' }; - throw new Error('command_failed'); - } - return { stdout: result.stdout.trim(), stderr: result.stderr.trim() }; - }; - const check = (name: string, passed: boolean) => { - receipt.cases[name] = passed ? 'passed' : 'failed'; - if (!passed) throw new Error('case_failed'); - }; - const within = (operation: () => Promise, milliseconds: number) => { - const remaining = deadline - performance.now(); - if (remaining <= 0) throw new Error('qualification_budget_exhausted'); - return bounded(operation(), Math.min(milliseconds, remaining)); - }; - try { - const record = parseDirectoryRecord(run('/usr/bin/dscl', ['.', '-read', '/Users/' + account.account, 'UniqueID', 'PrimaryGroupID', 'NFSHomeDirectory', 'GeneratedUID']).stdout); - if (!ownsFreshAccount(record, account)) throw new Error('fresh_registered_identity_mismatch'); - receipt.isolation.registeredIdentity = true; - for (const directory of [temporary, mount]) { - if (!existsSync(directory)) mkdirSync(directory, { mode: 0o700 }); - else if (realpathSync(directory) !== directory || !lstatSync(directory).isDirectory()) throw new Error('fixture_directory_escape'); - } - receipt.sourceSocketPathBytes = Buffer.byteLength(path.join(sourceProfile, 'SingletonSocket')); - assertDiaSocketPath(sourceProfile); - if (existsSync(sourceProfile) || existsSync(destinationProfile)) throw new Error('existing_profile_refused'); - for (const relative of ['Library/Application Support/Google/Chrome', 'Library/Application Support/Chromium', - 'Library/Application Support/Arc', 'Library/Application Support/Dia', 'Library/Application Support/Comet', - 'Library/Application Support/BraveSoftware/Brave-Browser', 'Library/Application Support/Microsoft Edge', - 'Library/Safari', 'Library/Cookies']) { - if (existsSync(path.join(home, relative))) { - receipt.preexistingState = relative; - throw new Error('preexisting_browser_state_refused'); - } - } - receipt.keychainHome = prepareKeychainHome(home); - const revision = process.env.GSTACK_DIA_SOURCE_REVISION; - if (revision && !/^[0-9a-f]{40}$/.test(revision)) throw new Error('invalid_source_revision'); - receipt.sourceRevision = revision ?? run('/usr/bin/git', ['-C', repository, 'rev-parse', 'HEAD']).stdout; - const sourceFiles = ['.github/scripts/qualify-dia-macos.ts', 'browse/src/cookie-import-browser.ts', 'browse/src/cookie-import-operation.ts', 'browse/src/cookie-database.ts', 'browse/src/cookie-auth-verification.ts', 'browse/src/cdp-bridge.ts']; - receipt.sourceHashes = Object.fromEntries(await within(() => Promise.all(sourceFiles.map(async file => [file, await sha256(path.join(repository, file))])), 10_000)); - stage = 'official_download'; - const downloaded = run('/usr/bin/curl', ['--fail', '--silent', '--show-error', '--location', '--proto', '=https', '--proto-redir', '=https', - '--connect-timeout', '20', '--max-time', '300', '--output', image, '--write-out', '%{url_effective}', DIA_DOWNLOAD], 310_000); - if (new URL(downloaded.stdout).origin !== 'https://releases.diabrowser.com') throw new Error('unexpected_download_origin'); - chmodSync(image, 0o600); - receipt.artifact.sha256 = await within(() => sha256(image), 30_000); - stage = 'signed_app_staging'; - run('/usr/bin/hdiutil', ['attach', '-readonly', '-nobrowse', '-noautoopen', '-mountpoint', mount, image], 45_000); - mounted = true; - const mountedApp = path.join(mount, 'Dia.app'); - if (!lstatSync(mountedApp).isDirectory() || !realpathSync(mountedApp).startsWith(realpathSync(mount) + path.sep)) throw new Error('mounted_app_escape'); - run('/usr/bin/ditto', ['--rsrc', '--extattr', mountedApp, app], 45_000); - run('/usr/bin/hdiutil', ['detach', mount], 15_000); - mounted = false; - if (realpathSync(app) !== app) throw new Error('staged_app_escape'); - run('/usr/bin/codesign', ['--verify', '--deep', '--strict', '--verbose=2', app], 45_000); - const signature = run('/usr/bin/codesign', ['--display', '--verbose=4', app]).stderr; - const gatekeeper = run('/usr/sbin/spctl', ['--assess', '--type', 'execute', '--verbose=4', app], 45_000).stderr; - const authority = signature.match(/^Authority=(Developer ID Application: .+)$/m)?.[1]; - const team = signature.match(/^TeamIdentifier=([A-Z0-9]{10})$/m)?.[1]; - if (!authority || !team || !gatekeeper.includes('accepted') || !gatekeeper.includes('Notarized Developer ID')) throw new Error('signer_or_notarization_unconfirmed'); - const plist = path.join(app, 'Contents/Info.plist'); - const property = (name: string) => run('/usr/bin/plutil', ['-extract', name, 'raw', '-o', '-', plist]).stdout; - const executableName = property('CFBundleExecutable'); - if (!executableName || path.basename(executableName) !== executableName) throw new Error('invalid_bundle_executable'); - const executable = realpathSync(path.join(app, 'Contents/MacOS', executableName)); - if (!executable.startsWith(realpathSync(app) + path.sep)) throw new Error('bundle_executable_escape'); - receipt.artifact = { ...receipt.artifact, version: property('CFBundleShortVersionString'), bundleId: property('CFBundleIdentifier'), authority, team, - signatureVerified: true, gatekeeperNotarized: true }; - stage = 'signed_app_architecture'; - receipt.artifact.architectureInspection = inspectMachOArchitectures(executable, Math.min(10_000, deadline - performance.now())); - receipt.artifact.architectures = receipt.artifact.architectureInspection.architectures; - if (!receipt.artifact.architectures.includes('arm64')) throw new Error('dia_arm64_binary_required'); - receipt.artifact.executableSha256 = await within(() => sha256(executable), 10_000); - stage = 'signed_app_os_compatibility'; - receipt.artifact.macosCompatibility = macosCompatibility(JSON.parse(run('/usr/bin/plutil', ['-convert', 'json', '-o', '-', plist]).stdout), - run('/usr/bin/sw_vers', ['-productVersion']).stdout); - if (receipt.artifact.macosCompatibility.compatible === false) throw new Error('source_macos_version_unsupported'); - stage = 'temporary_keychain'; - receipt.keychainStage = 'capture_original'; - const originalKeychains = captureUserKeychains(environment, [home, root]); - originalSearch = originalKeychains.search; - originalDefault = originalKeychains.default; - const keychainPassword = randomBytes(24).toString('hex'); - const fixtureKey = randomBytes(24).toString('hex'); - let setupFailure: unknown; - try { - receipt.keychainStage = 'create_fixture'; - keychainChanged = true; - run('/usr/bin/security', ['create-keychain', '-p', keychainPassword, keychain]); - keychainCreated = true; - receipt.keychainStage = 'configure_settings'; - run('/usr/bin/security', ['set-keychain-settings', '-lut', '600', keychain]); - receipt.keychainStage = 'unlock_fixture'; - run('/usr/bin/security', ['unlock-keychain', '-p', keychainPassword, keychain]); - receipt.keychainStage = 'seed_fixture'; - run('/usr/bin/security', ['add-generic-password', '-a', 'Dia', '-s', 'Dia Safe Storage', '-w', fixtureKey, '-T', executable, '-T', '/usr/bin/security', keychain]); - receipt.keychainStage = 'set_search'; - run('/usr/bin/security', ['list-keychains', '-d', 'user', '-s', keychain]); - receipt.keychainStage = 'set_default'; - run('/usr/bin/security', ['default-keychain', '-d', 'user', '-s', keychain]); - receipt.keychainStage = 'validate_environments'; - } catch (error) { setupFailure = error; } - if (keychainCreated) { - receipt.keychainObservations = observeDiaKeychainEnvironments({ keychainHome: environment, profileHome: environment }, - [home, root], keychain, fixtureKey, Math.min(20_000, deadline - performance.now())); - } - if (setupFailure !== undefined) throw setupFailure; - const keychainFailure = receipt.keychainObservations.firstFailure; - if (keychainFailure) throw new Error(keychainFailure.check === 'search_path' ? 'keychain_search_isolation_failed' : 'fixture_keychain_read_failed'); - receipt.keychainStage = 'completed'; - if (account.launchComparison) { - stage = 'diagnostic_source_launch'; - profileCreationAttempted = true; - profileOwnership = createOwnedDiaProfile(home); - assertOwnedDiaProfile(profileOwnership); - receipt.isolation.sourceProfileOwnershipConfirmed = true; - comparisonAttempted = true; - comparisonSource = await runDiaLaunchComparison(account, 'source', { assetRoot: root, executableName, executableSha256: receipt.artifact.executableSha256 }, - undefined, deadline - performance.now()); - if (!comparisonSource) throw new Error('diagnostic_source_launch_returned_no_result'); - receipt.launchComparison = { mode: 'launch-only', qualificationCredit: false, source: comparisonSource }; - receipt.browsers.source = { stage: 'delegated_comparison', launchReturned: comparisonSource.launchReturned, - timedOut: comparisonSource.timedOut ?? false, error: comparisonSource.error ?? null }; - receipt.reason = 'diagnostic_launch_comparison_only'; - return receipt; - } - delete process.env.DEBUG; - delete process.env.PWDEBUG; - browserRole = 'source'; - const sourceFacts = receipt.browsers.source; - sourceFacts.stage = 'runtime_import'; - const { chromium } = await import('playwright'); - sourceFacts.stage = 'fixture_setup'; - browserRole = undefined; - stage = 'synthetic_fixture_setup'; - const destinationExecutable = realpathSync(account.destinationExecutable); - observer = observeBrowserLaunches(new Map([[executable, sourceProfile], [destinationExecutable, destinationProfile]])); - const token = randomBytes(24).toString('hex'); - const identity = 'Synthetic Dia qualification account'; - server = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch(request) { - const url = new URL(request.url); - if (url.pathname === '/seed') return new Response('Synthetic session seeded.', { headers: { 'Content-Type': 'text/html', 'Set-Cookie': `dia_fixture_session=${token}; Path=/; HttpOnly; SameSite=Lax; Max-Age=3600` } }); - const authenticated = (request.headers.get('cookie') || '').split(';').some(value => value.trim() === `dia_fixture_session=${token}`); - return new Response(authenticated ? `
${identity}
` : '
Not signed in
', { status: authenticated ? 200 : 401, headers: { 'Content-Type': 'text/html' } }); - } }); - const origin = `http://127.0.0.1:${server.port}`; - stage = 'owned_source_profile_creation'; - profileCreationAttempted = true; - profileOwnership = createOwnedDiaProfile(home); - assertOwnedDiaProfile(profileOwnership); - receipt.isolation.sourceProfileOwnershipConfirmed = true; - stage = 'dia_headless_startup_or_onboarding'; - browserRole = 'source'; - sourceFacts.stage = 'launch'; - attemptStarts.source = observer.attempts.length; - launchAttempts++; - sourceFacts.nativeWait = { available: false, attempted: false, reason: 'launch_settled_before_sample_or_window_expired' }; - source = await observePendingBrowserLaunch( - () => within(() => chromium.launchPersistentContext(sourceProfile, nativeDiaLaunchOptions(executable, environment)), 40_000), - sampleDeadline => { - try { - const children = observer!.children.filter(child => child.executable === executable); - sourceFacts.nativeWait = children.length === 1 - ? sampleOwnedDiaWait(children[0], account.uid, executable, sampleDeadline, environment) - : { available: false, attempted: false, reason: 'source_root_ownership_unconfirmed' }; - sourceFacts.nativeWait.phase = 'launch_pending_before_timeout'; - } catch { sourceFacts.nativeWait = { available: false, attempted: false, reason: 'sampling_observer_failed' }; } - }, deadline); - sourceFacts.launchReturned = true; - sourceFacts.stage = 'ownership'; - sourceFacts.ownedRootCount = observer.children.filter(child => child.executable === executable).length; - if (observer.children.filter(child => child.executable === executable).length !== 1) throw new Error('source_process_ownership_unconfirmed'); - sourceFacts.stage = 'startup_pages'; - sourceFacts.startupPages = browserStartupFacts(source.pages().map(page => page.url()), origin); - if (!sourceFacts.startupPages.allowed) throw new Error('onboarding_or_external_page'); - sourceFacts.stage = 'route_registration'; - await within(() => source!.route('**/*', route => new URL(route.request().url()).origin === origin ? route.continue() : route.abort()), 10_000); - sourceFacts.stage = 'page_selection'; - const sourcePage = source.pages()[0] ?? await within(() => source!.newPage(), 10_000); - sourceFacts.stage = 'seed_navigation'; - const seed = await within(() => sourcePage.goto(origin + '/seed', { waitUntil: 'domcontentloaded', timeout: 10_000 }), 10_000); - sourceFacts.stage = 'seed_validation'; - sourceFacts.seedResponseStatus = seed?.status() ?? null; - sourceFacts.postNavigationPages = browserStartupFacts(source.pages().map(page => page.url()), origin); - check('headless_without_account_interaction', seed?.status() === 200 && sourcePage.url() === origin + '/seed' - && source.pages().every(page => allowedFixturePage(page.url(), origin))); - receipt.sourceBrowserVersion = source.browser()?.version(); - sourceFacts.stage = 'cookies_readback'; - const sourceCookies = await within(() => source!.cookies(origin), 10_000); - check('synthetic_session_created', sourceCookies.some(cookie => cookie.name === 'dia_fixture_session' && cookie.value === token)); - sourceFacts.stage = 'close'; - await within(() => source!.close(), 10_000); - source = undefined; - sourceFacts.stage = 'completed'; - browserRole = undefined; - stage = 'native_profile_persistence'; - assertOwnedDiaProfile(profileOwnership); - const cookieFile = path.join(sourceProfile, 'Default/Cookies'); - if (!existsSync(cookieFile) || !realpathSync(cookieFile).startsWith(sourceProfile + path.sep)) throw new Error('expected_profile_layout_missing'); - for (const metadata of ['Local State', 'Default/Preferences']) { - const file = path.join(sourceProfile, metadata); - if (existsSync(file) && !realpathSync(file).startsWith(sourceProfile + path.sep)) throw new Error('profile_metadata_escape'); - } - const { openCookieDatabase } = await import('../../browse/src/cookie-database'); - const database = openCookieDatabase(cookieFile); - try { - const rows = database.query('SELECT value, encrypted_value FROM cookies WHERE host_key = ? AND name = ?').all('127.0.0.1', 'dia_fixture_session') as any[]; - check('native_encrypted_cookie_persisted', rows.length === 1 && !rows[0].value && Buffer.from(rows[0].encrypted_value).subarray(0, 3).toString() === 'v10'); - } finally { database.close(); } - stage = 'production_import'; - const { listProfiles, listDomains } = await import('../../browse/src/cookie-import-browser'); - check('dia_profile_and_domain_discovered', listProfiles('Dia').some(profile => profile.name === 'Default') - && listDomains('Dia', 'Default').domains.some(entry => entry.domain === '127.0.0.1' && entry.count >= 1)); - browserRole = 'destination'; - const destinationFacts = receipt.browsers.destination; - destinationFacts.stage = 'launch'; - attemptStarts.destination = observer.attempts.length; - launchAttempts++; - destination = await within(() => chromium.launchPersistentContext(destinationProfile, nativeDiaLaunchOptions(destinationExecutable, environment)), 40_000); - destinationFacts.launchReturned = true; - destinationFacts.stage = 'ownership'; - destinationFacts.ownedRootCount = observer.children.filter(child => child.executable === destinationExecutable).length; - if (observer.children.filter(child => child.executable === destinationExecutable).length !== 1) throw new Error('destination_process_ownership_unconfirmed'); - destinationFacts.stage = 'startup_pages'; - destinationFacts.startupPages = browserStartupFacts(destination.pages().map(page => page.url()), origin); - destinationFacts.stage = 'page_selection'; - const target = destination.pages()[0] ?? await within(() => destination!.newPage(), 10_000); - destinationFacts.stage = 'protected_navigation'; - await within(() => target.goto(origin + '/protected', { waitUntil: 'domcontentloaded', timeout: 10_000 }), 10_000); - destinationFacts.postNavigationPages = browserStartupFacts(destination.pages().map(page => page.url()), origin); - destinationFacts.stage = 'storage_seed'; - await within(() => target.evaluate(() => { localStorage.setItem('fixture-local', 'preserved'); sessionStorage.setItem('fixture-session', 'preserved'); }), 10_000); - destinationFacts.stage = 'cookie_import'; - const { runCookieImport } = await import('../../browse/src/cookie-import-operation'); - const tracked: string[] = []; - const imported = await within(() => runCookieImport({ browser: 'Dia', profile: 'Default', domains: ['127.0.0.1'], verifyAuth: true }, - { page: target, url: target.url() }, domains => tracked.push(...domains), { identitySelector: '#fixture-identity', expectedIdentity: identity }), 30_000); - check('native_keychain_decryption_and_verified_import', imported.imported >= 1 && imported.failed === 0 && imported.verification.verified && tracked.includes('127.0.0.1')); - receipt.coverage.nativeKeychainRead = true; - destinationFacts.stage = 'storage_preservation'; - check('default_storage_preserved', await within(() => target.evaluate(() => localStorage.getItem('fixture-local') === 'preserved' && sessionStorage.getItem('fixture-session') === 'preserved'), 10_000)); - destinationFacts.stage = 'wrong_identity'; - const wrong = await within(() => runCookieImport({ browser: 'Dia', profile: 'Default', domains: ['127.0.0.1'], verifyAuth: true }, - { page: target, url: target.url() }, () => {}, { identitySelector: '#fixture-identity', expectedIdentity: 'Different synthetic account', timeoutMs: 500 }), 15_000); - check('wrong_identity_not_verified', !wrong.verification.verified && wrong.verification.reason === 'identity_mismatch'); - destinationFacts.stage = 'storage_reset'; - const reset = await within(() => runCookieImport({ browser: 'Dia', profile: 'Default', domains: ['127.0.0.1'], clearStorage: true, verifyAuth: true }, - { page: target, url: target.url() }, () => {}, { identitySelector: '#fixture-identity', expectedIdentity: identity }), 30_000); - check('explicit_storage_reset', reset.reset === 'cleared' && reset.verification.verified - && await within(() => target.evaluate(() => localStorage.getItem('fixture-local') === null && sessionStorage.getItem('fixture-session') === null), 10_000)); - destinationFacts.stage = 'completed'; - browserRole = undefined; - for (const file of sourceFiles) if (await within(() => sha256(path.join(repository, file)), 5_000) !== receipt.sourceHashes[file]) throw new Error('source_changed_during_qualification'); - if (await within(() => sha256(executable), 10_000) !== receipt.artifact.executableSha256) throw new Error('source_app_changed_during_qualification'); - receipt.status = 'passed'; - receipt.reason = 'native_dia_synthetic_profile_verified'; - } catch (error) { - receipt.reason = stage; - receipt.failureStage = stage; - if (browserRole) { - const facts = receipt.browsers[browserRole]; - const children = (observer?.children ?? []).filter(child => (child.executable === account.destinationExecutable ? 'destination' : 'source') === browserRole); - const stderrReasons = browserStderrFacts(children).flatMap(fact => Object.entries(fact.reasonCounts ?? {}) - .filter(([, count]) => count > 0).map(([reason]) => reason as BrowserStderrReason)); - facts.timedOut = browserOperationTimedOut(error); - facts.error = browserPreflightError(error, stderrReasons); - receipt.blocker = facts.error; - if (facts.stage === 'runtime_import') facts.moduleLoad = playwrightModuleLoadFacts(repository, error); - } - if (error instanceof Error && error.message === 'onboarding_or_external_page') receipt.blocker = 'onboarding_or_unexpected_startup_page'; - if (error instanceof Error && error.message === 'preexisting_browser_state_refused') receipt.blocker = 'preexisting_browser_state_refused'; - if (error instanceof Error && ['user_keychain_search_unavailable', 'user_default_keychain_unavailable', 'invalid_keychain_snapshot', - 'empty_keychain_snapshot', 'invalid_default_keychain_snapshot', 'keychain_outside_owned_home_refused', - 'keychain_search_isolation_failed', 'fixture_keychain_read_failed', 'user_keychain_probe_timeout', 'fixture_keychain_not_owned', - 'fresh_registered_identity_mismatch', 'unsafe_profile_ancestor', 'profile_ownership_unconfirmed', 'source_macos_version_unsupported', - 'invalid_macho_header', 'unsupported_macho_architecture', 'unsafe_macho_file', 'macho_changed_during_inspection', - 'macho_read_budget_exhausted', 'dia_arm64_binary_required', 'comparison_driver_inputs_changed', - 'comparison_driver_authority_missing', 'comparison_budget_exhausted'].includes(error.message)) receipt.blocker = error.message; - const code = (error as { code?: string } | null)?.code; - if (code && ['keychain_timeout', 'keychain_denied', 'keychain_not_found', 'keychain_error', 'db_read_error', 'db_corrupt', 'target_changed', 'target_mismatch'].includes(code)) receipt.blocker = code; - receipt.initialFailure ??= { stage, blocker: receipt.blocker ?? 'qualification_step_failed', - ...(browserRole ? { browser: browserRole, browserStage: receipt.browsers[browserRole].stage } : {}), - ...(browserRole ? { timedOut: receipt.browsers[browserRole].timedOut } : {}), - ...(stage === 'temporary_keychain' ? { keychainStage: receipt.keychainStage } : {}) }; - receipt.status = Object.values(receipt.cases).includes('failed') ? 'failed' : 'incomplete'; - } finally { - cleaning = true; - cleanupDeadline = performance.now() + 45_000; - observer?.stop(); - for (const role of ['source', 'destination'] as const) { - const facts = receipt.browsers[role]; - if (role === 'source' && comparisonAttempted && comparisonSource) { - facts.ownedRootCount = comparisonSource.rootCount ?? 0; - facts.rootStatesBeforeCleanup = comparisonSource.rootsBeforeCleanup ?? []; - facts.stderrBeforeCleanup = comparisonSource.stderrBeforeCleanup ?? []; - facts.launchAttempts = comparisonSource.launchAttempts ?? []; - facts.cleanup = comparisonSource.cleanup; - continue; - } - const children = (observer?.children ?? []).filter(child => (child.executable === account.destinationExecutable ? 'destination' : 'source') === role); - facts.ownedRootCount = children.length; - facts.rootStatesBeforeCleanup = browserRootFacts(children); - facts.stderrBeforeCleanup = browserStderrFacts(children); - facts.launchAttempts = attemptStarts[role] === undefined ? [] : (observer?.attempts ?? []) - .slice(attemptStarts[role], role === 'source' ? attemptStarts.destination : undefined); - facts.cleanup = { closeAttempted: false, groups: [] }; - } - for (const [role, context] of [['source', source], ['destination', destination]] as const) { - if (!context) continue; - receipt.browsers[role].cleanup.closeAttempted = true; - try { await bounded(context.close(), 5_000); } - catch (error) { receipt.browsers[role].cleanup.closeError = browserPreflightError(error); } - } - let stopped = comparisonAttempted ? comparisonSource?.cleanup?.confirmed === true : !observer || observer.children.length >= launchAttempts; - receipt.browserCleanup = { launchAttempts: comparisonAttempted ? 1 : launchAttempts, - capturedRootCount: comparisonAttempted ? comparisonSource?.rootCount ?? 0 : observer?.children.length ?? 0, - rootCaptureComplete: comparisonAttempted ? comparisonSource?.rootCount === 1 : stopped }; - for (const child of observer?.children ?? []) { - const role = child.executable === account.destinationExecutable ? 'destination' : 'source'; - const group: Record = { pid: child.pid, stage: 'probe_before_signal', signalSent: false, absenceConfirmed: false }; - receipt.browsers[role].cleanup.groups.push(group); - const until = Math.min(cleanupDeadline, performance.now() + 5_000); - try { - await stopOwnedBrowserGroup(child, until, group); - } catch (error) { - stopped = false; - group.childCloseObserved = child.closeObserved; - group.failure = browserCleanupError(error); - try { - const timeout = Math.floor(Math.min(2_000, cleanupDeadline - performance.now())); - if (timeout < 1) throw new Error('cleanup_budget_exhausted'); - const snapshot = spawnSync('/bin/ps', ['-axo', 'uid=,pid=,ppid=,pgid=,state='], { - env: environment, encoding: 'utf8', timeout, maxBuffer: 128 * 1024, - }); - if (snapshot.error || snapshot.status !== 0 || !snapshot.stdout.trim()) throw new Error('process_snapshot_unavailable'); - group.membersAfterFailure = browserGroupFacts(snapshot.stdout, account.uid, child.pid); - } catch { group.membersAfterFailure = { available: false }; } - } - group.rootAfterCleanup = browserRootFacts([child])[0]; - } - for (const role of ['source', 'destination'] as const) { - receipt.browsers[role].stderrAfterCleanup = role === 'source' && comparisonAttempted ? comparisonSource?.stderrAfterCleanup ?? [] - : browserStderrFacts((observer?.children ?? []).filter(child => (child.executable === account.destinationExecutable ? 'destination' : 'source') === role)); - } - receipt.cleanup.ownedBrowsersStopped = stopped; - receipt.observedBrowserRoots = comparisonAttempted ? comparisonSource?.rootCount ?? 0 : observer?.children.length ?? 0; - server?.stop(true); - if (!profileCreationAttempted) receipt.cleanup.sourceProfileRemoved = true; - else if (stopped && profileOwnership) { - try { removeOwnedDiaProfile(profileOwnership, stopped); receipt.cleanup.sourceProfileRemoved = true; } catch {} - } - if (stopped) { - try { - if (keychainChanged) { - let restored = true; - for (const args of fixtureKeychainRestoreCommands({ search: originalSearch, default: originalDefault }, keychain, keychainCreated)) { - try { run('/usr/bin/security', args); } catch { restored = false; } - } - if (!restored) throw new Error('keychain_restore_failed'); - const restoredSnapshot = captureUserKeychains(environment, [home, root], cleanupDeadline - performance.now()); - if (JSON.stringify(restoredSnapshot.search) !== JSON.stringify(originalSearch) - || JSON.stringify(restoredSnapshot.default) !== JSON.stringify(originalDefault)) throw new Error('keychain_restore_failed'); - } - receipt.cleanup.keychainRestored = true; - } catch {} - } - try { - if (mounted) run('/usr/bin/hdiutil', ['detach', mount], 10_000); - receipt.cleanup.mountDetached = true; - } catch {} - if (stopped && receipt.cleanup.sourceProfileRemoved && receipt.cleanup.keychainRestored && receipt.cleanup.mountDetached) { - try { - if (realpathSync(root) !== root || path.dirname(root) !== runnerTemp) throw new Error('fixture_root_changed'); - rmSync(root, { recursive: true, force: true }); - receipt.cleanup.fixtureRemoved = true; - } catch {} - } - if (Object.values(receipt.cleanup).some(value => value !== true)) { receipt.status = 'failed'; receipt.reason = 'cleanup_incomplete'; } - receipt.counts = { pass: Object.values(receipt.cases).filter(value => value === 'passed').length, - fail: Object.values(receipt.cases).filter(value => value === 'failed').length, skip: 0 }; - writePrivateReceipt(output, receipt); - } - return receipt; -} - -if (import.meta.main) { - try { - if (process.argv[2] === '--isolated-worker') { - const receipt = await qualifyDia({ root: process.argv[3], configFile: process.argv[4] }); - console.log(JSON.stringify({ status: receipt.status, reason: receipt.reason, counts: receipt.counts, artifact: 'dia-native-qualification.json' })); - process.exitCode = receipt.status === 'passed' ? 0 : 2; - } else { - validateQualificationHost(process.env); - if (process.argv[2] !== '--fresh-account' || !process.argv[3]) throw new Error('fresh_account_configuration_required'); - const account = readFreshAccountConfiguration(process.argv[3]); - if (account.guiReadiness) throw new Error('browser_qualification_authority_required'); - if (Bun.version !== '1.4.2' || require('playwright/package.json').version !== '1.62.1') throw new Error('pinned_runtimes_required'); - const originalHome = account.home; - const originalHomeEnvironment = process.env.HOME; - const runnerTemp = realpathSync(process.env.RUNNER_TEMP!); - const output = path.join(runnerTemp, 'dia-native-qualification.json'); - if (existsSync(output)) throw new Error('fresh_receipt_path_required'); - const root = realpathSync(mkdtempSync(path.join(runnerTemp, 'dia-'))); - chmodSync(root, 0o700); - const temporary = path.join(root, 't'); - mkdirSync(temporary, { mode: 0o700 }); - const metadata = Object.fromEntries(['CI', 'GITHUB_ACTIONS', 'RUNNER_ENVIRONMENT', 'RUNNER_OS', 'RUNNER_ARCH', 'RUNNER_TEMP', - 'GITHUB_RUN_ID', 'GITHUB_RUN_ATTEMPT', 'GSTACK_DIA_NATIVE_QUALIFY', 'GSTACK_DIA_EXPECT_UID', 'GSTACK_DIA_SOURCE_REVISION'] - .filter(name => process.env[name] !== undefined).map(name => [name, process.env[name]!])); - const child = spawnSync(process.execPath, ['--no-env-file', '--no-install', '--no-macros', '--config=/dev/null', import.meta.path, - '--isolated-worker', root, account.configFile], { - cwd: repository, env: { ...metadata, HOME: account.home, TMPDIR: temporary, PATH: '/usr/bin:/bin:/usr/sbin:/sbin', LANG: 'en_US.UTF-8' }, - encoding: 'utf8', timeout: 630_000, killSignal: 'SIGKILL', maxBuffer: 1024 * 1024, - }); - if (realpathSync(homedir()) !== originalHome || process.env.HOME !== originalHomeEnvironment - || child.error || ![0, 2].includes(child.status ?? -1) || !existsSync(output)) { - let receipt: Record = { counts: { pass: 0, fail: 0, skip: 0 }, cleanup: { confirmed: false } }; - if (existsSync(output)) { - if (!lstatSync(output).isFile() || realpathSync(output) !== output || lstatSync(output).size > 1024 * 1024) throw new Error('invalid_worker_receipt'); - try { receipt = JSON.parse(readFileSync(output, 'utf8')); } catch {} - } - receipt.status = 'incomplete'; - receipt.reason = 'qualification_worker_did_not_complete'; - receipt.runId = process.env.GITHUB_RUN_ID; - receipt.runAttempt = process.env.GITHUB_RUN_ATTEMPT; - receipt.supervisor = { completed: false, exitCode: child.status }; - receipt.recovery = 'Discard this disposable runner; do not reuse its Keychain or staged profile.'; - writePrivateReceipt(output, receipt, existsSync(output)); - console.log(JSON.stringify({ status: 'incomplete', reason: 'qualification_worker_did_not_complete', artifact: 'dia-native-qualification.json' })); - process.exitCode = 2; - } else { - const summary = JSON.parse(child.stdout); - console.log(JSON.stringify({ status: summary.status, reason: summary.reason, counts: summary.counts, artifact: 'dia-native-qualification.json' })); - process.exitCode = child.status === 0 && summary.status === 'passed' && summary.counts?.pass === 8 && summary.counts?.fail === 0 && summary.counts?.skip === 0 ? 0 : 2; - } - } - } catch { - console.log(JSON.stringify({ status: 'incomplete', reason: 'qualification_preflight_failed', counts: { pass: 0, fail: 0, skip: 0 } })); - process.exitCode = 2; - } -} diff --git a/.github/scripts/run-dia-native-qualification.ts b/.github/scripts/run-dia-native-qualification.ts deleted file mode 100644 index 95236b1f9..000000000 --- a/.github/scripts/run-dia-native-qualification.ts +++ /dev/null @@ -1,864 +0,0 @@ -import { createHash, randomBytes, randomUUID } from 'node:crypto'; -import { spawnSync } from 'node:child_process'; -import { accessSync, chmodSync, constants, copyFileSync, createReadStream, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'; -import { createRequire } from 'node:module'; -import { homedir } from 'node:os'; -import path from 'node:path'; -import { assertDiaSocketPath, browserPreflightError, browserStartupCategory, captureUserKeychains, fixtureKeychainRestoreCommands, FRESH_WORK_PREFIX, type FreshAccount, - nativeDiaLaunchOptions, observeBrowserLaunches, observeFixtureKeychain, ownsFreshAccount, parseDirectoryRecord, stopOwnedBrowserGroup, - inspectMachOArchitectures, playwrightModuleLoadFacts, prepareKeychainHome, readFreshAccountConfiguration, runDiaLaunchComparison, runGuiReadiness, - validateQualificationHost, writePrivateReceipt } from './qualify-dia-macos'; -export { FRESH_WORK_PREFIX, ownsFreshAccount, parseDirectoryRecord } from './qualify-dia-macos'; - -const require = createRequire(import.meta.url); -const repository = path.resolve(import.meta.dir, '../..'); - -interface UserDomainObservation { - uid: number; - state: 'present' | 'absent' | 'unavailable'; - hasGuiDomain: boolean; - exitCode: number | null; - stdoutBytes: number; - stderrBytes: number; - structure?: { - complete: boolean; - type: 'user' | 'other' | 'unavailable'; - handleMatchesUid: boolean | null; - creator: 'launchctl' | 'other' | 'unavailable'; - creatorIsProbe: boolean | null; - counts: Record; - sectionNonemptyLines: Record; - }; -} - -export function classifyUserDomain(uid: number, result: { status: number | null; stdout: string; stderr: string; error?: unknown }, probePid?: number): UserDomainObservation { - if (!Number.isSafeInteger(uid) || uid < 20_000 || uid >= 60_000) throw new Error('invalid_fresh_user_domain'); - const text = result.stdout.trimStart(); - const diagnostic = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join('\n'); - const missing = new RegExp('^(?:Bad request\\.\\s*)?Could not find domain for (?:(?:user (?:uid|user)|uid|user):\\s*' + uid + '|user/' + uid + ')\\.?$'); - const present = !result.error && result.status === 0 - && (text.startsWith('user/' + uid + ' = {') || text.startsWith('com.apple.xpc.launchd.domain.user.' + uid + ' = {')); - const absent = !result.error && Number.isInteger(result.status) && result.status! > 0 && missing.test(diagnostic); - const observation: UserDomainObservation = { uid, state: present ? 'present' : absent ? 'absent' : 'unavailable', - hasGuiDomain: present && (new RegExp('\\bgui/' + uid + '(?:\\b|/)').test(text) || /\bsession\s*=\s*Aqua\b/.test(text) - || new RegExp('com\\.apple\\.xpc\\.launchd\\.user\\.domain\\.' + uid + '\\.\\d+\\.Aqua\\b').test(text)), - exitCode: result.status, stdoutBytes: Buffer.byteLength(result.stdout), stderrBytes: Buffer.byteLength(result.stderr) }; - if (!present || observation.stdoutBytes > 1024 * 1024) return observation; - const lines = text.trimEnd().split('\n'); - const indent = lines.find(line => /^\s+type = \S+\s*$/.test(line))?.match(/^(\s+)/)?.[1]; - const fields = new Map(); - const sections: Record = Object.fromEntries(['services', 'jobs', 'subdomains', 'unmanaged processes', 'endpoints', - 'externally-hosted endpoints', 'pending requests', 'pending attachments'].map(key => [key, null])); - let complete = Boolean(indent) && lines.at(-1) === '}'; - for (let index = 1; indent && index < lines.length - 1; index++) { - const line = lines[index]; - if (!line.trim()) continue; - if (!line.startsWith(indent) || /^\s/.test(line.slice(indent.length))) { complete = false; break; } - const entry = line.slice(indent.length).match(/^([^=]+?) = (.*)$/); - if (!entry || fields.has(entry[1])) { complete = false; break; } - fields.set(entry[1], entry[2]); - if (entry[2] === '{') { - let nonemptyLines = 0; - while (++index < lines.length - 1 && lines[index] !== indent + '}') { - if (lines[index].trim()) nonemptyLines++; - } - if (index >= lines.length - 1) { complete = false; break; } - if (Object.hasOwn(sections, entry[1])) sections[entry[1]] = nonemptyLines; - } else if (entry[2] === '{}' && Object.hasOwn(sections, entry[1])) sections[entry[1]] = 0; - } - const counts = Object.fromEntries(['active count', 'on-demand count', 'service count', 'active service count', 'external activation count', - 'in-progress bootstraps', 'pended requests', 'creator euid'].map(key => { - const value = fields.get(key); - return [key, value && /^\d+$/.test(value) && Number.isSafeInteger(Number(value)) ? Number(value) : null]; - })); - const creatorMatch = fields.get('creator')?.match(/^launchctl(?:\.([1-9]\d*)|\[([1-9]\d*)\])$/); - const creatorPid = creatorMatch?.[1] ?? creatorMatch?.[2]; - observation.structure = { complete, type: fields.has('type') ? fields.get('type') === 'user' ? 'user' : 'other' : 'unavailable', - handleMatchesUid: fields.has('handle') ? fields.get('handle') === String(uid) : null, - creator: creatorPid ? 'launchctl' : fields.has('creator') ? 'other' : 'unavailable', - creatorIsProbe: creatorPid && Number.isSafeInteger(probePid) && probePid! > 0 ? Number(creatorPid) === probePid : null, - counts, sectionNonemptyLines: sections }; - return observation; -} - -export function inspectUserDomain(uid: number, deadline: number, env: Record, spawn: typeof spawnSync = spawnSync): UserDomainObservation { - if (!Number.isSafeInteger(uid) || uid < 20_000 || uid >= 60_000) throw new Error('invalid_fresh_user_domain'); - if (!Number.isFinite(deadline)) throw new Error('fresh_launcher_deadline'); - const timeout = Math.floor(Math.min(3_000, deadline - performance.now())); - if (!Number.isFinite(timeout) || timeout < 1) throw new Error('fresh_launcher_deadline'); - const result = spawn('/usr/bin/sudo', ['-n', '/bin/sh', '-c', 'printf "GSTACK_DIA_DOMAIN_PROBE_PID=%s\\n" "$$"; exec /bin/launchctl print "$1"', - 'gstack-dia-domain-probe', 'user/' + uid], { env, encoding: 'utf8', timeout, maxBuffer: 1024 * 1024 }); - const stdout = typeof result.stdout === 'string' ? result.stdout : ''; - const stderr = typeof result.stderr === 'string' ? result.stderr : ''; - const prefix = stdout.match(/^GSTACK_DIA_DOMAIN_PROBE_PID=([1-9]\d*)\n/); - const pid = prefix ? Number(prefix[1]) : undefined; - return classifyUserDomain(uid, { ...result, stdout: prefix ? stdout.slice(prefix[0].length) : stdout, stderr, - error: result.error || (!Number.isSafeInteger(pid) ? new Error('domain_probe_pid_unavailable') : undefined) }, pid); -} - -export function classifyParentDomain(uid: number, result: { status: number | null; stdout: string; stderr: string; error?: unknown }) { - if (!Number.isSafeInteger(uid) || uid < 20_000 || uid >= 60_000) throw new Error('invalid_fresh_user_domain'); - const observation = { uid, state: 'unavailable' as 'present' | 'absent' | 'unavailable', parseStage: 'command_failure', - subdomainCount: 0, matchingUserDomains: 0, matchingGuiDomains: 0, unrecognizedEntries: 0, duplicateEntries: 0, - exitCode: result.status, stdoutBytes: Buffer.byteLength(result.stdout), stderrBytes: Buffer.byteLength(result.stderr) }; - if (result.error || result.status !== 0) return observation; - observation.parseStage = 'oversized'; - if (observation.stdoutBytes > 1024 * 1024) return observation; - observation.parseStage = 'unexpected_parent'; - const lines = result.stdout.trim().split('\n'); - if (!['system = {', 'com.apple.xpc.launchd.domain.system = {'].includes(lines[0]) || lines.at(-1) !== '}') return observation; - const indent = lines.find(line => /^\s+type = system$/.test(line))?.match(/^(\s+)/)?.[1]; - if (!indent) return observation; - const fields = new Set(); - let subdomains: string[] | undefined; - observation.parseStage = 'malformed_structure'; - for (let index = 1; index < lines.length - 1; index++) { - const line = lines[index]; - if (!line.trim()) continue; - if (!line.startsWith(indent) || /^\s/.test(line.slice(indent.length))) return observation; - const entry = line.slice(indent.length).match(/^([^=]+?) = (.*)$/); - if (!entry || fields.has(entry[1])) return observation; - fields.add(entry[1]); - if (entry[2] === '{') { - const start = index + 1; - while (++index < lines.length - 1 && lines[index] !== indent + '}') {} - if (index >= lines.length - 1) return observation; - if (entry[1] === 'subdomains') subdomains = lines.slice(start, index).map(line => line.trim()).filter(Boolean); - } else if (entry[1] === 'subdomains' && entry[2] === '{}') subdomains = []; - } - observation.parseStage = 'missing_subdomains'; - if (!subdomains) return observation; - const seen = new Set(); - for (const entry of subdomains) { - observation.subdomainCount++; - const user = entry.match(/^(?:user\/|com\.apple\.xpc\.launchd\.domain\.user\.)(\d+)$/); - const gui = entry.match(/^(?:gui\/(\d+)|com\.apple\.xpc\.launchd\.user\.domain\.(\d+)\.\d+\.Aqua)$/); - const listedUid = user?.[1] ?? gui?.[1] ?? gui?.[2]; - const process = entry.match(/^(?:pid\/(\d+)|com\.apple\.xpc\.launchd\.domain\.pid\.[^{}\r\n]+\.(\d+))$/); - const session = entry.match(/^(?:session\/(\d+)|com\.apple\.xpc\.launchd\.domain\.session\.(\d+))$/); - const identity = user ? 'user/' + listedUid : gui ? 'gui/' + listedUid : process ? 'pid/' + (process[1] ?? process[2]) - : session ? 'session/' + (session[1] ?? session[2]) : entry; - if (seen.has(identity)) observation.duplicateEntries++; - seen.add(identity); - if (listedUid && (!Number.isSafeInteger(Number(listedUid)) || String(Number(listedUid)) !== listedUid)) observation.unrecognizedEntries++; - else if (user) observation.matchingUserDomains += Number(user[1]) === uid ? 1 : 0; - else if (gui) observation.matchingGuiDomains += Number(gui[1] ?? gui[2]) === uid ? 1 : 0; - else if (!/^(?:(?:pid|session|login)\/\d+|com\.apple\.xpc\.launchd\.domain\.(?:pid\.[^{}\r\n]+\.\d+|session\.\d+))$/.test(entry)) observation.unrecognizedEntries++; - } - observation.parseStage = observation.unrecognizedEntries ? 'unrecognized_subdomain' : observation.duplicateEntries ? 'duplicate_subdomain' : 'parsed'; - if (!observation.unrecognizedEntries && !observation.duplicateEntries) observation.state = observation.matchingUserDomains || observation.matchingGuiDomains ? 'present' : 'absent'; - return observation; -} - -type ParentDomainObservation = ReturnType; - -export function passiveUserDomainState(observation: ParentDomainObservation | undefined, uid: number): 'absent' | 'present' | 'unavailable' { - if (!observation || observation.uid !== uid || observation.exitCode !== 0 || observation.parseStage !== 'parsed' - || observation.duplicateEntries !== 0 || observation.unrecognizedEntries !== 0 || observation.matchingGuiDomains !== 0) return 'unavailable'; - if (observation.state === 'absent' && observation.matchingUserDomains === 0) return 'absent'; - if (observation.state === 'present' && observation.matchingUserDomains === 1) return 'present'; - return 'unavailable'; -} - -export function inspectParentDomain(uid: number, deadline: number, env: Record, spawn: typeof spawnSync = spawnSync) { - if (!Number.isSafeInteger(uid) || uid < 20_000 || uid >= 60_000) throw new Error('invalid_fresh_user_domain'); - const timeout = Math.floor(Math.min(3_000, deadline - performance.now())); - if (!Number.isFinite(deadline) || !Number.isFinite(timeout) || timeout < 1) throw new Error('fresh_launcher_deadline'); - const result = spawn('/usr/bin/sudo', ['-n', '/bin/launchctl', 'print', 'system'], { env, encoding: 'utf8', timeout, maxBuffer: 1024 * 1024 }); - return classifyParentDomain(uid, { ...result, stdout: typeof result.stdout === 'string' ? result.stdout : '', - stderr: typeof result.stderr === 'string' ? result.stderr : '' }); -} - -export const ARCHIVE_CHECK = `import json, posixpath, sys, tarfile, unicodedata -try: - with tarfile.open(sys.argv[1], 'r:') as archive: - members = archive.getmembers() - if len(members) > 200000 or sum(item.size for item in members) > 2 * 1024**3: - raise ValueError() - seen, links = set(), set() - for item in members: - name = item.name.rstrip('/') - if not name or name.startswith('/') or '\\\\' in name or any(ord(char) < 32 for char in name): - raise ValueError() - canonical = unicodedata.normalize('NFC', name).casefold() - if '..' in name.split('/') or posixpath.normpath(name) != name or canonical in seen: - raise ValueError() - if not (item.isfile() or item.isdir() or item.issym()): - raise ValueError() - seen.add(canonical) - if item.issym(): - target = posixpath.normpath(posixpath.join(posixpath.dirname(name), item.linkname)) - if item.linkname.startswith('/') or '\\\\' in item.linkname or '..' in item.linkname.split('/') or target == '..' or target.startswith('../'): - raise ValueError() - links.add(canonical) - for item in members: - parts = unicodedata.normalize('NFC', item.name.rstrip('/')).casefold().split('/') - if any('/'.join(parts[:index]) in links for index in range(1, len(parts))): - raise ValueError() - print(json.dumps({'valid': True, 'members': len(members)})) -except Exception: - print(json.dumps({'valid': False, 'reason': 'unsafe_source_archive'})) - sys.exit(2) -`; - -export const PRIVATE_RECEIPT_READ = `import json, os, stat, sys -fds = [] -try: - file, uid, root = sys.argv[1], int(sys.argv[2]), os.path.realpath(sys.argv[3]) - if root != sys.argv[3] or not os.path.isabs(file) or os.path.normpath(file) != file or os.path.commonpath([file, root]) != root: - raise ValueError() - parts = os.path.relpath(file, root).split(os.sep) - if any(part in ('', '.', '..') for part in parts): - raise ValueError() - fds.append(os.open(root, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)) - for part in parts[:-1]: - fds.append(os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fds[-1])) - parent = os.fstat(fds[-1]) - if parent.st_uid != uid or parent.st_mode & 0o022: - raise ValueError() - fds.append(os.open(parts[-1], os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=fds[-1])) - fd = fds[-1] - info = os.fstat(fd) - if not stat.S_ISREG(info.st_mode) or info.st_uid != uid or info.st_mode & 0o022 or info.st_size > 1024**2: - raise ValueError() - data = os.read(fd, 1024**2 + 1) - after = os.fstat(fd) - if len(data) != info.st_size or (info.st_size, info.st_mtime_ns, info.st_ctime_ns) != (after.st_size, after.st_mtime_ns, after.st_ctime_ns): - raise ValueError() - value = json.loads(data) - if not isinstance(value, dict): - raise ValueError() - print(json.dumps(value)) -except Exception: - sys.exit(2) -finally: - for fd in reversed(fds): - os.close(fd) -`; - -export function uidProcessFacts(output: string, uid: number) { - const known = ['bun', 'security', 'osascript', 'launchd', 'cfprefsd', 'trustd', 'distnoted', 'lsd', 'tccd', 'securityd', 'secd', 'usernoted', - 'UserEventAgent', 'pkd', 'nsurlsessiond', 'containermanagerd', 'Google Chrome for Testing', 'Google Chrome', 'Chromium', - 'Chromium Helper', 'Dia', 'Dia Helper', 'chrome', 'chrome_crashpad_handler']; - const aliases = new Map(known.flatMap(name => [name, name.slice(0, 15), name.slice(0, 16)].map(alias => [alias, name] as const))); - const processes: Array<{ pid: number; ppid: number; state: string; basename: string }> = []; - for (const line of output.split('\n').filter(line => line.trim())) { - const match = line.match(/^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/); - if (!match) throw new Error('invalid_uid_process_snapshot'); - if (Number(match[1]) !== uid) continue; - const pid = Number(match[2]); - const ppid = Number(match[3]); - if (!Number.isSafeInteger(pid) || pid < 1 || !Number.isSafeInteger(ppid) || ppid < 0) throw new Error('invalid_uid_process_snapshot'); - const state = ['I', 'R', 'S', 'T', 'U', 'Z', 'D', 'X'].includes(match[4][0]) ? match[4][0] : 'other'; - processes.push({ pid, ppid, state, basename: aliases.get(match[5]) ?? 'other' }); - } - return { available: true, count: processes.length, zombies: processes.filter(process => process.state === 'Z').length, - live: processes.filter(process => process.state !== 'Z').length, truncated: processes.length > 64, processes: processes.slice(0, 64) }; -} - -export function inspectUidProcesses(uid: number, deadline: number, env: Record, spawn: typeof spawnSync = spawnSync) { - if (!Number.isSafeInteger(uid) || uid < 20_000 || uid >= 60_000) throw new Error('invalid_fresh_user_domain'); - try { - const timeout = Math.floor(Math.min(2_000, deadline - performance.now())); - if (!Number.isFinite(deadline) || !Number.isFinite(timeout) || timeout < 1) throw new Error('fresh_launcher_deadline'); - const result = spawn('/bin/ps', ['-axo', 'uid=,pid=,ppid=,state=,ucomm='], { env, encoding: 'utf8', timeout, maxBuffer: 128 * 1024 }); - if (result.error || result.status !== 0 || typeof result.stdout !== 'string' || !result.stdout.trim()) throw new Error('uid_process_snapshot_failed'); - return uidProcessFacts(result.stdout, uid); - } catch { return { available: false }; } -} - -export function freshQualificationPassed(workerExit: number | undefined, backgroundStatus: unknown, qualificationStatus: unknown, cleanup: Record): boolean { - return workerExit === 0 && backgroundStatus === 'passed' && qualificationStatus === 'passed' - && ['serviceStopped', 'userDomainStopped', 'userProcessesStopped', 'accountRemoved', 'groupRemoved', 'stagingRemoved'].every(key => cleanup[key] === true) - && Object.values(cleanup).every(value => value === true); -} - -export function parseDirectoryIds(output: string): Set { - const ids = new Set(); - for (const line of output.split('\n').filter(line => line.trim())) { - const value = line.match(/^\S.*?\s+(-?\d+)\s*$/)?.[1]; - if (!value || !Number.isSafeInteger(Number(value))) throw new Error('invalid_directory_id_list'); - ids.add(Number(value)); - } - if (!ids.size) throw new Error('empty_directory_id_list'); - return ids; -} - -export function ownedUserDomainTarget(record: Record, account: Pick, - beforeCreation: ParentDomainObservation | undefined, current: ParentDomainObservation, currentUid = process.getuid?.()): string | null { - const currentState = passiveUserDomainState(current, account.uid); - if (!Number.isSafeInteger(account.uid) || account.uid < 20_000 || account.uid >= 60_000 || account.uid === currentUid - || !Number.isSafeInteger(currentUid) || !ownsFreshAccount(record, account) - || passiveUserDomainState(beforeCreation, account.uid) !== 'absent' || currentState === 'unavailable') { - throw new Error('fresh_user_domain_ownership_unconfirmed'); - } - return currentState === 'present' ? 'user/' + account.uid : null; -} - -export function freshLaunchDefinition(account: FreshAccount) { - return { - Label: account.label, UserName: account.account, GroupName: account.account, SessionCreate: true, - RunAtLoad: true, KeepAlive: false, ExitTimeOut: 5, Umask: 63, - WorkingDirectory: account.snapshot, - ProgramArguments: [account.bun, '--no-env-file', '--no-install', '--no-macros', '--config=/dev/null', - path.join(account.snapshot, '.github/scripts/run-dia-native-qualification.ts'), '--fresh-worker', account.configFile], - EnvironmentVariables: account.environment, - StandardOutPath: '/dev/null', StandardErrorPath: '/dev/null', - }; -} - -export function ownsLaunchService(state: string, account: Pick): boolean { - return state.trimStart().startsWith('system/' + account.label + ' = {') - && state.match(/^\s*program = (.+)$/m)?.[1].trim() === account.bun - && state.match(/^\s*username = (.+)$/m)?.[1].trim() === account.account - && state.match(/^\s*group = (.+)$/m)?.[1].trim() === account.account; -} - -async function digest(file: string) { - const hash = createHash('sha256'); - for await (const chunk of createReadStream(file)) hash.update(chunk); - return hash.digest('hex'); -} - -function safeCommand(command: string, args: string[], timeout: number, env: NodeJS.ProcessEnv, cwd?: string) { - timeout = Math.floor(timeout); - if (!Number.isFinite(timeout) || timeout < 1) throw new Error('native_operation_timed_out'); - const result = spawnSync(command, args, { env, cwd, encoding: 'utf8', timeout, maxBuffer: 1024 * 1024 }); - if (result.error || result.status !== 0) { - const elevated = command === '/usr/bin/sudo'; - const errorCode = (result.error as NodeJS.ErrnoException | undefined)?.code; - throw Object.assign(new Error('native_command_failed'), { diagnostic: { - command: path.basename(elevated ? args[1] : command), operation: args[elevated ? 2 : 0], exitCode: result.status, - stdoutBytes: Buffer.byteLength(result.stdout || ''), stderrBytes: Buffer.byteLength(result.stderr || ''), - spawnError: result.error ? (['ENOENT', 'EACCES', 'EPERM', 'ETIMEDOUT'].includes(errorCode || '') ? errorCode : 'spawn_failed') : undefined, - } }); - } - return result.stdout.trim(); -} - -async function limit(promise: Promise, timeout: number): Promise { - let timer: ReturnType; - try { - return await Promise.race([promise, new Promise((_, reject) => { - timer = setTimeout(() => reject(new Error('native_operation_timed_out')), timeout); - })]); - } finally { clearTimeout(timer!); } -} - -async function freshWorker(configFile: string) { - validateQualificationHost(process.env); - const account = readFreshAccountConfiguration(configFile); - const preflightFile = path.join(account.temporary, 'dia-background-preflight.json'); - const seed = lstatSync(preflightFile); - if (!seed.isFile() || seed.uid !== process.getuid?.() || realpathSync(preflightFile) !== preflightFile) throw new Error('unsafe_preflight_receipt'); - const receipt: Record = { status: 'incomplete', reason: 'fresh_identity_preflight', nativeCasesRun: false, - preflight: { registeredIdentity: false, foundationHome: false, keychain: false, headlessChromium: false }, - cleanup: { probeBrowsersStopped: false, probeKeychainRestored: false }, sessionCreate: true }; - const env = account.environment; - let cleaning = false; - const run = (command: string, args: string[], timeout = 10_000) => { - try { return safeCommand(command, args, timeout, env, account.snapshot); } - catch (error) { - const diagnostic = (error as { diagnostic?: object }).diagnostic ?? { command: path.basename(command), operation: args[0] }; - if (cleaning) (receipt.cleanupCommandFailures ??= []).push(diagnostic); - else receipt.initialCommandFailure ??= diagnostic; - throw new Error('native_command_failed'); - } - }; - let context: any; - let observer: ReturnType | undefined; - let comparisonControl: Record | undefined; - let launchAttempted = false; - let keychainCreated = false; - let keychainChanged = false; - let snapshot: ReturnType | undefined; - const probe = path.join(account.temporary, 'probe'); - const keychain = path.join(probe, 'probe.keychain-db'); - try { - if (!/^[a-z][a-z0-9]{8,24}$/.test(account.account) || process.getuid?.() !== account.uid || process.geteuid?.() !== account.uid - || process.getgid?.() !== account.gid || realpathSync(homedir()) !== account.home || realpathSync(account.work) !== account.work) throw new Error('fresh_identity_mismatch'); - for (const directory of [account.home, account.temporary, account.snapshot, path.dirname(account.bun), - ...(account.guiReadiness ? [] : [path.join(account.snapshot, 'node_modules')])]) { - if (!directory.startsWith(account.work + path.sep) || realpathSync(directory) !== directory || lstatSync(directory).uid !== account.uid) throw new Error('fresh_directory_ownership_mismatch'); - } - const record = parseDirectoryRecord(run('/usr/bin/dscl', ['.', '-read', '/Users/' + account.account, 'UniqueID', 'PrimaryGroupID', 'NFSHomeDirectory', 'GeneratedUID'])); - if (!ownsFreshAccount(record, account)) throw new Error('fresh_registered_identity_mismatch'); - receipt.preflight.registeredIdentity = true; - if (account.guiReadiness) { - if (await digest(account.bun) !== account.bunSha256) throw new Error('staged_executable_changed'); - receipt.reason = 'gui_readiness_only'; - receipt.operations = { dependencyInstall: false, browserLaunch: false, keychainAccess: false, diaDownload: false }; - receipt.guiReadiness = await runGuiReadiness(account.guiReadiness.executable, account.guiReadiness.executableSha256, - path.join(account.snapshot, '.github/scripts/dia-gui-readiness.c'), account.guiReadiness.sourceSha256, false, env); - return receipt.guiReadiness.available && receipt.guiReadiness.observation.identity.effectiveUidMatches - && receipt.guiReadiness.observation.identity.homeMatchesRegistered ? 0 : 2; - } - if (!account.destinationExecutable || !account.destinationSha256) throw new Error('browser_qualification_authority_required'); - const foundationHome = run('/usr/bin/osascript', ['-l', 'JavaScript', '-e', 'ObjC.import("Foundation"); $.NSHomeDirectory().js']); - if (realpathSync(foundationHome) !== account.home) throw new Error('foundation_home_mismatch'); - receipt.preflight.foundationHome = true; - receipt.keychainHome = prepareKeychainHome(account.home, account.uid); - receipt.dependencyDirectoryPresentBeforeInstall = true; - for (const executable of [account.bun, account.destinationExecutable]) { - accessSync(executable, constants.X_OK); - if (!path.isAbsolute(executable) || realpathSync(executable) !== executable || !executable.startsWith(account.work + path.sep)) throw new Error('staged_executable_escape'); - } - if (await digest(account.bun) !== account.bunSha256 || await digest(account.destinationExecutable) !== account.destinationSha256) throw new Error('staged_executable_changed'); - receipt.reason = 'fresh_dependency_install'; - run(account.bun, ['install', '--frozen-lockfile', '--ignore-scripts'], 180_000); - if (Bun.version !== '1.4.2' || require(path.join(account.snapshot, 'node_modules/playwright/package.json')).version !== '1.62.1') throw new Error('pinned_runtime_mismatch'); - mkdirSync(probe, { mode: 0o700 }); - receipt.reason = 'background_keychain_preflight'; - snapshot = captureUserKeychains(env, [account.home, account.temporary]); - const password = randomBytes(24).toString('hex'); - const value = randomBytes(24).toString('hex'); - keychainChanged = true; - run('/usr/bin/security', ['create-keychain', '-p', password, keychain]); - keychainCreated = true; - run('/usr/bin/security', ['set-keychain-settings', '-lut', '300', keychain]); - run('/usr/bin/security', ['unlock-keychain', '-p', password, keychain]); - run('/usr/bin/security', ['list-keychains', '-d', 'user', '-s', keychain]); - run('/usr/bin/security', ['default-keychain', '-d', 'user', '-s', keychain]); - run('/usr/bin/security', ['add-generic-password', '-s', 'Gstack Native Probe', '-a', 'fixture', '-w', value, - '-T', '/usr/bin/security', keychain]); - const observed = observeFixtureKeychain(env, [account.home, account.temporary], keychain, value); - receipt.keychainObservations = { ...observed, preferencesFileExists: existsSync(path.join(account.home, 'Library/Preferences/com.apple.security.plist')) }; - if (!observed.searchPathMatches || !observed.defaultPathMatches || !observed.explicitReadMatches) throw new Error('native_keychain_probe_failed'); - receipt.preflight.keychain = true; - if (account.launchComparison) { - receipt.reason = 'comparison_chromium_control'; - launchAttempted = true; - comparisonControl = await runDiaLaunchComparison(account, 'control'); - if (!comparisonControl) throw new Error('comparison_control_failed'); - receipt.comparisonControl = comparisonControl; - if (!comparisonControl.ready || !comparisonControl.cleanup?.confirmed) throw new Error('comparison_control_failed'); - receipt.preflight.headlessChromium = true; - receipt.status = 'passed'; - receipt.reason = 'background_session_ready'; - } else { - receipt.browserPreflight = { stage: 'runtime_import', launchReturned: false, ownedRootCount: 0, - startupPageCount: null, startupPageCategories: [], pageSelected: false, contentSet: false, readbackMatched: false }; - receipt.reason = 'background_browser_runtime_import'; - const { chromium } = await import('playwright'); - const profile = path.join(probe, 'chromium'); - observer = observeBrowserLaunches(new Map([[account.destinationExecutable, profile]])); - launchAttempted = true; - receipt.browserPreflight.stage = 'launch'; - receipt.reason = 'background_browser_launch'; - context = await limit(chromium.launchPersistentContext(profile, nativeDiaLaunchOptions(account.destinationExecutable, env)), 40_000); - receipt.browserPreflight.launchReturned = true; - receipt.browserPreflight.stage = 'ownership'; - receipt.reason = 'background_browser_ownership'; - receipt.browserPreflight.ownedRootCount = observer.children.length; - if (observer.children.length !== 1) throw new Error('background_browser_ownership_failed'); - receipt.browserPreflight.stage = 'startup_pages'; - receipt.reason = 'background_browser_startup_pages'; - const pages = context.pages(); - const startupUrls = pages.map((page: any) => page.url()); - receipt.browserPreflight.startupPageCount = pages.length; - receipt.browserPreflight.startupPageCategories = startupUrls.map(browserStartupCategory); - if (startupUrls.some((url: string) => url !== 'about:blank')) throw new Error('background_browser_startup_page_rejected'); - receipt.browserPreflight.stage = 'page_selection'; - receipt.reason = 'background_browser_page_selection'; - const page = pages[0] ?? await limit(context.newPage(), 5_000); - receipt.browserPreflight.pageSelected = true; - receipt.browserPreflight.stage = 'content_set'; - receipt.reason = 'background_browser_content_set'; - await limit(page.setContent('
background browser ready
'), 5_000); - receipt.browserPreflight.contentSet = true; - receipt.browserPreflight.stage = 'readback'; - receipt.reason = 'background_browser_readback'; - receipt.browserPreflight.readbackMatched = await limit(page.locator('#fixture').innerText(), 5_000) === 'background browser ready'; - if (!receipt.browserPreflight.readbackMatched) throw new Error('background_browser_render_failed'); - receipt.browserPreflight.stage = 'completed'; - receipt.preflight.headlessChromium = true; - receipt.status = 'passed'; - receipt.reason = 'background_session_ready'; - } - } catch (error) { - receipt.status = 'incomplete'; - if (error instanceof Error && ['fresh_identity_mismatch', 'fresh_directory_ownership_mismatch', 'fresh_registered_identity_mismatch', - 'foundation_home_mismatch', 'staged_executable_escape', 'staged_executable_changed', 'pinned_runtime_mismatch', - 'user_keychain_search_unavailable', 'user_default_keychain_unavailable', 'keychain_outside_owned_home_refused', - 'keychain_home_unsafe', 'fixture_keychain_not_owned', 'native_keychain_probe_failed', 'comparison_control_failed', - 'gui_readiness_inputs_changed', 'gui_readiness_budget_exhausted'].includes(error.message)) receipt.blocker = error.message; - if (receipt.browserPreflight) { - receipt.blocker = browserPreflightError(error); - receipt.browserPreflight.error = receipt.blocker; - if (receipt.browserPreflight.stage === 'runtime_import') receipt.browserPreflight.moduleLoad = playwrightModuleLoadFacts(account.snapshot, error); - receipt.browserPreflight.ownedRootCount = observer?.children.length ?? 0; - receipt.browserPreflight.launchAttempts = observer?.attempts ?? []; - } - receipt.initialFailure = { stage: receipt.reason, blocker: receipt.blocker ?? 'native_preflight_failed' }; - } finally { - cleaning = true; - if (receipt.browserPreflight) { - receipt.browserPreflight.launchAttempts ??= observer?.attempts ?? []; - receipt.browserPreflight.rootStatesBeforeCleanup = (observer?.children ?? []).map(child => ({ - pid: child.pid, exitCode: Number.isInteger(child.process.exitCode) ? child.process.exitCode : null, - signal: child.process.signalCode == null ? null - : ['SIGABRT', 'SIGTRAP', 'SIGSEGV', 'SIGBUS', 'SIGKILL', 'SIGTERM', 'SIGILL'].includes(child.process.signalCode) ? child.process.signalCode : 'other', - })); - } - observer?.stop(); - if (context) await limit(context.close().catch(() => {}), 5_000).catch(() => {}); - let stopped = !launchAttempted || (account.launchComparison ? comparisonControl?.cleanup?.confirmed === true : observer?.children.length === 1); - for (const child of observer?.children ?? []) { - const until = performance.now() + 5_000; - try { - await stopOwnedBrowserGroup(child, until, {}); - } catch { stopped = false; } - } - receipt.cleanup.probeBrowsersStopped = stopped; - if (stopped) { - try { - if (keychainChanged && snapshot) { - let restored = true; - for (const args of fixtureKeychainRestoreCommands(snapshot, keychain, keychainCreated)) { - try { run('/usr/bin/security', args); } catch { restored = false; } - } - if (!restored || JSON.stringify(captureUserKeychains(env, [account.home, account.temporary])) !== JSON.stringify(snapshot)) throw new Error('probe_keychain_restore_failed'); - } - receipt.cleanup.probeKeychainRestored = true; - if (existsSync(probe) && realpathSync(probe) === probe) rmSync(probe, { recursive: true, force: true }); - } catch { receipt.cleanupFailure = 'probe_keychain_restore_failed'; } - } - if (!receipt.cleanup.probeBrowsersStopped || !receipt.cleanup.probeKeychainRestored) { receipt.status = 'incomplete'; receipt.reason = 'background_probe_cleanup_incomplete'; } - writePrivateReceipt(preflightFile, receipt, true); - } - if (receipt.status !== 'passed') return 2; - const result = spawnSync(account.bun, ['--no-env-file', '--no-install', '--no-macros', '--config=/dev/null', - path.join(account.snapshot, '.github/scripts/qualify-dia-macos.ts'), '--fresh-account', account.configFile], { - cwd: account.snapshot, env, stdio: 'ignore', timeout: 660_000, killSignal: 'SIGKILL', - }); - return !result.error && result.status === 0 ? 0 : 2; -} - -export async function runFreshAccountQualification(comparisonRuntime?: 'bun' | 'node', guiReadinessOnly = false) { - validateQualificationHost(process.env); - if (comparisonRuntime !== undefined && !['bun', 'node'].includes(comparisonRuntime)) throw new Error('invalid_comparison_runtime'); - if (guiReadinessOnly && comparisonRuntime !== undefined) throw new Error('conflicting_diagnostic_modes'); - if (process.getuid?.() === 0 || Bun.version !== '1.4.2') throw new Error('run_as_unprivileged_pinned_ci_runner'); - const outputRoot = realpathSync(process.env.RUNNER_TEMP!); - const output = path.join(outputRoot, 'dia-native-qualification.json'); - if (existsSync(output)) throw new Error('fresh_output_required'); - const work = realpathSync(mkdtempSync(FRESH_WORK_PREFIX)); - const home = path.join(work, 'home'); - const temporary = path.join(work, 'tmp'); - const snapshot = path.join(work, 'repo'); - const bin = path.join(work, 'bin'); - const browserDirectory = path.join(work, 'browser'); - const archive = path.join(work, 'source.tar'); - const suffix = randomBytes(6).toString('hex'); - const accountName = 'gsdia' + suffix; - const label = 'ai.gstack.dia.' + suffix; - const deadline = performance.now() + 16 * 60_000; - const hostEnv = { HOME: homedir(), PATH: '/usr/bin:/bin:/usr/sbin:/sbin', LANG: 'en_US.UTF-8' }; - let cleanupDeadline = 0; - const run = (command: string, args: string[], timeout = 10_000) => { - const remaining = (cleanupDeadline || deadline) - performance.now(); - if (remaining <= 0) throw new Error('fresh_launcher_deadline'); - return safeCommand(command, args, Math.min(timeout, remaining), hostEnv); - }; - const rootCommand = (command: string, args: string[], timeout = 10_000) => run('/usr/bin/sudo', ['-n', command, ...args], timeout); - let account: FreshAccount | undefined; - let userCreated = false; - let groupCreated = false; - let serviceAttempted = false; - let domainBeforeCreation: ParentDomainObservation | undefined; - let stage = 'fresh_launcher_preflight'; - const receipt: Record = { status: 'incomplete', reason: stage, runId: process.env.GITHUB_RUN_ID, runAttempt: process.env.GITHUB_RUN_ATTEMPT, - counts: { pass: 0, fail: 0, skip: 0 }, launcher: { sessionCreate: true, aquaLogin: false }, - launcherCleanup: { serviceStopped: false, userDomainStopped: false, userProcessesStopped: false, accountRemoved: false, groupRemoved: false, stagingRemoved: false } }; - let workerExit: number | undefined; - let pythonExecutable: string | undefined; - const probeParentDomain = (uid: number) => inspectParentDomain(uid, cleanupDeadline || deadline, hostEnv); - const snapshotProcesses = (phase: string, uid: number) => { - const facts = inspectUidProcesses(uid, cleanupDeadline || deadline, hostEnv); - (receipt.uidProcessSnapshots ??= {})[phase] = facts; - return facts; - }; - try { - rootCommand('/usr/bin/true', []); - for (const directory of [home, temporary, snapshot, bin, ...(guiReadinessOnly ? [] : [browserDirectory])]) mkdirSync(directory, { mode: 0o700 }); - assertDiaSocketPath(path.join(home, 'Library/Application Support/Dia/User Data')); - writeFileSync(path.join(temporary, 'dia-background-preflight.json'), JSON.stringify({ status: 'incomplete', reason: 'fresh_worker_not_started', - nativeCasesRun: false, preflight: { registeredIdentity: false, foundationHome: false, keychain: false, headlessChromium: false } }) + '\n', { mode: 0o600, flag: 'wx' }); - const sourceRevision = run('/usr/bin/git', ['-C', repository, 'rev-parse', 'HEAD']); - if (!/^[0-9a-f]{40}$/.test(sourceRevision)) throw new Error('invalid_source_revision'); - const python = Bun.which('python3'); - if (!python) throw new Error('archive_validator_unavailable'); - pythonExecutable = realpathSync(python); - stage = 'source_archive_preflight'; - run('/usr/bin/git', ['-C', repository, 'archive', '--format=tar', '--output', archive, 'HEAD'], 30_000); - const archiveResult = JSON.parse(run(pythonExecutable, ['-I', '-c', ARCHIVE_CHECK, archive], 30_000)); - if (archiveResult.valid !== true) throw new Error('unsafe_source_archive'); - run('/usr/bin/tar', ['--no-same-owner', '--no-same-permissions', '-xf', archive, '-C', snapshot], 30_000); - if (!guiReadinessOnly) mkdirSync(path.join(snapshot, 'node_modules'), { mode: 0o700 }); - const sourceBun = realpathSync(process.execPath); - const bun = path.join(bin, 'bun'); - copyFileSync(sourceBun, bun); - chmodSync(bun, 0o755); - let guiReadiness: FreshAccount['guiReadiness']; - if (guiReadinessOnly) { - stage = 'gui_readiness_build'; - const source = path.join(snapshot, '.github/scripts/dia-gui-readiness.c'); - const executable = path.join(bin, 'gui-readiness'); - const sourceSha256 = await digest(source); - run('/usr/bin/xcrun', ['clang', '-arch', 'arm64', '-std=c11', '-O2', '-Wall', '-Wextra', source, - '-framework', 'Security', '-framework', 'ApplicationServices', '-o', executable], 30_000); - if (await digest(source) !== sourceSha256 || !inspectMachOArchitectures(executable).architectures.includes('arm64')) throw new Error('gui_readiness_build_unconfirmed'); - chmodSync(executable, 0o755); - guiReadiness = { mode: 'gui-readiness-only', executable, sourceSha256, executableSha256: await digest(executable) }; - stage = 'gui_readiness_original_runner'; - receipt.guiReadiness = { mode: 'gui-readiness-only', qualificationCredit: false, - helper: { sourceSha256, executableSha256: guiReadiness.executableSha256 }, - originalRunner: await runGuiReadiness(executable, guiReadiness.executableSha256, source, sourceSha256, true, hostEnv, - Math.min(5000, deadline - performance.now())) }; - } - let launchComparison: FreshAccount['launchComparison']; - if (comparisonRuntime) { - let executable = bun; - if (comparisonRuntime === 'node') { - const sourceNode = Bun.which('node'); - if (!sourceNode) throw new Error('pinned_node_unavailable'); - const resolvedNode = realpathSync(sourceNode); - const node = JSON.parse(run(resolvedNode, ['-p', 'JSON.stringify({version:process.versions.node,arch:process.arch,os:process.platform,bun:Boolean(process.versions.bun)})'])); - if (node.version !== '24.18.0' || node.arch !== 'arm64' || node.os !== 'darwin' || node.bun) throw new Error('pinned_node_required'); - executable = path.join(bin, 'node'); - copyFileSync(resolvedNode, executable); - chmodSync(executable, 0o755); - } - launchComparison = { mode: 'launch-only', runtime: comparisonRuntime, executable, executableSha256: await digest(executable), - driverSha256: await digest(path.join(snapshot, '.github/scripts/dia-launch-driver.mjs')), - helpersSha256: await digest(path.join(snapshot, '.github/scripts/qualify-dia-macos.ts')) }; - } - let destination: Pick = {}; - if (!guiReadinessOnly) { - const { chromium } = await import('playwright'); - if (require('playwright/package.json').version !== '1.62.1') throw new Error('pinned_playwright_required'); - const originalExecutable = realpathSync(chromium.executablePath()); - let bundle = path.dirname(originalExecutable); - while (!bundle.endsWith('.app')) { - const parent = path.dirname(bundle); - if (parent === bundle) throw new Error('destination_app_bundle_missing'); - bundle = parent; - } - const copiedBundle = path.join(browserDirectory, path.basename(bundle)); - run('/usr/bin/ditto', ['--rsrc', '--extattr', bundle, copiedBundle], 45_000); - const destinationExecutable = realpathSync(path.join(copiedBundle, path.relative(bundle, originalExecutable))); - if (!destinationExecutable.startsWith(browserDirectory + path.sep)) throw new Error('destination_bundle_escape'); - destination = { destinationExecutable, destinationSha256: await digest(originalExecutable) }; - } - const userIds = parseDirectoryIds(run('/usr/bin/dscl', ['.', '-list', '/Users', 'UniqueID'])); - const groupIds = parseDirectoryIds(run('/usr/bin/dscl', ['.', '-list', '/Groups', 'PrimaryGroupID'])); - const used = new Set([...userIds, ...groupIds]); - for (const uid of run('/bin/ps', ['-axo', 'uid=']).split(/\s+/).filter(Boolean)) used.add(Number(uid)); - let uid = 20_000; - while (used.has(uid) && uid < 60_000) uid++; - if (uid >= 60_000) throw new Error('fresh_uid_unavailable'); - stage = 'fresh_user_domain_preflight'; - domainBeforeCreation = probeParentDomain(uid); - receipt.userDomain = { beforeCreation: domainBeforeCreation }; - receipt.candidateIdentity = { uid, accountUidAbsent: !userIds.has(uid), groupUidAbsent: !groupIds.has(uid) }; - const candidateProcesses = snapshotProcesses('before_account_creation', uid); - if (passiveUserDomainState(domainBeforeCreation, uid) !== 'absent' || !('count' in candidateProcesses) || candidateProcesses.count !== 0 - || !receipt.candidateIdentity.accountUidAbsent || !receipt.candidateIdentity.groupUidAbsent) { - throw new Error('candidate_domain_baseline_unconfirmed'); - } - const configFile = path.join(work, 'account.json'); - const metadata = Object.fromEntries(['CI', 'GITHUB_ACTIONS', 'RUNNER_ENVIRONMENT', 'RUNNER_OS', 'RUNNER_ARCH', 'GITHUB_RUN_ID', - 'GITHUB_RUN_ATTEMPT', 'GSTACK_DIA_NATIVE_QUALIFY'].map(name => [name, process.env[name]!])); - account = { work, home, temporary, snapshot, bun, ...destination, uid, gid: uid, account: accountName, - ...(launchComparison ? { launchComparison } : {}), ...(guiReadiness ? { guiReadiness } : {}), - guid: randomUUID().toUpperCase(), groupGuid: randomUUID().toUpperCase(), label, sourceRevision, - archiveSha256: await digest(archive), bunSha256: await digest(bun), configFile, - environment: { ...metadata, HOME: home, TMPDIR: temporary, RUNNER_TEMP: temporary, PATH: bin + ':/usr/bin:/bin:/usr/sbin:/sbin', LANG: 'en_US.UTF-8', - GSTACK_DIA_EXPECT_UID: String(uid), GSTACK_DIA_SOURCE_REVISION: sourceRevision, - ...(destination.destinationExecutable ? { GSTACK_DIA_DESTINATION_EXECUTABLE: destination.destinationExecutable } : {}) } }; - stage = 'fresh_account_creation'; - rootCommand('/usr/bin/dscl', ['.', '-create', '/Groups/' + accountName]); - groupCreated = true; - for (const [name, value] of [['GeneratedUID', account.groupGuid], ['PrimaryGroupID', String(uid)], ['RealName', 'gstack native fixture group']]) { - rootCommand('/usr/bin/dscl', ['.', '-create', '/Groups/' + accountName, name, value]); - } - rootCommand('/usr/bin/dscl', ['.', '-create', '/Users/' + accountName]); - userCreated = true; - for (const [name, value] of [['GeneratedUID', account.guid], ['UniqueID', String(uid)], ['PrimaryGroupID', String(uid)], - ['NFSHomeDirectory', home], ['UserShell', '/usr/bin/false'], ['RealName', 'gstack native fixture'], ['IsHidden', '1'], ['Password', '*']]) { - rootCommand('/usr/bin/dscl', ['.', '-create', '/Users/' + accountName, name, value]); - } - if (!ownsFreshAccount(parseDirectoryRecord(run('/usr/bin/dscl', ['.', '-read', '/Users/' + accountName, 'UniqueID', 'PrimaryGroupID', 'NFSHomeDirectory', 'GeneratedUID'])), account)) throw new Error('fresh_account_not_registered'); - for (const directory of [home, temporary, snapshot, bin, ...(guiReadinessOnly ? [] : [browserDirectory])]) rootCommand('/usr/sbin/chown', ['-R', '-P', `${uid}:${uid}`, directory], 30_000); - writeFileSync(configFile, JSON.stringify(account), { mode: 0o644, flag: 'wx' }); - const json = path.join(work, 'service.json'); - const plist = path.join(work, label + '.plist'); - writeFileSync(json, JSON.stringify(freshLaunchDefinition(account)), { mode: 0o600, flag: 'wx' }); - run('/usr/bin/plutil', ['-convert', 'xml1', '-o', plist, json]); - rootCommand('/usr/sbin/chown', ['root:wheel', configFile, plist, work]); - rootCommand('/bin/chmod', ['644', configFile, plist]); - rootCommand('/bin/chmod', ['755', work]); - stage = 'background_session_bootstrap'; - serviceAttempted = true; - rootCommand('/bin/launchctl', ['bootstrap', 'system', plist]); - stage = 'background_session_probe'; - while (performance.now() < deadline) { - const state = rootCommand('/bin/launchctl', ['print', 'system/' + label]); - const exit = state.match(/^\s*last exit code = (\d+)\s*$/m); - const running = /^\s*pid = \d+\s*$/m.test(state); - if (!running && exit) { workerExit = Number(exit[1]); break; } - await Bun.sleep(500); - } - if (workerExit === undefined) throw new Error('background_session_timeout'); - receipt.reason = workerExit === 0 ? 'fresh_account_qualification_completed' : 'fresh_account_preflight_or_qualification_failed'; - } catch (error) { - receipt.reason = stage; - receipt.failureStage = stage; - if ((error as { diagnostic?: object }).diagnostic) receipt.commandFailure = (error as { diagnostic: object }).diagnostic; - } finally { - cleanupDeadline = performance.now() + 60_000; - if (serviceAttempted && account) { - try { - if (!ownsLaunchService(rootCommand('/bin/launchctl', ['print', 'system/' + label]), account)) throw new Error('service_identity_changed'); - rootCommand('/bin/launchctl', ['bootout', 'system/' + label], 10_000); - receipt.launcherCleanup.serviceStopped = true; - } catch {} - } else receipt.launcherCleanup.serviceStopped = true; - let owned = false; - if (account && userCreated) { - try { owned = ownsFreshAccount(parseDirectoryRecord(run('/usr/bin/dscl', ['.', '-read', '/Users/' + accountName, 'UniqueID', 'PrimaryGroupID', 'NFSHomeDirectory', 'GeneratedUID'])), account); } catch {} - } - if (owned && account) { - const collect = (phase: string) => { - const results: Record = {}; - for (const [name, filename] of [['backgroundPreflight', 'dia-background-preflight.json'], ['qualification', 'dia-native-qualification.json']]) { - try { - if (!pythonExecutable) throw new Error('receipt_reader_unavailable'); - const text = rootCommand(pythonExecutable, ['-I', '-c', PRIVATE_RECEIPT_READ, path.join(temporary, filename), String(account!.uid), work], 3_000); - if (text.length > 1024 * 1024) throw new Error('oversized_receipt'); - receipt[name] = JSON.parse(text); - results[name] = 'captured'; - } catch { results[name] = 'unavailable'; } - } - (receipt.diagnosticCollection ??= {})[phase] = results; - }; - const active = () => { - const facts = inspectUidProcesses(account!.uid, cleanupDeadline, hostEnv); - if (!('count' in facts)) throw new Error('uid_process_snapshot_unavailable'); - return facts.count !== 0; - }; - collect('before_signal'); - snapshotProcesses('before_signal', account.uid); - let domainOwnershipConfirmed = false; - try { - if (!receipt.launcherCleanup.serviceStopped) throw new Error('service_still_loaded'); - const record = parseDirectoryRecord(run('/usr/bin/dscl', ['.', '-read', '/Users/' + accountName, 'UniqueID', 'PrimaryGroupID', 'NFSHomeDirectory', 'GeneratedUID'])); - const before = probeParentDomain(account.uid); - (receipt.userDomain ??= {}).beforeTeardown = before; - const domain = ownedUserDomainTarget(record, account, domainBeforeCreation, before); - domainOwnershipConfirmed = true; - if (domain !== null) { - try { rootCommand('/bin/launchctl', ['bootout', domain], 10_000); } - catch (error) { - receipt.userDomain.teardownCommandFailure = (error as { diagnostic?: object }).diagnostic ?? { failed: true }; - } - } - receipt.userDomain.afterTeardown = probeParentDomain(account.uid); - receipt.launcherCleanup.userDomainStopped = passiveUserDomainState(receipt.userDomain.afterTeardown, account.uid) === 'absent'; - } catch { (receipt.userDomain ??= {}).teardownRefusedOrUnconfirmed = true; } - snapshotProcesses('after_domain_teardown', account.uid); - try { - if (!domainOwnershipConfirmed || !receipt.launcherCleanup.userDomainStopped) throw new Error('user_domain_ownership_or_absence_unconfirmed'); - if (active()) { - const record = parseDirectoryRecord(run('/usr/bin/dscl', ['.', '-read', '/Users/' + accountName, 'UniqueID', 'PrimaryGroupID', 'NFSHomeDirectory', 'GeneratedUID'])); - if (!ownsFreshAccount(record, account)) throw new Error('account_identity_changed'); - try { rootCommand('/usr/bin/pkill', ['-KILL', '-u', String(account.uid)]); } catch {} - const until = Math.min(cleanupDeadline, performance.now() + 10_000); - snapshotProcesses('after_signal', account.uid); - while (active() && performance.now() < until) await Bun.sleep(100); - } - receipt.launcherCleanup.userProcessesStopped = !active(); - } catch {} - snapshotProcesses('after_wait', account.uid); - if (domainOwnershipConfirmed) { - try { - receipt.userDomain.afterWait = probeParentDomain(account.uid); - receipt.launcherCleanup.userDomainStopped = passiveUserDomainState(receipt.userDomain.afterWait, account.uid) === 'absent'; - } catch { receipt.launcherCleanup.userDomainStopped = false; } - } - collect('after_wait'); - if (receipt.launcherCleanup.userProcessesStopped) { - try { - if (!receipt.launcherCleanup.serviceStopped || !receipt.launcherCleanup.userDomainStopped) throw new Error('owned_domain_or_service_still_loaded'); - const record = parseDirectoryRecord(run('/usr/bin/dscl', ['.', '-read', '/Users/' + accountName, 'UniqueID', 'PrimaryGroupID', 'NFSHomeDirectory', 'GeneratedUID'])); - if (!ownsFreshAccount(record, account)) throw new Error('account_identity_changed'); - receipt.userDomain.beforeAccountRemoval = probeParentDomain(account.uid); - receipt.launcherCleanup.userDomainStopped = passiveUserDomainState(receipt.userDomain.beforeAccountRemoval, account.uid) === 'absent'; - if (!receipt.launcherCleanup.userDomainStopped) throw new Error('fresh_uid_domain_reappeared'); - if (active()) { receipt.launcherCleanup.userProcessesStopped = false; throw new Error('fresh_uid_processes_reappeared'); } - rootCommand('/usr/bin/dscl', ['.', '-delete', '/Users/' + accountName]); - receipt.launcherCleanup.accountRemoved = true; - } catch {} - } - } else if (!userCreated) { - receipt.launcherCleanup.userDomainStopped = true; - receipt.launcherCleanup.userProcessesStopped = true; - receipt.launcherCleanup.accountRemoved = true; - } - if (account && groupCreated && receipt.launcherCleanup.accountRemoved) { - try { - const group = parseDirectoryRecord(run('/usr/bin/dscl', ['.', '-read', '/Groups/' + accountName, 'GeneratedUID', 'PrimaryGroupID'])); - if (group.GeneratedUID?.toUpperCase() !== account.groupGuid || group.PrimaryGroupID !== String(account.gid)) throw new Error('group_identity_changed'); - rootCommand('/usr/bin/dscl', ['.', '-delete', '/Groups/' + accountName]); - receipt.launcherCleanup.groupRemoved = true; - } catch {} - } else if (!groupCreated) receipt.launcherCleanup.groupRemoved = true; - const mountSafe = !serviceAttempted || (receipt.qualification ? receipt.qualification.cleanup?.mountDetached === true - : receipt.backgroundPreflight?.status === 'incomplete'); - if (receipt.launcherCleanup.serviceStopped && receipt.launcherCleanup.userDomainStopped && receipt.launcherCleanup.userProcessesStopped && receipt.launcherCleanup.accountRemoved - && receipt.launcherCleanup.groupRemoved && mountSafe && (workerExit !== undefined || !serviceAttempted)) { - try { - const owner = lstatSync(work).uid; - if (realpathSync(work) !== work || path.dirname(work) !== '/private/tmp' || !path.basename(work).startsWith(path.basename(FRESH_WORK_PREFIX)) - || (owner !== 0 && owner !== process.getuid?.())) throw new Error('staging_identity_changed'); - rootCommand('/bin/rm', ['-rf', '--', work], 20_000); - receipt.launcherCleanup.stagingRemoved = true; - } catch {} - } - if (receipt.qualification) receipt.counts = receipt.qualification.counts; - if (account) receipt.launcher = { ...receipt.launcher, uid: account.uid, gid: account.gid, accountGuid: account.guid, groupGuid: account.groupGuid, serviceLabel: account.label, - sourceRevision: account.sourceRevision, archiveSha256: account.archiveSha256, bunSha256: account.bunSha256, destinationSha256: account.destinationSha256 }; - if (account?.launchComparison) receipt.launchComparison = { mode: 'launch-only', runtime: account.launchComparison.runtime, - executableSha256: account.launchComparison.executableSha256, driverSha256: account.launchComparison.driverSha256, - helpersSha256: account.launchComparison.helpersSha256, qualificationCredit: false }; - const clean = Object.values(receipt.launcherCleanup).every(value => value === true); - receipt.workerExitCode = workerExit ?? null; - receipt.status = !account?.launchComparison && !account?.guiReadiness && freshQualificationPassed(workerExit, receipt.backgroundPreflight?.status, receipt.qualification?.status, receipt.launcherCleanup) ? 'passed' : 'incomplete'; - if (account?.guiReadiness) { - receipt.reason = 'gui_readiness_only'; - receipt.guiReadiness.freshUser = receipt.backgroundPreflight?.guiReadiness ?? { available: false, reason: 'fresh_probe_receipt_unavailable' }; - } - if (account?.launchComparison && receipt.qualification?.reason === 'diagnostic_launch_comparison_only') receipt.reason = 'diagnostic_launch_comparison_only'; - if (!clean) receipt.recovery = 'Discard this disposable runner. Do not reuse its account, session, profile, or Keychain.'; - if (receipt.backgroundPreflight?.status !== 'passed' && receipt.backgroundPreflight) receipt.reason = receipt.backgroundPreflight.reason; - writePrivateReceipt(output, receipt); - } - return receipt; -} - -if (import.meta.main) { - try { - if (process.argv[2] === '--fresh-worker') process.exitCode = await freshWorker(process.argv[3]); - else { - const args = process.argv.slice(2); - const readinessOnly = args.length === 1 && args[0] === '--gui-readiness-only'; - if (args.length && !readinessOnly && (args.length !== 2 || args[0] !== '--launch-comparison' || !['bun', 'node'].includes(args[1]))) throw new Error('invalid_comparison_arguments'); - const receipt = await runFreshAccountQualification(args[1] as 'bun' | 'node' | undefined, readinessOnly); - console.log(JSON.stringify({ status: receipt.status, reason: receipt.reason, counts: receipt.counts, artifact: 'dia-native-qualification.json' })); - process.exitCode = receipt.status === 'passed' ? 0 : 2; - } - } catch { - console.log(JSON.stringify({ status: 'incomplete', reason: 'fresh_account_launcher_preflight_failed', counts: { pass: 0, fail: 0, skip: 0 } })); - process.exitCode = 2; - } -} diff --git a/.github/workflows/native-qualification.yml b/.github/workflows/native-qualification.yml index fedf9c2e6..59d6e562f 100644 --- a/.github/workflows/native-qualification.yml +++ b/.github/workflows/native-qualification.yml @@ -1,8 +1,8 @@ name: Native Qualification # Dispatch-only diagnostic campaigns for native browser integrations: owned -# Windows cookie extraction, Windows launch/credential diagnostics, and Dia on -# disposable Apple-silicon Macs. They exercise real browsers and OS services, +# Windows cookie extraction and Windows launch/credential diagnostics. They +# exercise real browsers and OS services, # so they are qualification evidence, not PR gates; they used to live in # windows-free-tests.yml, where their red dispatch runs read as a red PR lane. # @@ -19,9 +19,6 @@ on: options: - cookie-native - windows-native-diagnostics - - dia-native - - dia-launch-comparison - - dia-gui-readiness concurrency: group: native-qualification-${{ github.ref }}-${{ inputs.mode }} @@ -102,53 +99,3 @@ jobs: name: windows-native-diagnostics path: ${{ runner.temp }}/gstack-free-test-*.log if-no-files-found: ignore - - dia-native-qualification: - if: startsWith(inputs.mode, 'dia-') - runs-on: macos-15 - timeout-minutes: 20 - strategy: - fail-fast: false - matrix: - runtime: ${{ fromJSON(inputs.mode == 'dia-launch-comparison' && '["bun","node"]' || '["bun"]') }} - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 - with: - persist-credentials: false - - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 - with: - bun-version: 1.4.2 - - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 - if: inputs.mode == 'dia-launch-comparison' - with: - node-version: 24.18.0 - architecture: arm64 - - name: Install pinned dependencies - if: inputs.mode != 'dia-gui-readiness' - run: bun install --frozen-lockfile - - name: Install the synthetic destination browser - if: inputs.mode != 'dia-gui-readiness' - run: bunx --no-install playwright install chromium - - name: Inspect GUI readiness without browser or Keychain access - if: inputs.mode == 'dia-gui-readiness' - env: - GSTACK_DIA_NATIVE_QUALIFY: '1' - run: bun --no-env-file --no-install --no-macros --config=/dev/null .github/scripts/run-dia-native-qualification.ts --gui-readiness-only - - name: Qualify native Dia discovery, decryption, and import - if: inputs.mode == 'dia-native' - env: - GSTACK_DIA_NATIVE_QUALIFY: '1' - run: bun --no-env-file --no-install --no-macros --config=/dev/null .github/scripts/run-dia-native-qualification.ts - - name: Compare protected native Dia launch without qualification credit - if: inputs.mode == 'dia-launch-comparison' - env: - GSTACK_DIA_NATIVE_QUALIFY: '1' - COMPARISON_RUNTIME: ${{ matrix.runtime }} - run: bun --no-env-file --no-install --no-macros --config=/dev/null .github/scripts/run-dia-native-qualification.ts --launch-comparison "$COMPARISON_RUNTIME" - - name: Preserve only the sanitized qualification receipt - if: always() - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 - with: - name: ${{ inputs.mode == 'dia-gui-readiness' && 'dia-gui-readiness' || inputs.mode == 'dia-launch-comparison' && format('dia-launch-comparison-{0}', matrix.runtime) || 'dia-native-qualification' }} - path: ${{ runner.temp }}/dia-native-qualification.json - if-no-files-found: error diff --git a/.github/workflows/windows-free-tests.yml b/.github/workflows/windows-free-tests.yml index d5ec9bb6e..6d19e5b48 100644 --- a/.github/workflows/windows-free-tests.yml +++ b/.github/workflows/windows-free-tests.yml @@ -18,7 +18,7 @@ name: Windows Free Tests # the artifact. # # Native browser qualification campaigns (Windows cookie extraction, launch -# diagnostics, Dia on macOS) are dispatch-only in native-qualification.yml. +# diagnostics) are dispatch-only in native-qualification.yml. on: pull_request: diff --git a/.gstack/pregate.json b/.gstack/pregate.json index f9cb2832c..0454e74f3 100644 --- a/.gstack/pregate.json +++ b/.gstack/pregate.json @@ -20,5 +20,5 @@ "windows-free-tests.yml/windows-free-shard": "bun run scripts/test-free-shards.ts --windows-only --list" }, "warn": [], - "strays": { "allow": [] } + "strays": { "allow": ["modules/loadouts.json", "modules/loadouts.schema.json"] } } diff --git a/.gstack/ship-policy.json b/.gstack/ship-policy.json index d188eced9..d50acbc38 100644 --- a/.gstack/ship-policy.json +++ b/.gstack/ship-policy.json @@ -14,5 +14,5 @@ "pr_count": { "default_pr_count": 1, "split_requires_owner": true }, "maintainers": ["garrytan"], "train": { "gate_workflow": "evals.yml", "free_workflow": "free-tests.yml", "full_gate_check": "gstack/full-gate", "record_artifact": "gstack-train-record", "max_size": 3, "fill_hours": 1, "screen_selection": "gstack-paid", "trial_reservation_usd": 1.5 }, - "min_gstack_version": "1.91.146.0" + "min_gstack_version": "1.91.299.0" } diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index c91ac7c04..7dc9c3546 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -199,7 +199,7 @@ Storage reset and authentication verification are independent opt-ins. `--clear- ### Shell injection prevention -The browser registry (Chrome, Chromium, Brave, Edge, Windows-only Opera and Opera GX, and macOS-only Comet, Arc, Dia) is hardcoded. Database roots come from known platform locations; profile directory input is validated. Keychain access uses `Bun.spawn()` with explicit argument arrays, not shell string interpolation. +The browser registry (Chrome, Chromium, Brave, Edge, Windows-only Opera and Opera GX, and macOS-only Comet and Arc) is hardcoded. Database roots come from known platform locations; profile directory input is validated. Keychain access uses `Bun.spawn()` with explicit argument arrays, not shell string interpolation. ### Egress receipt ledger (v1.63.0.0) diff --git a/BROWSER.md b/BROWSER.md index 886016ced..13aa70909 100644 --- a/BROWSER.md +++ b/BROWSER.md @@ -218,7 +218,7 @@ What changes when the fallback is active: | On Aside | On the fallback engine | |---|---| -| Your sessions are already there | `/setup-browser-cookies` copies selected cookies from Chrome, Chromium, Brave, Edge, Windows-only Opera and Opera GX, or macOS-only Comet, Arc, and Dia; verify sign-in separately, or log in once in headed mode | +| Your sessions are already there | `/setup-browser-cookies` copies selected cookies from Chrome, Chromium, Brave, Edge, Windows-only Opera and Opera GX, or macOS-only Comet and Arc; verify sign-in separately, or log in once in headed mode | | You watch the tabs the agent opens in Aside | `/open-gstack-browser` (or `$B connect`) shows the headed GStack Browser with the side panel | | Sign-in wall: sign in inside Aside, say "done" | `$B handoff` opens a visible Chrome at the same page; `$B resume` continues | | One `aside repl` script per flow, fresh session each time | Persistent daemon: cookies, tabs, and localStorage carry over between `$B` calls | @@ -568,7 +568,7 @@ from `snapshot`, or `@c` refs from `snapshot -C`. Full table: #### Choosing a source and checking sign-in -Select the source browser and account/profile explicitly. The picker recognizes Chrome, Chromium, Brave, Edge, Windows-only Opera and Opera GX, and macOS-only Comet, Arc, and Dia. It shows current profile names from `Local State`, falling back to Preferences and then the directory name, with directory labels to distinguish duplicate names. `--profile` takes that directory (`Default`, `Profile 2`), not its display name. Without it, only a sole relevant profile is selected; ambiguity or unreadable profiles require a choice. The omitted-browser default remains `comet` for CLI compatibility, not as a recommendation. The picker opening link is one-use and expires after five minutes. +Select the source browser and account/profile explicitly. The picker recognizes Chrome, Chromium, Brave, Edge, Windows-only Opera and Opera GX, and macOS-only Comet and Arc. It shows current profile names from `Local State`, falling back to Preferences and then the directory name, with directory labels to distinguish duplicate names. `--profile` takes that directory (`Default`, `Profile 2`), not its display name. Without it, only a sole relevant profile is selected; ambiguity or unreadable profiles require a choice. The omitted-browser default remains `comet` for CLI compatibility, not as a recommendation. The picker opening link is one-use and expires after five minutes. For direct import, first navigate to a page matching `--domain`. Example after choosing Chrome's `Profile 2`: diff --git a/CHANGELOG.md b/CHANGELOG.md index 093488ff6..f08e5adb4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## [Unreleased] +## [1.91.318.0] - 2026-10-29 **/office-hours now has eval tasks for the shared skill eval, and /write-skill's diet locks its tasks before a paid run.** gstack-evals' Lane A will re-check the office-hours diet from #3525. To do that it needs office-hours' tasks in gstack's contract format, a sidecar for what Lane A adds, and a diet step that commits the lock a paid run requires. #3525 never committed the task set GSTA-134 ran, so these tasks rebuild it from the pilot's written summary. @@ -15,6 +15,312 @@ ### Tests - `test/skill-eval-tasks.test.ts` checks office-hours' `tasks.json` against the contract. It also checks that each `tasks.ext.json` entry names a task in `tasks.json` and uses only known keys. No existing test, threshold or allowlist changed. +## [1.91.317.0] - 2026-10-29 + +**Registered gstack skills now say when to use them where the harness model reads them, and OpenClaw lists the task skills directly.** HARN-5's paid cells showed OpenClaw and Hermes listing gstack's skills while the model rarely opened them. Router lines kept only each skill's first sentence and dropped its "Use when asked to ..." trigger, and Hermes's skills index shows only the first 57 characters of a description, which for gstack was capability prose. This release changes only what gstack writes into its own skills folders. Use rates are not claimed yet: HARN-5's fixed panel measures them next. + +### Changed +- **Router lines lead with the trigger** (`gstack-harness`, every router-mode target: OpenClaw, dots, `generic` and `--print`). Each line opens with the skill's own trigger sentence, or, when the description has none, `Use for:` and the skill's `triggers:` list, within 160 characters. The router's description now leads with task verbs (review, debug, QA test, plan, ship) in its first 200 characters, within the 300-character budget. The wording rule lives in `lib/skill-triggers.ts`. +- **Hermes descriptions open with a trigger list of at most 57 characters** (`frontmatter.descriptionLead` in `hosts/hermes.ts`), for example `Use for: review this pr, code review, check my diff.`, followed by the description without its own trigger sentence, which the lead repeats, so no Hermes render grows. Claude Code and every other host render their descriptions as before. +- **OpenClaw registers in `hybrid` mode by default**: `gstack-review`, `gstack-investigate`, `gstack-qa`, `gstack-ship` and `gstack-plan-eng-review` are top-level skills and the `gstack` router carries the rest. Dumped through OpenClaw 2026.10.6's own `buildSkillSnapshot`/`prepareSkillsForPrompt` with its 19 eligible bundled skills, hybrid's skills section is 10,290 characters in full format (budget 18,000). `--skills all` falls to compact format at 17,971 characters, and `--skills router` is 6,701. `--skills router` and `--skills all` remain, and a mode switch now removes the empty folders the previous mode left behind. +- **`--context ` is opt-in for OpenClaw and Hermes too**: the block is written only into the file named, after a `gstack-harness: context block: ( scope)` line. Setup, upgrades and refresh never add one and do not re-add a block you deleted. A second `--context` file keeps the first, because the ledger keys blocks by file. The block text follows the mode (with `--skills all` it names no router path). Uninstall now restores each file byte for byte (the blank separator line, a missing final newline and a file gstack created are undone). +- `HARNESS_MODE_UNSUPPORTED`'s fix text and docs/hosts.md describe Hermes's listing, not its loader, and docs/hosts.md states registered, listed and used as separate facts. + +### Fixed +- Re-registering an OpenClaw, Hermes or dots registration without `--context` (what setup and `gstack-harness auto` do) no longer cuts a block the user opted into. + +### Added +- `HARNESS_CONTEXT_REFUSED`: `--context` refuses `SOUL.md` (in any letter case), and for Hermes a new rules file that would outrank rules Hermes loads now: a file of an earlier group (`.hermes.md`/`HERMES.md` before `AGENTS.md` before `CLAUDE.md`), an earlier name in the same folder (`.hermes.md` before `HERMES.md`, `AGENTS.override.md` before `AGENTS.md`), or a `.hermes.md`/`HERMES.md` below one in a parent folder, which Hermes takes as the nearest. + +### Gate integrity +- `test/harness-register.test.ts`: three expectations change with the byte-for-byte restore and blocks keyed by file. The generic cut now expects the original bytes, without the extra newline. The second `--context` case now expects both blocks kept and both restored where it used to expect the first block cut. The OpenClaw router case passes `mode: 'router'` because the default is now hybrid. New cases cover router lines, Hermes leads (at most 57 characters), hybrid with mode switches through refresh and uninstall, context opt-in, refusal and scope, the CLI scope line, and Hermes's threat scanner on every block variant. The scanner case runs when `GSTACK_HERMES_SRC` names a Hermes checkout and is skipped otherwise. More new cases cover the same-folder and nearest-parent refusals, pre-blockpad ledgers, refresh keeping a block the user edited, `--json --context` output, and the Hermes check outside a git repository; new `test/skill-triggers.test.ts` covers the wording rule's fallbacks and cuts. +- `test/fixtures/skill-md-size-allowlist.json`: the Hermes pins for `gstack-autoplan` (108,982 to 108,891) and `gstack-plan-eng-review` (128,708 to 128,655) go down to the new render sizes, as the size guard directs. +- New `test/session-kind-marker.test.ts`: a marker-only environment (`GSTACK_SESSION_KIND=spawned`, no `GSTACK_CAPY`) gets the same soft admission from `bin/gstack-install-verdict.sh` and `lib/install-verdict.ts`. A ratchet fails when a file in `bin/`, `lib/`, `hosts/` or `scripts/` reads or sets `GSTACK_SESSION_KIND` outside its 13-file inventory; a planted-reader control and a comments-only control check it. + +## [1.91.316.0] - 2026-10-29 + +**/ship takes a token cap and stops cleanly at it, and long runs hand their heavy segments to fresh-context children.** On gstack-evals#31 a /ship spent 54M tokens against a 25M cap because the cap was only a number in a brief; #26, whose agent read the counter after every step, stopped at 39.40M of 40M. `/ship --token-cap 25M` (or `GSTACK_SHIP_TOKEN_CAP`) now admits each step and dispatch batch only when it fits, and a run started from a long-lived context, or one whose per-call charge passes 150k at Step 7 or Step 12, runs that segment in a fresh child. + +### Added +- **`gstack-ship-budget`** (`lib/ship-budget.ts`, `lib/ship-budget-cli.ts`, `lib/ship-handoff.ts`): an admission cap on a per-run token ledger under `/ship-runs//` (its own schema; only `withFileLock` is shared with `lib/spend-ledger.ts`). `start`, `check` (the `BUDGET:` line, `verdict=continue|delegate|stop`, a `RESERVATION:` id per admitted step or batch), `settle`/`release`, `handoff`/`launch`/`verify-handoff`/`return`/`reconcile`, `resume` (cap raises need `--approved-by` and the owner's words; `--rebuild-from-record`; restore from a private Drive checkpoint) and `close`. Exit 0 continue/delegate, 3 stop, 2 usage. Each meter is a versioned contract, and there are three: the Capy root counter (`--reading`), Claude Code journal usage (`lib/claude-usage.ts`, bound by `--session` or an echoed nonce) and `--meter estimate`. +- **`gstack-review-log --start ... --reservation `**: under a cap, a dispatch without an unspent, one-shot reservation refuses before launch (`BUDGET_CHECK_SKIPPED`), and `--finish` settles it. Without a cap nothing changes. +- **/ship**: the skeleton's Budget paragraph (`--token-cap`, `--resume `, `--continue `) and a new `budget-handoff` section with the meter recipes, reservations, stop and resume, and the delegate flow per host. +- **Result codes** `BUDGET_CAP_REACHED`, `BUDGET_READING_MISSING`, `BUDGET_READING_REJECTED`, `BUDGET_METER_UNAVAILABLE`, `BUDGET_LEDGER_INVALID`, `BUDGET_CHECK_SKIPPED`, `HANDOFF_PIN_MOVED` with docs/troubleshooting.md anchors; `lib/ship-budget-calibration.json` seeded from #19, #26 and #31. +- **Docs**: docs/ship-budget.md (linked from docs/unattended.md), and a paragraph each in the Capy skill's SKILL.md and captain.md. + +### Tests +- `test/ship-budget.test.ts`: the cap boundary, batch overshoot, the #31 replay, spend above a reservation, the no-cap path, meters and epochs, exit codes, start and segment delegation, the full handoff chain with an idempotent reconcile, moved pins and a tampered brief, refused and interrupted children, stop and RECOVER, checkpoint restore into an empty state root, ledger rebuild, concurrent ledgers, and an unchanged `gstack-wtree`. +- `test/ship-budget-review-log.test.ts`, `test/claude-usage.test.ts`, `test/ship-budget-calibration.test.ts` (leave-one-out), `test/ship-budget-section.test.ts`. + +## [1.91.315.0] - 2026-10-29 + +### Changed +- **Stacked PRs** (Fixes #3570): after a stack parent lands and the child is retargeted to the base with the base merged in, `carry --base ` compares HEAD's product diff against the base with the range the receipt reviewed against the parent branch. That is the recorded `product_patch_id`, or the range against `origin/` for an older receipt. HEAD's side is its whole product diff against the base, so a parent's `package.json` change that never reached the base refuses too. Equal carries with the reason `stack parent landed` and rebinds the receipt's `base` to the base; anything else refuses. Until now every stacked child paid a full /ship once its parent merged (gstack-evals#19). + +### Tests +- `test/ship-receipt-carry-squash.test.ts`: a child carries after its parent squash-merges and main is merged in, names main as its base, and carries again across a later main merge. A test-only child carries. A child edited after the merge, a parent that never landed, a parent `package.json` change that never reached main, and a merge that keeps the child's tree over the landed parent refuse. An older receipt falls back to `origin/` and refuses once that branch is deleted. + +## [1.91.314.0] - 2026-10-29 + +**A later autoplan gate that asks nothing new is now answered with the owner's earlier words instead of another round trip.** Captains were carrying approvals across gate revisions by hand (GSTA-140 reused a rev-1 "Do it" on rev 2; ALPH-50 lost about 27 minutes to one), and a replay over 23 recorded runs found 14 later gates, 8 of them holding only post-cap delta items. + +### Added +- **Carry-forward** (`lib/autoplan-carry.ts`): when gate_rev N+1 asks nothing new and gate_rev N was fully answered by the owner with `rec` or "do it", gstack answers N+1 with those recorded words and prints `CARRIED: gate_rev= <- gate_rev= …`; anything else prints `CARRY: no ()` and goes to the owner. `--no-carry-forward` on the first `next` turns it off. +- **"do it" covers new low-risk items.** When the owner's own words were "do it", a new item that changes no scope, cost, direction or plan text takes its recommendation, is marked `carried_under: do it`, and is listed in the approval record and the Captain brief as not shown to the owner. A Captain's "do it" never counts. +- **Delta check.** A "plan changed after cap" item gets one reviewer from another model family on the delta first (`CARRY_CHECK:`, `gstack-autoplan check`), within a per-gate spend cap (`--carry-check-cap`, default $5). High or above, no reviewer, an owner answer, or a plan edit after dispatch leaves the gate for the owner and releases the reservation. The verdict is recorded on `gate.json`, the decision rows and `decisions.tsv`. +- **`eli5` in gate.json**: the plan's `## ELI5` and the four approvals-shape sections; `gstack-gate render` opens page 1 with them, and the Captain brief requires `## ELI5` (older runs render as before). +- **`gstack-approvals import --autoplan --stack b1,b2`** writes the same rows to every branch of a stack, or to none when one branch is unknown. +- **`REVIEW_ESTIMATE:`** on the first `next`: phases, voices, rounds, attempts and the reservation total. + +### Changed +- `lib/decision-trail.ts` holds the trail append rules shared by `gstack-decision-trail` and the carry. + +## [1.91.313.0] - 2026-10-29 + +**The PII scanner stops flagging two kinds of ordinary text: a bare power-of-two or hash constant in code, and a package@version-style filename.** Eval artifacts and PR bodies that print a PRNG range or name a versioned results file no longer raise a MEDIUM phone or email finding, and real phone numbers and addresses next to them still report. + +### Fixed +- **`lib/redact-patterns.ts`**: `pii.phone.e164` skips a bare number that is exactly a power of two from 2^30 through 2^49, one less than one, or one of eleven well-known 32-bit hash and PRNG constants. The same digits written with a `+`, spaces, dashes, dots or parentheses still report (#3577). +- **`lib/redact-patterns.ts`**: `pii.email` skips a filename whose part after the `@` is a version or tag followed by file extensions no top-level domain uses, or a dotted version followed by an extension that doubles as one. A file named after a real address, an address at a numeric domain such as 163.com, and an address under a top-level domain that doubles as an extension (`.sh`, `.md`) still report (#3576). + +### Tests +- `test/redact-constant-and-at-filename.test.ts`: pins both exemptions in both directions, including files named after a real address. + +## [1.91.312.0] - 2026-10-29 + +**An install check run from inside /ship no longer upgrades gstack under it.** /ship's docs step runs `scripts/install.sh --for document-release`. That run fast-forwarded the checkout from 1.91.298 to 1.91.299 in the middle of a lane's /ship, so the receipt writer's rules changed partway through the run (#3571). + +### Fixed +- **`bin/gstack-capy-session`**: in install mode, a live workflow lease under 120 minutes old held by the caller's own process chain now skips the self-upgrade: `SELF_UPGRADE: skipped (a gstack run in this session holds a workflow lease on this installation: pid

(m ), so the upgrade waits until the lease is 120 minutes old; …(UPGRADE_BUSY))`. The install still certifies the installed revision and the trailer stays ok with `behind=`. `bin/gstack-upgrade` deliberately ignores the caller's own lease, and an install started from inside the run passed that check. Each `gstack-skill-start` renews the lease. The age bound matters on Capy, where the leased pid is the machine's long-lived `capy-server`, so a lease is never released by its process exiting. An older lease, or none, upgrades as before, and `GSTACK_UPGRADE_FORCE=1` or a hand-run `bin/gstack-upgrade` still moves the checkout. + +### Tests +- `test/capy-skill-wrapper.test.ts`: an install run under a shell that holds a fresh lease leaves HEAD where it was and stays ok. Once that lease is 121 minutes old, with its holder still alive, the same install upgrades. Before this change the first run printed `SELF_UPGRADE: done 1.0.1 -> 1.0.2`. + +## [1.91.311.0] - 2026-10-29 + +**A sealed policy can now refuse `sealed//tasks.json` while allowing the `MANIFEST.json` beside it, and can catch `HELDOUT/` with a `heldout` glob.** The sealed guard only had deny globs and one-commit waivers, so the gstack-evals layout, which keeps a public manifest of hashes and counts next to its sealed tasks, needed a fresh `.gstack/sealed-allow.tsv` line for every manifest commit (gstack-evals wiki/board/2026-10-28-gsta-9-sealed-manifest-glob-gap.md). Their first draft also wrote `sealed/**`, which never matched their nested `tasks//sealed/` directories, and garrytan/gstack-evals#3 (dc54796) hand-listed `Sealed/`, `HELDOUT/` and other case variants. + +### Added +- **`sealed.allow_paths`** (`lib/sealed-guard.ts`): globs that exempt publishable files from `sealed.path` and `sealed.transcript`, applied after the deny globs and before sha waivers. They are read from the destination base branch only, so a push cannot widen its own exceptions; a pushed copy is still validated and refuses when malformed. Text rules still read an exempt file, so a manifest that quotes a sealed answer still refuses. An entry whose file name contains `**` or is only wildcards before its extension (`**`, `sealed/*`, `**/*.json`) is refused. Each exempt path prints `exempt commit (sealed.allow_paths )` on every push. +- **`sealed.case_insensitive: true`**: `paths` and `transcripts` match regardless of case, so `**/heldout/**` also refuses `HELDOUT/` and `HeldOut/`. The value is the base branch's OR the pushed one, because it only tightens. `allow_paths` never fold case. Separator and spelling variants such as `hold-out/` still need their own globs. + +### Changed +- `gstack-pregate sealed` prints `exempt=` after `waived=` on its `SEALED:` line (`policy=` stays last), and `--json` carries an `exempt` array. Both bins build their error report through one `sealedErrorReport`. +- An unknown `sealed` key now says to upgrade gstack if the key comes from a newer one. A gstack older than this release refuses `allow_paths` and `case_insensitive` this way on every push and `gstack-pregate run`, so a repository raises `min_gstack_version` before landing either key. +- `docs/pregate.md` § Sealed output explains glob anchoring: patterns match from the repository root, so `sealed/**` misses `tasks/x/sealed/a.json` and the docs say to write `**/sealed/**`. It also documents case handling, exceptions and the version skew. + +### Gate integrity +- This is a gate edit: `allow_paths` lets the sealed guard pass files it refused before, but only from the reviewed base branch. No existing test, threshold or allowlist changed. New cases in `test/sealed-guard.test.ts` (10) and `test/pregate-guards.test.ts` cover an allowed exception, a non-matching one, an exception added on the pushed head, a text rule inside an exempt file, transcripts, the waiver order, the error report, case folding in both directions and the root-anchoring example. + +## [1.91.310.0] - 2026-10-29 + +**The cookie workflow judge now asks for structured output, so a quote the model forgets to escape can no longer fail the gate.** Train 42 went red because both of its `setup-browser-cookies/SKILL.md workflow` samples came back as free text with a bare quote inside `reasoning` ("one --domain per run"), and neither parsed. The GSTA-91 comparison had measured that failure: 2 of 144 free-text samples failed to parse, against 0 of 72 with the schema. + +### Changed +- **Cookie workflow judge transport:** `setup-browser-cookies/SKILL.md workflow` now sends `WORKFLOW_JUDGE_RESPONSE_SCHEMA`, released on GStack Minder's ruling: "GStack Minder, 2026-10-29: release the GSTA-91 hold; a07 is matched by old-b; free-text parse errors cost train 42". Its model, thresholds (4/3/4), sample count and case kind are unchanged. The ruling is recorded in `test/fixtures/judge-calibration/cookie-workflow/release.json`, and the held comparison stays recorded as held. + +### Tests +- `test/cookie-workflow-judge-input.test.ts` runs the registered cookie callback through the real `callJudge` and pins its request to the schema. It replays train 42's two replies (msg_011CgVnRtVj5vyLvb56m6KJH, msg_011CgVne5GStZ6f9pRoCvgWE): their free-text bytes do not parse, and the same judgment returned as schema output scores and passes. `test/judge-calibration.test.ts` reads the release record. Both fail without the transport change. + +### Gate integrity +- Gate edit: the cookie judge's response transport moves from free text to the JSON schema, on the ruling above. No threshold, sample, trial, deadline or case-kind change. The Haiku free-text failure pin in `test/llm-judge-frontier.test.ts` is untouched. + +## [1.91.309.0] - 2026-10-29 + +**The judged review and Eng prose each give one rule where the paid judges kept finding two, and a judge that runs out of time now says what it was waiting on.** Every sample of two red panels on #3527's screens (review 40617200857, plan-eng-review 40634787316), attempt and rerun, named the same contradictions; a third red (ship, train 35 gate 40660626349) hit the 120 s judge deadline with nothing logged but "No completed model response". + +### Fixed +- **`/review` Step 5.8**: an unresolved non-gate defect (an unanswered question) is recorded as `open`, so every finding has a record action. A repeat pass's reruns of superseded probes are revalidation, so they run after smoke expiry, in the same probe directory; earlier provisional QA sections link checkpoints and only the final pass runs the once-only `materialize`. +- **`/plan-eng-review`**: the shared Voice now loads once. Eng no longer carries a near-copy whose only difference was its em-dash clause; the Scope gate's format precedence says required formats keep their em dashes. +- **`/benchmark` Phase 6 example**: the hero image recommendation no longer suggests lazy-loading (that delays the largest paint) and names one remedy, as the rule under it asks. + +### Changed +- **Judge cancellations leave evidence.** When a judge request is cancelled (the workflow judge deadline), `callJudge` prints one `llm-judge-aborted` line: elapsed time, wrapper attempts and 429 waits, HTTP requests and statuses (so the SDK's own retries show), connection, first and last stream event times, the open block type, thinking and text character counts, message and request ids, and the reason (at most 200 characters). Counts only, never content; an observer that throws cannot change a judge result. Deadlines, effort, samples and thresholds are unchanged. + +### Tests +- `test/review-workflow-clarity.test.ts` and `test/eng-scope-entry-ap.test.ts` pin the repaired rules; both fail with the prose change stashed. +- `test/llm-judge-stream.test.ts` and `test/llm-judge-abort.test.ts` replay a stream cancelled mid-thinking, a stream with no events, one cancelled after headers, an SDK-retried 429, a cancelled 429 wait, an event the observer cannot read and an overlong reason, with no-abort controls; each fails with the helper change stashed. `test/workflow-judge-cache.test.ts`'s SDK stream stand-ins gain the real stream's `on()`. +- Focused paid judge runs: review 4/4/4 at 1bdc4ce and again at 3463250, plan-eng-review 3/5/4 at 1bdc4ce ($0.18). + +### Gate integrity +- No threshold, sample, trial, deadline or case-kind change. `scripts/harness-version.json` records the `llm-judge.ts` change as non-behavioral (no series reset). Generated SKILL.md size pins for review and plan-eng-review were lowered to their new sizes on every host. + +## [1.91.308.0] - 2026-10-29 + +**`gstack-restamp` no longer cuts a four-part package.json version to three parts in a repo whose convention is four.** On garrytan/gbrain#7878, `/ship` restamped gbrain's `package.json` to `"0.60.483"` beside `VERSION` `0.60.483.0`; gbrain requires the two to match and its CI version gate fails when they drift, so the stamp had to be reverted by hand. The version stage called `gstack-version-bump write`, which always stores the npm-valid three-part form in the manifest (decision 11, which is why gstack's own `package.json` reads `1.91.298`). + +### Fixed +- **`lib/restamp.ts`**: the version stage keeps the full version in the manifest when the policy lists it in `stamp_paths` or `stamp_files` and the base's copy holds four parts, and the stage detail says so (`wrote 0.60.483.0 (package.json keeps four parts: …)`). The form is read at the base, like the policy, so a branch an earlier restamp already cut to three parts goes back to four. Every other repo, gstack included, still gets the npm-valid form, and a four-part manifest the policy does not list still migrates to three parts as decision 11 says. +- **`bin/gstack-version-bump write`**: new `--manifest-form npm|full` (default `npm`); `full` writes the version as given to the manifest and its npm lockfiles. It has no effect when the version path is itself a JSON manifest. + +### Tests +- `test/restamp-four-part-manifest.test.ts`: a gbrain-shaped fixture (four-part `VERSION` and `package.json`, the manifest in `stamp_files`, bun, no npm lockfile) restamped from an unstamped branch and from a branch already carrying its stamp (both failed before the fix with `"0.60.483"`), from a branch an older restamp cut to three parts, and with the manifest listed through `stamp_paths`. gstack's shape (three-part manifest and lockfile) and an unlisted four-part manifest keep their current results. +- `test/gstack-version-bump.test.ts`: `--manifest-form full` keeps four parts in the manifest and lockfile; an unknown form exits 2 before anything is written. + +## [1.91.307.0] - 2026-10-29 + +**/ship now reviews in proportion to what the diff can break: light, standard or full depth.** A diff with 50 or fewer runtime lines gets one batched specialist plus the native adversarial pass, a larger runtime diff gets the class's specialists scoped to their hunks, and gate code or any classifier error gets the full review as before. The receipt records the depth and the queue refuses a receipt below what the head needs. Before this, a 12-line fix paid for the same reviewer fan-out as a change to the merge gate. The backtest that would have let light depth drop the adversarial pass was inconclusive (9 light-eligible PRs, 5 with attributable findings, below the 15 the plan required), so light keeps it. + +### Added +- **Review depth** (`lib/review-depth.ts`, `lib/review-collect.ts`, `gstack-review-plan`): `REVIEW_DEPTH:` (depth, runtime lines, the rules hash, reasons), `GATE_SCAN:` bound to HEAD, one `DEPTH_ERROR:` per input that fails closed to full (with the input, the cause and the repair), and per-reviewer `DIFF_CMD:` pathspecs. Runtime lines leave out docs, tests and outputs registered with a command in the base branch's `.gstack/generated.json`, read at the base commit. `--depth-floor standard|full` only raises the depth. A fixed or open blocker, or a CRITICAL, raises light to standard for the rest of the invocation. +- **Receipt fields**: `gstack_version` and `review_depth` (`{ depth, class, runtime_lines, rules, base, registry, gate_scan: { tagged, head }, reasons }`), computed at the checked-out head. `write --head` must be HEAD. `review_loop_exception` (`write --review-loop-exception`) records an owner-accepted stop after a fix-check edit with the fix-check's head and findings, and the PR body repeats its line word for word (Fixes #3559). +- **Queue checks** (`gstack-ship-queue ready`, `train build`): the depth the head needs is recomputed from git and a lower receipt is `QUEUE_RECEIPT_DEPTH_RAISED`, with the receipt's depth, the required depth, reasons and inputs on a `REVIEW_DEPTH:` line. A malformed owner exception, a body that dropped its line, or a fix-check head that is not the bound head or its ancestor is `QUEUE_RECEIPT_EXCEPTION_INVALID`. The queue reads the same committed range as the writer and trusts a recorded gate scan only when it names the full bound commit. A receipt with neither new field predates depth receipts and is accepted as legacy. + +### Changed +- **Carry and depth**: a carry recomputes the depth at the new head, rebinds the gate scan, and refuses when the new head needs more (a test change that skips a test is gate class). It also refuses a `--head` other than the checked-out HEAD, a receipt with `gstack_version` but no `review_depth`, and an owner exception that no longer stands, since the queue would refuse each of them. Tracked edits in the checkout make the write-time gate scan unavailable, which records `full`. +- **`gstack-diff-scope --head `**: the scope signals for the committed range only, with no working-tree or untracked files; an unknown sha is `SCOPE_ERROR=no_head` and a missing merge base `SCOPE_ERROR=no_merge_base`. +- **`.gstack/ship-policy.json`**: `min_gstack_version` rises from 1.91.146.0 to 1.91.299.0. + +### Tests +- `test/ship-receipt-depth.test.ts`: write records the depth bound to HEAD and refuses another `--head`. The queue refuses light on a standard head, a current receipt with no depth and an unbound gate scan, and accepts a legacy receipt. A plain test change carries and rebinds the scan, while a skipped test refuses the carry. The review-loop exception is refused without a fix-check, with a foreign head or without its body line, and the queue refuses a body that dropped the line. +- `test/review-depth.test.ts`, `test/review-collect.test.ts`, `test/review-plan-cli.test.ts`: the depth matrix, the fixed light set, fail-closed errors and the registry read at the base commit. A `package.json` version line that also carries other keys is not stamp-only. +- `test/diff-scope.test.ts`: `--head` reads the committed range and ignores working-tree edits, and refuses an unknown sha. + +## [1.91.306.0] - 2026-10-29 + +**A /ship receipt now survives a base merge that only regenerates outputs, and a rebase onto the tree it reviewed.** On gstack-evals, two full /ship reruns came from a merge of main that changed a generated file's diff (U1 paid about 28M tokens for its rerun), and one came from a rebase whose tree was byte-identical to the reviewed one (about 60M). Each re-reviewed code the receipt already covered. For crews the rule is now a single line. Merge main into a reviewed branch, and never rebase it. + +### Changed +- **`gstack-ship-receipt carry`**: an output of an entry with a `command` in origin/'s `.gstack/generated.json` counts as `generated`, not product, when the `--pregate` result for HEAD lists it under the `regen` check's new `proven` paths and that check ran the same base registry. Without that evidence, for a file that matches an output glob but that the command never writes, and for an entry with no command or one only the branch registers, the output stays product. +- **`gstack-pregate` `regen` check**: a fresh entry with touched outputs runs its command a second time in the scratch worktree with those outputs deleted, and records the ones it recreates byte-identically as `proven`. The verdict still comes from the first run, so a generator that reads its own output passes as before and proves nothing. +- **Carry across rewritten history**: `write` records `head_tree` and `product_patch_id`, and each carry rebinds both and keeps earlier trees in `carry.trees`. A head that is no longer an ancestor carries only when its tree is one the receipt covers and its product patch-id against the current base matches; it records `carry.ancestry: rewritten` and needs no old commit, so a fresh clone carries too. A different tree is the new `RECEIPT_CARRY_TREE_MISMATCH`. The reviewed tree on a base that moved under it is `RECEIPT_CARRY_PRODUCT_CHANGED`. +- **Docs**: docs/ship-policy.md#receipt-carry opens with a four-row table: merge with the product unchanged, merge that changes product, rebase onto a covered tree, and any other rebase. docs/captain.md and captain/templates/CREW.md say to merge main in and never rebase a reviewed branch, and the troubleshooting entries for the carry refusals match the new rules. + +### Tests +- `test/ship-receipt-carry-rewrite.test.ts`: a rebase onto the covered tree carries from a fresh clone that never fetched the old head, a different tree refuses with `RECEIPT_CARRY_TREE_MISMATCH`, the reviewed tree on a moved base refuses, and a merge that changes only a registered output's diff carries with a pregate whose regen check proved it and refuses without one or with a pregate from another registry, and a hand-written file under an output glob that the generator never writes stays product. +- `test/gstack-ship-receipt.test.ts`: the written receipt's key order includes `head_tree` and `product_patch_id`. + +## [1.91.305.0] - 2026-10-29 + +**You can now render gstack with whole skills, skill sections, model overlays or preamble pieces left out, as a byte-exact tree with a lock file, so an eval can measure which instructions a model actually needs.** Garry asked for "95% of the outcome but with 50% of the token use", and the free ceiling measurement on train gate run 40705984271 found skill text is about 21% of billed eval cost (35 of 103 tests), so trimming it per model is worth measuring. Nothing changes for anyone today. Every model rung and unknown models load `full`, and the committed SKILL.md files are byte-identical to the previous release. A smaller loadout ships only after GSTA-2 measures it. + +### Added +- **`bin/gstack-modules`**: `list` prints every module id (`skill:`, `section:`, `overlay:`, `preamble:`) with its source and pin; `validate` checks `modules/loadouts.json`; `render --host (--loadout | --modules full,-,+) --out-dir ` renders one loadout with the same `--model`, `--install-root` and `--plan-mode` setup uses, and writes `loadout.lock.json` (spec sha256, excluded ids, per-file sha256 and bytes). +- **`modules/loadouts.json`** (with a JSON schema): rungs `frontier`, `strong`, `mid`, `light`, the model-id table, pinned modules and named loadouts. Every rung and `unknown` map to `full`. +- **Safety pins**: the start command, plan-mode rules, the question format, completion status, the unattended profile, /ship's review army and adversarial pass, the router and `/gstack-upgrade` can never be excluded, directly or by excluding the skill that holds them (`MODULE_PINNED`). +- **Renders refuse instead of guessing**: an unknown loadout or module, a malformed spec, a rendered file that still points at an excluded skill or section (`MODULE_EXCLUSION_UNSAFE`), or an `--out-dir` that an earlier render did not write (`RENDER_DEST_NOT_OWNED`) each exit 2 with a fix line and a `docs/troubleshooting.md` anchor, and never fall back to `full`. A failed render leaves the earlier one in place. +- **`docs/loadouts.md`**: terms, commands, how to build an eval arm, and how a loadout changes (only with a cited GSTA-2 run). + +### Changed +- `gen:skill-docs` accepts `--loadout` and `--modules` with an `--out-dir` outside the checkout; a selection with exclusions aimed at the committed tree is refused. Excluded sections render a one-line `Not loaded in the loadout` stub, and `{{IF_SECTION:}}` guards remove skeleton text that belongs to a section (office-hours' second-opinion offer and visual-design phase, plan-design-review's review-sections self-check). `gstack/llms.txt` lists only the skills a render includes. + +### For contributors +- New `test/module-loadouts.test.ts` covers the manifest, selection, pins, the render filter, the CLI and the byte-identical `full` render. `.gstack/pregate.json` allows the two new `modules/` files as strays. `test/gen-skill-docs-prune-stale.test.ts`'s copied fixture now links `scripts/modules.ts`; no assertion, threshold or budget changed. + +## [1.91.304.0] - 2026-10-29 + +**Running the Capy installer for a second workflow on the same machine no longer takes away the first one's admission.** /ship's docs step runs `scripts/install.sh --for document-release`, and that run replaced the `--for ship` install verdict with its narrower one, so the rest of /ship refused with "the install verdict certified for=document-release, which does not cover codex that ship needs" until someone reran `--for ship` (#3561, seen on gstack-evals#13). + +### Fixed +- **`bin/gstack-capy-install`**: an ok run keeps what an earlier ok install certified for the same checkout, project, HEAD and Bun. The verdict's `required` list becomes the union, pins count as planning-only only when both runs skipped them, and `for` lists every workflow (`for=ship,document-release`). The installer says so in one line. A failing run, a new HEAD or another Bun still replaces the verdict, and the review-voice profile still never narrows a fuller one. + +### Tests +- `test/gstack-capy-install.test.ts`: `--for ship` then `--for document-release` leaves one ok verdict that admits both workflows through `verdictProblem`; a `--check --for ship` keeps it; after a new commit, `--for document-release` replaces it and ship is refused again. It failed before this change. + +## [1.91.303.0] - 2026-10-29 + +**`gstack-pr-shots` no longer edits your `.gitignore` in the middle of /ship, so the pregate stays fresh and the ship receipt gets written.** When a repository tracks files under `.gstack/` (`pregate.json`, `ship-policy.json`), git does not read `.gstack/` as ignored, and the browse daemon that `gstack-pr-shots` starts appended `.gstack/` to the tracked `.gitignore`. The tree changed after pregate and the receipt writer refused with PREGATE_STALE (#3560, seen on gstack-evals#13). + +### Fixed +- **`browse/src/config.ts`**: the browse state dir still writes its own `.gstack/.gitignore` (`*`), and when git does not already ignore `.gstack/` the line goes to the repository's `info/exclude` (resolved with `git rev-parse --git-path`, so linked worktrees share it). The project's `.gitignore` is never written. Outside a git repository nothing is written beyond the state dir. + +### Tests +- `test/pr-shots.test.ts`: a repository that tracks `.gstack/pregate.json` runs `gstack-pr-shots` with a browse stub that runs the daemon's real state-dir setup; the `gstack-wtree` fingerprint and the `.gitignore` are unchanged afterwards. It failed before this change. +- `browse/test/config.test.ts`: the cases that pinned the `.gitignore` append now pin `info/exclude`: written once, no duplicate, a missing trailing newline added, `info/` created when absent, a warning in `browse-server.log` when it cannot be written, and nothing written outside a repository. + +## [1.91.302.0] - 2026-10-29 + +**Three flaky gate cases from the 2026-10-28 daily flaky pass are repaired: shared-libs-review-index-flags, ship-exploratory-late-input (with ship-exploratory-plan-checks, which failed the same way), and the real-Chromium cookie-auth positive case.** Each red was diagnosed from its captured run before the fix, and each repair has a free test that fails without it. + +### Fixed +- **Shared-code reuse no longer lets a review rewrite the index flags it checks.** In train gate 40619718717, the reviewer ran `git update-index --really-refresh` while gathering evidence. That cleared the assume-unchanged flag the checker reads, so the trial's prerequisites went stale. Step 1 of the /review and /ship shared-code reuse section now says evidence gathering is read-only and names that command. Nearby wording was tightened so the section keeps its exact size. +- **The /ship exploratory-QA cases follow Step 9's review plan again.** Since #3527, Step 9 runs `gstack-review-plan --base main`. The fixture refused that command (paid screen 40707142223, both ship-exploratory-plan-checks trials) and never said that the plan's adversarial-native and outside-voice lines belong to Step 11, which is outside the fixture's Steps 8–9 excerpt. In gate 40664336141, ship-exploratory-late-input reported pass while listing that Step 11 pass as remaining work. Once the plan ran, it dispatched the state-machines specialist, and review-army tells the parent to write the merge-base sha into that specialist's diff command. The fixture refused `git diff `, which failed both ship-exploratory-unavailable trials in this PR's screen 40737741454. +- **The real-browser cookie-auth checks no longer time out under load.** The positive case and the rejection cases that return early now use the product's default 15 s limit instead of a 400 ms test-only value. That value timed out twice on Windows and once on a Ubicloud VM. + +### Gate integrity +- `test/helpers/qa-callers-fixture.ts`: the caller command interface now admits the `gstack-review-plan` forms ship Step 9 names (`--base main` with its `--pass`, `--last` and finding flags, or `--fix-check-prompt` with literal file arguments), only at the fixture's installed helper path. Pipes, other arguments, other binaries and calls without the fixture's runtime are refused, and `test/qa-caller-review-plan.test.ts` checks these as negative controls. The ship prompt names the Step 11 boundary. The interface also admits the fixture's own merge base (at least 7 hex characters) as a literal diff base, bare or in review-army's `DIFF_BASE= && git diff "$DIFF_BASE"` specialist form, and the prompt declares it. Any other sha, a shorter prefix, other Git options and composition are still refused. No threshold, trial count, case kind or timeout changed. +- `browse/test/cookie-auth-verification.test.ts`: GStack Minder approved dropping the shared `timeoutMs: 400`, which came from a84b0b5b6 (#2964) as a fixture value no product path uses (`--verify-auth` callers run under `MAX_TIMEOUT_MS` 15000). The identity mismatch, missing and ambiguous cases keep 400 ms because they resolve only at the deadline, and the 15 s default would exceed bun's 5 s test timeout. The explicit 100 ms, 30 ms, 60 s-cap and invalid-timeout tests are unchanged. +- New free tests: `test/qa-caller-review-plan.test.ts` (replays both 40707142223 captures and both 40737741454 ship-exploratory-unavailable captures, and runs the real plan for all four ship cases) and `test/shared-libs-index-flags-readonly.test.ts` (replays the captured refresh against the assume-unchanged fixture, with a read-only control). +- `scripts/lib/windows-curation.ts`: `test/shared-libs-index-flags-readonly.test.ts` is curated off the Windows subset. Its fixture starts the review through `bin/gstack-review-log`, a bash script, which windows-latest cannot launch (Windows Free Tests run 40727825859, shard 5). + +## [1.91.301.0] - 2026-10-29 + +**Four paid gate cases that went red on 2026-10-28 without a product defect now pass on the runs that failed them.** Each repair replays the failing run as a free test that fails without it. + +### Fixed +- **plan-design-with-ui-scope**: the Design focus question counts when it puts "review all 7 areas or focus" in its rated title and letters its options ("A) Review all 7 areas"), as gate 40664336141 asked it. +- **plan-review-report**: the case turns the default-on outside voice off with `codex_reviews: disabled`, the skill's documented switch. In gate 40660626349 both reds ran out of the 20-turn cap before writing the report, and the outside voice had used 4 of their 21 turns. The cap is unchanged. +- **shared-libs-review-path-eligibility**: a Bash read that printed a whole evidence file counts even when a later command in the same call failed, as one did in run 40617200857. +- **office-hours-brain-writeback**: the fake `gbrain` saves a page piped on stdin, the form the SAVE_RESULTS template shows, as well as `--content`. + +### Gate integrity +- `designFocusBoundary` (test/skill-e2e-plan-design-with-ui.test.ts) accepts the all-7 offer in the rated title line and rejects issue-numbered option sets. Seven new negative controls cover a missing rating, a /7 rating, no focus, another count, an offer below the title, issue-numbered options and a single option. +- `hasTrustedSharedLibsCheck` (test/helpers/shared-libs-review-start-evidence.ts) accepts an errored Bash read only in a multi-command call whose output holds the exact evidence source. Start, check and finish calls must still succeed. The existing "errored caller read" control still fails, and five new controls do too. +- The plan-review-report case input now disables the outside voice. Outside-voice coverage is not part of this case's assertions. + +## [1.91.300.0] - 2026-10-28 + +**Three free tests that went red at random now fail only when the code under test is wrong.** Today's flaky-test pass (GSTA-139) traced two Linux reds to their fixtures and fixed a third that was certain to fail under load. No product code changed. + +### Fixed +- **`test/ubicloud-runner.test.ts`**: the watchdog cases expected exit 124 but got 2 or 0, about one run in 62. The cause was not timing. The fake `ssh` had a `*-O*` case arm, meant for `ssh -O exit` but never matched by it, and it caught any remote command whose checkout path held `-O`. That happened whenever the fixture's temporary directory name started with `O`. The arm is gone, and a new test runs a checkout named `ubi-run-O1x2y3`. +- **`test/ship-queue-train.test.ts`, `test/gstack-ship-queue.test.ts`**: `coordinatorClone` now clones the fixture origin with `--no-local`, through git's transport like a real clone of GitHub, instead of copying `origin.git/objects` file by file. Every push into the fixture origin leaves a detached `git maintenance run --auto` there. The local transport drops the shard's `GIT_CONFIG_COUNT` maintenance-off setting, so that process still creates and deletes `objects/maintenance.lock` after the push returns. Two runs failed with `failed to copy file … No such file or directory` on a loose object. The process that removed that object was not identified; the transport clone never lists the directory at all. +- **`test/qa-fix-loop-fixture.test.ts` late-timeout**: the scenario ran its real setup inside a 1000 ms mocked work budget under a 1160 ms deadline, so on a loaded machine the attempt never started (0 of 10 runs under 24 busy loops). It now uses #3413's qa-only fix: the clock stands still from the test body's start until the capture begins, and the deadline is the registered 6080 ms outer budget (20 of 20 under the same load). + +### Gate integrity +- `test/qa-fix-loop-fixture.test.ts` late-timeout asserts that the capture gets exactly 1000 ms, where it used to accept anything between 0 and 1000, and its test deadline is the registered outer budget rather than budget − 5000 + 80 ms. If the workflow's outer budget drops back to the bare work budget, the scenario still fails. A new `slow-setup` scenario keeps the check the old range assertion gave. A controlled clock spends 400 ms in setup, and the capture must get exactly 600 ms. If the workflow passed the whole work budget to the capture instead of what setup left, it would fail. + +## [1.91.299.0] - 2026-10-28 + +**The Captain brief now says what `rec` does when a gate carries earlier decisions.** At a gate after the owner already answered some items, such as a round-cap gate, `gstack-owner-brief render --captain` listed each item's recommendation ("keep the plan as written", `rec resolves to d2a`) while `gstack-gate render` and `gstack-autoplan answer --reply rec` keep the carried answer (`d2b`). A Captain relaying the brief told the owner the opposite of what their one-word reply would record (#3546). The brief now takes its choices from the same resolver `gstack-gate render` uses. + +### Fixed +- **Carried choices in the Captain brief**: each choice under "What we need from you", the header, the change-something example and the relaying agent's `rec resolves to` line use the `rec` resolution from `parseReply`, given the answers already recorded at this gate the way `gstack-autoplan answer` reads them. A carried item shows the owner's earlier answer marked `(your answer at gate_rev N, carried forward)`, an item answered earlier at this gate is marked `(your answer at this gate)`, and the header says how many answers `rec` keeps. + +### Tests +- `test/captain-brief.test.ts` drives a fixture autoplan run to a round-cap gate with three carried decisions, renders `gstack-gate render` and `gstack-owner-brief render --captain` for it, and asserts the same `rec` resolution and choice labels. A second case records a partial answer at that gate and checks the brief's `rec` against what `gstack-autoplan answer --reply rec` then records. The negative control strips the carried decisions and expects both renders to fall back to the recommendations. + +## [1.91.298.0] - 2026-10-28 + +**Dia is gone from gstack.** `/setup-browser-cookies` and `cookie-import-browser` no longer list Dia as a cookie source, and the Dia qualification harness is deleted. That harness was a set of macOS campaigns that never qualified a native import, and its `dia-launch-comparison` free test was failing the merge train on Ubicloud runners. Cookie import from Comet, Chrome, Chromium, Arc, Brave, Edge, Opera and Opera GX is unchanged. + +### Removed +- **Dia as a cookie source**: the registry entry, the `dia` alias, and every Dia mention in the `cookie-import-browser` description, the browse and setup-browser-cookies skills, `gstack/llms.txt`, README, BROWSER.md, ARCHITECTURE.md, CONTRIBUTING.md, docs/skills.md and docs/TESTING_INTERNALS.md. +- The `dia-native`, `dia-launch-comparison` and `dia-gui-readiness` modes are gone from `native-qualification.yml`, along with their job, the four `.github/scripts` files behind them, and their three `browse/test` files. Those tests also leave the free-test duration seed and the test typecheck baseline. +- **`clang` on the Ubicloud free-suite VM**: only the Dia GUI readiness test compiled C on Linux. + +### Tests +- The cookie tests that used Dia as their macOS fixture browser now use Arc, which has the same `User Data` layout and Keychain shape: numbered-profile discovery, Keychain denial, the credential deadline, the Node bundle import and the picker UI. The historical cookie-workflow approval fixture adds one reverse edit so it still rebuilds the approved prompt byte for byte. No threshold or allowlist changed. + +## [1.91.297.0] - 2026-10-28 + +**The terminal agent on Windows no longer waits on PowerShell to learn its own start time, so it boots in about a second and a slow PowerShell can no longer leave it without an identity.** Every agent boot ran `powershell.exe Get-CimInstance` with a 2 s timeout, twice when started standalone. On a loaded `windows-latest` runner one launch took 0.94 s at the median and up to 10.8 s, so agent boot took 2.4 to 2.8 s at the median and 5.1 s on a runner's first boot, past the owner-watchdog test's 5 s window. Measured again after the change under the same load: 0.86 to 0.91 s at the median, 1.18 s at most, 120 of 120 boots inside the window. + +### Fixed +- **`browse/src/terminal-agent-control.ts`**: under Bun the Windows start time comes from `GetProcessTimes` in-process and is written as the same `/Date()/` value PowerShell's `CreationDate` gives (147 of 147 processes matched), so records from earlier releases and from the Node daemon, which keeps the PowerShell reader, still compare. The kill-time check still reads the command line through PowerShell, and a process is stopped only when it carries the record's `--agent-gen`. On Windows a start time that disagrees between the two readers no longer reads as gone when the live process carries that generation or its command line cannot be read, so no second agent starts beside it. + +### Tests +- `browse/test/process-liveness-windows.test.ts`: the in-process reader, the Node fallback, the kill-time command-line check, a reader disagreement and the unreadable path (never signalled, never gone, blocks a second agent), plus two Windows-only cases: the in-process value equals PowerShell's `CreationDate`, and a live agent whose identity cannot be read blocks a second one. +- `browse/test/path-security-realpath.test.ts` builds its 8.3 alias with `GetShortPathNameW` instead of a PowerShell launch that stalled for 30 s in Windows Free Tests 40624015029 and was reported as "8.3 short names are disabled". A failed lookup now fails the test instead of skipping it. +- `browse/test/cookie-import-native-job.test.ts` prints the Restart Manager receipt when the owner assertion fails, so the next red names its cause. + +### Gate integrity +- Test 5 in `process-liveness-windows.test.ts` expected the PowerShell mock's `fixture-owner-start` as the owner start time on every platform. On Windows that expectation followed the old implementation, so it moved with the product. It now requires the in-process value, equality with a real read, and no PowerShell query for the owner. The Linux and macOS assertion is unchanged. + +## [1.91.296.0] - 2026-10-28 + +**The docsync gate stops failing ship-docsync-current and ship-docsync-store when the agent asks the docs helper for its usage in the middle of a line of reads.** Five red paid trials since 2026-10-27 each failed on a single refused line. In four, the agent ended a line of reads with `gstack-docs-candidate --help` (screen 40558235014, gate 40600731931, and screen 40627127462 twice). In the fifth, gate 40643690306, the line included `git tag`. v1.91.185.0 tried to stop the first slip by moving the "own Bash call" rule into the sentence that names `--help`, and the slip came back four times. The helper's `--help` prints its usage and returns before it touches Git or any file, so refusing it protected nothing. The 2026-10-27 backstop red (40515158924, `toContain`) ran on a tree from before #3516, which had already fixed it. + +### Fixed +- **`test/helpers/docsync-observer.ts`**: a line of reads may now include the installed candidate's `--help`, either alone or after `snapshot` or `compare`, optionally with `2>&1` or `2>/dev/null`. It counts as a neutral read, the same way a joined Git read does, but never when it is fed by a pipe and never in a line that also runs `cd`. `git tag`, `git tag -l` and `git tag --list` are now accepted as Git reads, alongside the branch listings #3516 added. A tag operand or any other option is still refused. +- **`test/helpers/docsync-interface.ts`**: the fixture interface declares both changes. It names the candidate's `--help` as the one exception to the own-call rule, and it adds tag listings to the Git read list. + +### Tests +- `test/docsync-command-grammar.test.ts` replays the five captured lines, which were refused before this change, and checks that each is now accepted, while the same line with `; git add app.ts` appended is still refused. Negative controls that stay refused: pipe-fed, `| sh`, `>` redirect and `cd` forms; `snapshot` and `compare` joined to reads; `-h`, `--version` and `--help snapshot`; the `~` and foreign helper paths; the lifecycle helpers' `--help` joined to reads; and 13 tag writes or filtered listings. + +### Gate integrity +- This is a gate edit, because the docs detector now accepts more lines. The test that pinned the joined `--help` as refused now expects it to be accepted. Focused paid trials at e967634: ship-docsync-current PASS ($0.84; its agent did join `--help` onto a line of reads) and ship-docsync-store PASS ($0.84). + ## [1.91.295.0] - 2026-10-28 **Deleting or renaming a test no longer fails pregate with PREGATE_NO_LANE.** A PR that removed a test file, or renamed one, failed `lanes` because the removed path had no test lane of its own, so cleanup PRs needed a hand-written `dependencies` entry to pass (#3529). Pregate now accounts for a removed test the way it accounts for an edit. A renamed test runs under its new name, a deleted test runs the remaining tests of the files it exercised, and either one runs the tests of any file that still names it, such as a curation list. Every waived test is printed on its own line, so the reason is visible in the gate output. Removing any other file still needs a lane, as before. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 37eece64e..d2c84855a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -194,7 +194,7 @@ the new defaults. | Clear pregate's test tier on a machine under 8 cores ([remote gate](docs/pregate.md#remote-gate)) | `gstack-pregate --stage tests --remote --spend-cap 2 --timeout 2700 --allow-repo-commands` (same command keyed or keyless) | Keyed: one billed 16-vCPU VM, about 7 minutes and $0.06 for the whole free tier, worst case $0.38; keyless: free, local parallel shards, practical for small selections only (98 files took 103 s on 4 cores) | Keyed: `UBICLOUD_API_KEY`; keyless: nothing | | Run the curated Windows-safe subset | `bun run test:windows` (CI: six `windows-latest` jobs) | Free | Windows, Git Bash | | Refresh the Windows duration seed | `gh workflow run windows-free-tests.yml --ref -f record_durations=true`, then commit the `free-test-durations-windows` artifact | Free CI runners | Pushed branch, `gh` with workflow rights | -| Run a native Windows or Dia qualification campaign | `gh workflow run native-qualification.yml --ref -f mode=` ([modes](docs/TESTING_INTERNALS.md#windows-free-lane)) | Free CI runners | Pushed branch, `gh` with workflow rights | +| Run a native Windows qualification campaign | `gh workflow run native-qualification.yml --ref -f mode=` ([modes](docs/TESTING_INTERNALS.md#windows-free-lane)) | Free CI runners | Pushed branch, `gh` with workflow rights | | Preview which paid cases my diff selects | `bun run eval:select` (PR profile; `--profile full` for the plain touchfile selection) | Free | — | | Preview the CI paid slice plan | `bun run scripts/test-paid-shards.ts --tier periodic --list --slice-budget 420 --jobs 2` (diff-selected; `EVALS_ALL=1` lists everything) | Free | — | | Run paid coverage for my change (agents: detached) | `bun run eval:bg:pr` (foreground: `bun run test:pr`) | API spend for the selected cases only; about 10 minutes when dispatched to CI | Dispatch: a clean, pushed HEAD and `gh`. Local fallback: `ANTHROPIC_API_KEY`, Claude Code CLI, a plain terminal | @@ -205,6 +205,7 @@ the new defaults. | Validate periodic cases on a branch in CI | `gh workflow run evals-periodic.yml --ref ` (periodic lane only) | CI runners + API spend | Pushed branch, `gh` with workflow rights | | Validate periodic cases plus the weekly gate census on a branch | `gh workflow run evals-periodic.yml --ref -f include_gate_census=true` | CI runners + API spend | Pushed branch, `gh` with workflow rights | | Run the opt-in ML, gitleaks and Swift checks | `gh workflow run platform-qualification.yml --ref ` | Free CI runners | Pushed branch, `gh` with workflow rights | +| Render one module loadout as an eval arm ([loadouts](docs/loadouts.md)) | `bin/gstack-modules render --host claude --modules full,-section:/ --out-dir

` (`--loadout full` for the control) | Free, about a second per host | Bun 1.4.2 | | Look at past local eval runs | `bun run eval:list` / `eval:compare` / `eval:summary` | Free | Local eval history | | See a case's pass rate across recent weekly runs | `bun run eval:pass-rates --case ` | Free | `gh` with repo read access | | Measure one red case alone against the ship bar (MEETS 9/10) | `bun run scripts/ship-measure.ts measure --case --round baseline` ([bar](docs/TESTING_INTERNALS.md#ship-measure)) | API spend for 10 trials (12 for behavior); asks above $2/trial, stops at $25/case | Same as paid coverage | diff --git a/README.md b/README.md index a7519ae27..222b96893 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ installs and passes the conformance tests but has no certification run yet; | GitHub Copilot CLI | experimental | `--host copilot` → `~/.copilot/skills/gstack-*/` | `/gstack-office-hours` | advisory, not blocked | Codex CLI, signed in | `./setup --host copilot` | | Antigravity CLI | experimental | `--host agy` (or `--host antigravity`) → `~/.gemini/antigravity-cli/skills/gstack-*/` | `/gstack-office-hours` | advisory, not blocked | Codex CLI, signed in | `./setup --host agy` | | Slate | instruction-only | `--host slate` (points at the Claude install; Slate reads `.claude/skills`) | `/office-hours` via the Claude install | advisory, not blocked | — | `./setup --host claude` | -| OpenClaw | experimental | `--host openclaw` (one `gstack` router skill in OpenClaw's skills folder; automatic when setup runs inside OpenClaw; ACP route in [docs/OPENCLAW.md](docs/OPENCLAW.md)) | ask for the task; the agent opens the `gstack` skill | advisory, not blocked | — | `./setup --host openclaw` | +| OpenClaw | experimental | `--host openclaw` (five task skills and one `gstack` router skill in OpenClaw's skills folder; automatic when setup runs inside OpenClaw; ACP route in [docs/OPENCLAW.md](docs/OPENCLAW.md)) | ask for the task; the agent opens the matching task skill or the `gstack` router | advisory, not blocked | — | `./setup --host openclaw` | | Hermes | experimental | `--host hermes` (every skill in `$HERMES_HOME/skills/gstack`; automatic when setup runs inside Hermes) | ask for the task, or `/gstack-review` | advisory, not blocked | — | `./setup --host hermes` | | GBrain (mod) | instruction-only | `--host gbrain` (brain-aware variants ship from the GBrain repo) | — | advisory, not blocked | — | — | @@ -169,7 +169,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | `/retro` | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. `/retro global` runs across all your projects and AI tools (Claude Code, Codex, Gemini). | | `/browse` | **QA Engineer** | Give the agent eyes. Drives your [Aside](https://aside.com) browser first — your real sessions, real clicks, real screenshots — through deterministic `aside repl` scripts. No Aside? It falls back to gstack's own Chromium: real clicks, ~100ms per command, and `/open-gstack-browser` shows it headed with sidebar, anti-bot stealth, and auto model routing. Every other browser skill stands on it. | | `/scrape` | **Data Extractor** | Pull structured data off a web page — tables, lists, prices — in your Aside browser with the page's real logged-in state. On the fallback browser, `/skillify` turns the flow into a permanent browser-skill that runs in ~200ms next time. | -| `/setup-browser-cookies` | **Session Manager** | Copy selected cookies from Chrome, Chromium, Brave, Edge, Windows-only Opera and Opera GX, or macOS-only Comet, Arc, and Dia into gstack's bundled browser. Choose your profile and domains; copying and sign-in verification are separate. Only needed on the fallback path — Aside already has your sessions. | +| `/setup-browser-cookies` | **Session Manager** | Copy selected cookies from Chrome, Chromium, Brave, Edge, Windows-only Opera and Opera GX, or macOS-only Comet and Arc into gstack's bundled browser. Choose your profile and domains; copying and sign-in verification are separate. Only needed on the fallback path — Aside already has your sessions. | | `/autoplan` | **Review Pipeline** | One command, fully reviewed plan. Runs CEO → design → DX → eng review automatically (eng always last, so the shipping gate reviews the final amended plan) with encoded decision principles. Surfaces only taste decisions for your approval. | | `/spec` | **Spec Author** | Turn vague intent into a precise, executable spec in five phases (why, scope, technical with mandatory code-reading, draft, file). Outside-review quality gate before filing (Claude Code on Codex; Codex on other harnesses; blocks below 7/10), fail-closed secret redaction, dedupe against existing issues, archive to `$GSTACK_STATE_ROOT/projects/$SLUG/specs/` for team-corpus recall. `--execute` spawns `claude -p` in a fresh worktree; `/ship` auto-closes the source issue on merge. Plan-mode aware. | | `/learn` | **Memory** | Manage what gstack learned across sessions. Review, search, prune, and export project-specific patterns, pitfalls, and preferences. Learnings compound across sessions so gstack gets smarter on your codebase over time. | diff --git a/TODOS.md b/TODOS.md index d2be7ab44..7d7aa202d 100644 --- a/TODOS.md +++ b/TODOS.md @@ -2,6 +2,11 @@ ## NEXT PRIORITY +### P1: review-depth receipt follow-ups (filed 2026-10-28, from the #3567 /ship plan audit) + +- **Derive `carry.covers` from depth.** A carried receipt's `covers` is the fixed `CARRY_COVERS` list (lib/ship-receipt.ts); derive it from the recorded `review_depth` so a light review's carry does not claim the checks a full review ran (plan item 5, deferred at /ship). **Effort:** S. **Priority:** P1. +- **Bound the queue's recompute time.** `gstack-ship-queue` recomputes each receipt's needed depth at READY and at train build; add a test that a five-PR train recomputes within a fixed budget, so a large diff cannot stall the train. **Effort:** S. **Priority:** P1. + ### P3: `/codex --effort` follow-ups (filed 2026-10-11, from the #3146 autoplan review) - **Show the effort that ran.** Step 0.5 prints `CODEX_EFFORT: (source: /codex --effort)` once, but the result footers do not repeat the effort, so it scrolls away. Add an `Effort:` line to the review, challenge and consult result footers. Blocked on skeleton bytes in `codex/SKILL.md` (cap 60,200). **Effort:** S. **Priority:** P3. @@ -783,15 +788,15 @@ Each item was deferred with a reason during the `/claude-api prompt-audit` clean format errors, so it stays on today's request), the default workflow judge (landed, but one provider refusal on corpus item f03 under the new prompt, matched by one under the old prompt) and the cookie workflow judge (GSTA-91: - held on one new false pass on a07, zero new-request format errors, so it stays - on today's request; today's request itself false-passes a07 in `old-b` and on + held on one new false pass on a07, zero new-request format errors; the hold was + released on GStack Minder's 2026-10-29 ruling and it now sends the schema; today's request itself false-passes a07 in `old-b` and on both valid `old-a` samples, and a08 in `old-a`, so the prose step targets those). Reuse `test/fixtures/judge-calibration` and `scripts/judge-calibration.ts`. Priority P3. Effort M. - **Uncalibrated workflow-judge configurations** — build a corpus and calibrate schema transport for the frontier configuration (review/SKILL.md workflow); it stays on today's request. The cookie configuration (setup-browser-cookies/SKILL.md workflow) has a corpus and a held comparison-1 - (GSTA-91), so it also stays on today's request. After any transport change, + (GSTA-91); it moved to the schema on GStack Minder's 2026-10-29 release ruling. After any transport change, re-run the review and cookie workflow judges. Priority P3. Effort M. - **Claude model auto-detection for the skill overlay** — when no `claude_overlay_model` is set, detect the Claude Code model (`ANTHROPIC_MODEL`, diff --git a/VERSION b/VERSION index c7e4e95c1..5cbe83882 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.91.295.0 +1.91.318.0 diff --git a/agents-digest/gstack-AGENTS.md b/agents-digest/gstack-AGENTS.md index 358c63a00..28a0e1743 100644 --- a/agents-digest/gstack-AGENTS.md +++ b/agents-digest/gstack-AGENTS.md @@ -1,4 +1,4 @@ -# gstack digest v1.91.295.0 — regenerate/re-copy after upgrading gstack +# gstack digest v1.91.318.0 — regenerate/re-copy after upgrading gstack Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed for agent hosts without a full skill install. The full skills add workflows, diff --git a/autoplan/DRIVER.md b/autoplan/DRIVER.md index f1e1a3f96..875ea1068 100644 --- a/autoplan/DRIVER.md +++ b/autoplan/DRIVER.md @@ -26,7 +26,7 @@ line yourself; gstack never writes the plan. 1. `next` prints one `ATTEMPT: phase=

voice=native|outside prompt= result=` per voice. Dispatch the native prompt to a subagent on your model and the outside prompt to - a subagent on another model family (or `gstack-outside-voice run`). Each writes `result=`. + a subagent on another model family (or `gstack-outside-voice run`). Each writes `result=`. The first `next` also prints `REVIEW_ESTIMATE:` (most attempts and reservations the review can take). 2. Submit each voice exactly once (`BOUND:`). Both voices in closes the phase (`PHASE_CLOSED:`). 3. Repeat `next` until `status=gate_pending` (`GATE: gate_rev=`); render it with `gstack-gate render

/gate.json --all` and relay every page with the two cost lines printed under `GATE:`: `GATE_SPEND:` (spent, worst case, cap, headroom, attempts; host-subagent attempts are priced unknown and counted at their reservation, so quote their real figure from the host's cost view) and `GATE_REC_COST:` (the phases `rec` can reopen and the estimate for them, an upper bound; `gate_cost` in `--json`). You never approve the gate for the owner. Offer `rec` (every recommendation, plan changes included) as the default. @@ -38,6 +38,7 @@ line yourself; gstack never writes the plan. 5. `REOPENED: ` means loop `next` again (Eng last). `APPROVED:` means `export` (`DISPATCHES: est_input_tokens=`, relative). 6. Rounds: one by default; a second only for High or Critical findings; cap 2 (`--max-rounds`). A `revise` whose decisions all resolve below High prints `APPLIED: without re-review (below High)`. At the cap with High open, `ESCALATE: evidence sufficient, decision needed`: relay it, never ask for another round. +7. Carry-forward ([docs/unattended.md#carry-forward](../docs/unattended.md#carry-forward); `--no-carry-forward` on the first `next` opts out): a later gate that asks nothing new takes the owner's words from the gate before it (`CARRIED:`, then `APPROVED:`); `CARRY: no ()` leaves it for the owner; `CARRY_CHECK:` means one reviewer from another model family reads the printed delta prompt, then `check --out --attempt --result --model ` (or `--unavailable ""`). ### On Capy @@ -51,9 +52,8 @@ line yourself; gstack never writes the plan. with `gstack-config set autoplan_checkpoint drive`) so a run survives machine replacement: a generation is published at rest, after each bound voice and after each phase transition; restore with `resume --out --from /`, which never redispatches a bound voice. -- Plans carry `## Before → after`, `## Why it matters`, `## What caused this work`, `## Big decisions`; - relay the printed `RELAY: gstack-owner-brief render --captain` output to your Captain (or the person), - then `gstack-approvals import --autoplan ` after `answer` (`capy/skill/gstack/captain.md`). +- Plans carry `## ELI5` (5-10 plain sentences), `## Before → after`, `## Why it matters`, `## What caused this work`, `## Big decisions`; + relay the printed `RELAY: gstack-owner-brief render --captain` output to your Captain (or the person), then `gstack-approvals import --autoplan ` after `answer` (`--stack ` for a stack; `capy/skill/gstack/captain.md`). ### Commands diff --git a/autoplan/DRIVER.md.tmpl b/autoplan/DRIVER.md.tmpl index b2ff2b001..9b3ed3765 100644 --- a/autoplan/DRIVER.md.tmpl +++ b/autoplan/DRIVER.md.tmpl @@ -23,7 +23,7 @@ line yourself; gstack never writes the plan. 1. `next` prints one `ATTEMPT: phase=

voice=native|outside prompt= result=` per voice. Dispatch the native prompt to a subagent on your model and the outside prompt to - a subagent on another model family (or `gstack-outside-voice run`). Each writes `result=`. + a subagent on another model family (or `gstack-outside-voice run`). Each writes `result=`. The first `next` also prints `REVIEW_ESTIMATE:` (most attempts and reservations the review can take). 2. Submit each voice exactly once (`BOUND:`). Both voices in closes the phase (`PHASE_CLOSED:`). 3. Repeat `next` until `status=gate_pending` (`GATE: gate_rev=`); render it with `gstack-gate render

/gate.json --all` and relay every page with the two cost lines printed under `GATE:`: `GATE_SPEND:` (spent, worst case, cap, headroom, attempts; host-subagent attempts are priced unknown and counted at their reservation, so quote their real figure from the host's cost view) and `GATE_REC_COST:` (the phases `rec` can reopen and the estimate for them, an upper bound; `gate_cost` in `--json`). You never approve the gate for the owner. Offer `rec` (every recommendation, plan changes included) as the default. @@ -35,6 +35,7 @@ line yourself; gstack never writes the plan. 5. `REOPENED: ` means loop `next` again (Eng last). `APPROVED:` means `export` (`DISPATCHES: est_input_tokens=`, relative). 6. Rounds: one by default; a second only for High or Critical findings; cap 2 (`--max-rounds`). A `revise` whose decisions all resolve below High prints `APPLIED: without re-review (below High)`. At the cap with High open, `ESCALATE: evidence sufficient, decision needed`: relay it, never ask for another round. +7. Carry-forward ([docs/unattended.md#carry-forward](../docs/unattended.md#carry-forward); `--no-carry-forward` on the first `next` opts out): a later gate that asks nothing new takes the owner's words from the gate before it (`CARRIED:`, then `APPROVED:`); `CARRY: no ()` leaves it for the owner; `CARRY_CHECK:` means one reviewer from another model family reads the printed delta prompt, then `check --out --attempt --result --model ` (or `--unavailable ""`). ### On Capy @@ -48,9 +49,8 @@ line yourself; gstack never writes the plan. with `gstack-config set autoplan_checkpoint drive`) so a run survives machine replacement: a generation is published at rest, after each bound voice and after each phase transition; restore with `resume --out --from /`, which never redispatches a bound voice. -- Plans carry `## Before → after`, `## Why it matters`, `## What caused this work`, `## Big decisions`; - relay the printed `RELAY: gstack-owner-brief render --captain` output to your Captain (or the person), - then `gstack-approvals import --autoplan ` after `answer` (`capy/skill/gstack/captain.md`). +- Plans carry `## ELI5` (5-10 plain sentences), `## Before → after`, `## Why it matters`, `## What caused this work`, `## Big decisions`; + relay the printed `RELAY: gstack-owner-brief render --captain` output to your Captain (or the person), then `gstack-approvals import --autoplan ` after `answer` (`--stack ` for a stack; `capy/skill/gstack/captain.md`). ### Commands diff --git a/benchmark/SKILL.md b/benchmark/SKILL.md index 56c76e733..ee09bbba4 100644 --- a/benchmark/SKILL.md +++ b/benchmark/SKILL.md @@ -412,7 +412,7 @@ TOP 10 SLOWEST RESOURCES RECOMMENDATIONS: - vendor.chunk.js: code-split — 320KB on initial load - analytics.js: load async/defer — blocks rendering for 250ms -- hero-image.webp: add width/height (CLS), lazy-load +- hero-image.webp: add width/height (CLS) ``` Third-party = any host but the page's origin. Each recommendation names a resource here or in a Phase 5 regression, the metric it moves and one remedy (split, defer, compress, lazy-load, cache). diff --git a/benchmark/SKILL.md.tmpl b/benchmark/SKILL.md.tmpl index 12a805eec..0a7448a29 100644 --- a/benchmark/SKILL.md.tmpl +++ b/benchmark/SKILL.md.tmpl @@ -201,7 +201,7 @@ TOP 10 SLOWEST RESOURCES RECOMMENDATIONS: - vendor.chunk.js: code-split — 320KB on initial load - analytics.js: load async/defer — blocks rendering for 250ms -- hero-image.webp: add width/height (CLS), lazy-load +- hero-image.webp: add width/height (CLS) ``` Third-party = any host but the page's origin. Each recommendation names a resource here or in a Phase 5 regression, the metric it moves and one remedy (split, defer, compress, lazy-load, cache). diff --git a/bin/gstack-approvals b/bin/gstack-approvals index da97642a9..3d3d5a9ef 100755 --- a/bin/gstack-approvals +++ b/bin/gstack-approvals @@ -5,7 +5,7 @@ * gstack-approvals add --ask --words --by --scope * [--pending ] [--outcome approved|rejected|pending|standing] * [--date YYYY-MM-DD] [--source ] [--branch ] [--json] - * gstack-approvals import --autoplan [--by ] [--branch ] [--json] + * gstack-approvals import --autoplan [--by ] [--branch | --stack ] [--json] * gstack-approvals render [--no-heading] [--branch ] * gstack-approvals list [--json] [--branch ] * gstack-approvals sync [--branch ] @@ -20,14 +20,15 @@ */ import * as path from 'node:path'; import { EXIT, exitTableHelp } from '../lib/headless-artifacts'; -import { appendRows, buildRow, importAutoplan, locate, readRecord, renderRecord, syncRecord, type RecordError, type StoreLocation } from '../lib/approval-record'; +import { appendRows, branchExists, buildRow, importAutoplan, locate, readRecord, renderRecord, syncRecord, type RecordError, type StoreLocation } from '../lib/approval-record'; import { resultLine } from '../lib/result-codes'; const HELP = `gstack-approvals — the per-thread approval record (capy/skill/gstack/captain.md) add --ask --words --by --scope [--pending ] [--outcome approved|rejected|pending|standing] [--date YYYY-MM-DD] [--source ] - import --autoplan [--by ] + import --autoplan [--by ] [--stack ] + --stack writes the same rows to every branch of a stack; each branch is checked first, and one unknown branch writes none render [--no-heading] the ## Approvals section for a PR body or report list [--json] sync re-mirror the record (GSTACK_APPROVALS_DIR, the Captain's drive approvals/, or the project-user Drive) @@ -40,7 +41,7 @@ Example: ${exitTableHelp()}`; -const VALUE_FLAGS = new Set(['--ask', '--words', '--by', '--scope', '--pending', '--outcome', '--date', '--source', '--branch', '--autoplan']); +const VALUE_FLAGS = new Set(['--ask', '--words', '--by', '--scope', '--pending', '--outcome', '--date', '--source', '--branch', '--autoplan', '--stack']); function parse(args: string[]): { flags: Record; bools: Set; error?: string } { const flags: Record = {}; @@ -64,11 +65,45 @@ function fail(cmd: string, e: RecordError): number { return EXIT.refused; } +/** `import --stack`: every branch checked first, then the same rows (ids are branch-independent) written to each branch's record. */ +function importStack(cmd: string, flags: Record, json: boolean): number { + if (cmd !== 'import' || !flags['--autoplan'] || flags['--branch'] !== undefined) { process.stderr.write(`gstack-approvals: --stack goes with import --autoplan , without --branch\n`); return EXIT.usage; } + const branches = [...new Set(flags['--stack']!.split(',').map(b => b.trim()).filter(Boolean))]; + if (!branches.length) { process.stderr.write(`gstack-approvals: --stack needs \n`); return EXIT.usage; } + const cwd = process.cwd(); + const missing = branches.filter(b => !branchExists(cwd, b)); + if (missing.length) return fail(cmd, { code: 'APPROVAL_RECORD_NO_BRANCH', message: `no local or origin branch ${missing.join(', ')}; nothing was written` }); + const runDir = path.resolve(flags['--autoplan']); + const results: Array<{ branch: string; added: string[]; skipped: number; file: string; mirror: string | null; error?: string }> = []; + let firstError: RecordError | undefined; + const plans: Array<{ branch: string; loc: StoreLocation; rows: ReturnType & unknown[] }> = []; + for (const branch of branches) { + const loc = locate({ cwd, env: process.env, branch }); + if ('code' in loc) return fail(cmd, loc); + const rows = importAutoplan(runDir, branch, flags['--by']); + if ('code' in rows) return fail(cmd, rows); + plans.push({ branch, loc, rows }); + } + for (const { branch, loc, rows } of plans) { + const res = appendRows(loc, rows); + if ('code' in res) { firstError ??= res; results.push({ branch, added: [], skipped: 0, file: loc.file, mirror: loc.mirror ?? null, error: res.message }); continue; } + if (res.mirrorError) firstError ??= res.mirrorError; + results.push({ branch, added: res.added.map(r => r.id), skipped: res.skipped, file: loc.file, mirror: loc.mirror ?? null, ...(res.mirrorError ? { error: res.mirrorError.message } : {}) }); + } + if (json) process.stdout.write(JSON.stringify({ branches: results }) + '\n'); + else { + for (const r of results) process.stdout.write(`APPROVAL_IMPORTED: branch=${r.branch} n=${r.added.length} skipped=${r.skipped} ${r.file}${r.mirror ? ` mirror=${r.mirror}` : ''}${r.error ? ` error=${r.error}` : ''}\n`); + process.stdout.write(`APPROVAL_IMPORTED_STACK: branches=${results.length} added=${results.reduce((n, r) => n + r.added.length, 0)}\n`); + } + return firstError ? fail(cmd, firstError) : EXIT.ok; +} + function main(argv: string[]): number { const [cmd, ...rest] = argv; if (!cmd || cmd === '--help' || cmd === '-h') { process.stdout.write(HELP + '\n'); return cmd ? EXIT.ok : EXIT.usage; } const { flags, bools, error } = parse(rest); if (error) { process.stderr.write(`gstack-approvals: ${error}\n${HELP}\n`); return EXIT.usage; } + if (flags['--stack'] !== undefined) return importStack(cmd, flags, bools.has('--json')); const loc = locate({ cwd: process.cwd(), env: process.env, branch: flags['--branch'] }); if ('code' in loc) return fail(cmd, loc); const json = bools.has('--json'); diff --git a/bin/gstack-autoplan b/bin/gstack-autoplan index 0b0a1c45b..c42062867 100755 --- a/bin/gstack-autoplan +++ b/bin/gstack-autoplan @@ -19,13 +19,14 @@ * gstack-autoplan release --out --attempt drop a reservation for an attempt that never ran * gstack-autoplan close --out --phase

--deferred "" --by > close a phase accepted-with-findings * gstack-autoplan budget --out

[--spend-cap ] [--max-rounds ] --by > the owner's journaled cap change + * gstack-autoplan check --out --attempt --result --model | --unavailable the delta check before a carry * gstack-autoplan checkpoints --from list checkpoint generations, newest first, with hash ok|bad * gstack-autoplan contract print the coordinator contract every lane prompt inherits (plan E2) * * Logic: lib/autoplan-run.ts (next/submit/resume), lib/autoplan-gate.ts (close, gate, answer), * lib/autoplan-export.ts, lib/autoplan-prompts.ts, lib/spend-ledger.ts. Codes: lib/result-codes.ts. * Workflow commands end with GSTACK_RESULT: skill=autoplan status= run=; the run is never approved here. - * Mutating verbs (next, submit, answer, recommend, revise, close, budget, export, run) pass admission first (lib/autoplan-admission.ts) + * Mutating verbs (next, submit, answer, recommend, revise, close, budget, check, export, run) pass admission first (lib/autoplan-admission.ts) * and bring an older run directory forward (lib/autoplan-migrate.ts) under the run lock. */ import * as fs from 'node:fs'; @@ -33,6 +34,7 @@ import * as path from 'node:path'; import { amendmentSteps, answerGate, closeDeferred, finishGate, recommendGate } from '../lib/autoplan-gate'; import { gateCost, gateCostPayload, renderGateCost, type GateCost } from '../lib/autoplan-gate-cost'; import { attemptEstimate, changeBudget, escalateLine, liftStop } from '../lib/autoplan-budget'; +import { DEFAULT_CARRY_CHECK_CAP_USD, carryLines, submitCarryCheck } from '../lib/autoplan-carry'; import { ANSWERED_BY_RE } from '../lib/gate-list'; import { checkpointLines, checkpointRun, restoreCheckpoint, type CheckpointMoment } from '../lib/autoplan-checkpoint'; import { admit, touchInstallLease } from '../lib/autoplan-admission'; @@ -60,6 +62,9 @@ DRIVER: ${driverFile()} --estimate-usd: reserved per new attempt; unattended Capy runs reserve a default for host attempts so --spend-cap binds --scaffold (first next): a plan missing one of its two sections is reviewed from /plan-source.md with the heading added --light loads each phase's checklist plus the sections its scope needs (the unattended default); interactive kinds load everything + --no-carry-forward (first next): every later gate revision goes to the owner, even one that asks nothing new + --carry-check-cap (first next): the most one delta check may reserve before a carry (default ${DEFAULT_CARRY_CHECK_CAP_USD.toFixed(2)}) + the first next prints REVIEW_ESTIMATE: the most the review can reserve at this scope and round cap prepare the current phase; one ATTEMPT: line per voice; ends awaiting_result submit --out --phase

--voice native|outside --result | --record [--attest ] --model [--attempt ] [--runner ] [--usage-usd ] [--reconcile ] [--json] @@ -84,6 +89,9 @@ DRIVER: ${driverFile()} resume --out

[--from ] [--json] --from restores a hash-verified checkpoint into an empty --out first (a collection or root restores its newest valid generation; GSTACK_AUTOPLAN_CHECKPOINT_DIR set: every command leaving the run at rest publishes a generation under // and prints CHECKPOINT: on stderr) + check --out --attempt --result --model [--same-family ""] | --unavailable "" + bind the one-reviewer delta check a CARRY_CHECK: line asked for: nothing at High or above carries the owner's + last answer (CARRIED:); otherwise, or when unavailable, the gate goes to the owner as before checkpoints --from list checkpoint generations, newest first: run, gate_rev, time, hash ok|bad, current close --out --phase

--deferred "" --by > close the phase accepted-with-findings: open voices skipped (dispatched attempts settle unknown at their @@ -180,7 +188,10 @@ function doNext(out: string, rest: string[], json: boolean): number { const ui = rest.includes('--ui') ? true : rest.includes('--no-ui') ? false : undefined; const maxRounds = num(rest, '--max-rounds'); if (maxRounds !== undefined && (!Number.isInteger(maxRounds) || maxRounds < 1)) throw new RunError('ARTIFACT_SCHEMA', '--max-rounds needs an integer >= 1', 1); + const carryCheckCapUsd = num(rest, '--carry-check-cap'); + if (carryCheckCapUsd !== undefined && !(carryCheckCapUsd >= 0)) throw new RunError('ARTIFACT_SCHEMA', '--carry-check-cap needs a number >= 0', 1); initRun({ plan, out, cwd, planHeading: flag(rest, '--plan-heading'), outsideEnabled: !rest.includes('--no-outside'), spendCap: num(rest, '--spend-cap') ?? null, maxRounds, + carryForward: !rest.includes('--no-carry-forward'), carryCheckCapUsd, deadlineMin: num(rest, '--deadline'), light: rest.includes('--light'), scaffold: rest.includes('--scaffold'), scope: { ui, developerTool: rest.includes('--developer-tool'), agentPrimary: rest.includes('--agent-primary'), dx: rest.includes('--no-dx') ? false : undefined, ...(rest.includes('--docs-only') ? { docsOnly: true } : {}) } }, initLines); } const redispatch = rest.flatMap((a, i) => (a === '--redispatch' && rest[i + 1] ? [rest[i + 1]!] : [])); @@ -257,7 +268,7 @@ function doClose(out: string, rest: string[], json: boolean): number { const r = closeDeferred(state, phase as Phase, { reason: reason.trim(), by, cause: 'owner' }); moment = 'transition'; const lines = [...r.lines, ...(stopped ? liftStop(state, `${phase} closed deferred by ${by}`) : [])]; - if (!currentPhase(state)) { finishGate(state); lines.push(...gateLines(state, out)); } + if (!currentPhase(state)) { finishGate(state); lines.push(...carryLines(state), ...(state.status === 'gate_pending' ? gateLines(state, out) : [])); } else { state.status = 'running'; lines.push(`NEXT: gstack-autoplan next --out ${out}`); } writeState(state); lines.push(resultLineFor(state.status, out)); @@ -265,6 +276,19 @@ function doClose(out: string, rest: string[], json: boolean): number { return EXIT.ok; } +/** `check`: the delta reviewer's verdict before a carry (lib/autoplan-carry.ts). */ +function doCheck(out: string, rest: string[], json: boolean): number { + const unavailable = flag(rest, '--unavailable'); + const result = flag(rest, '--result'); + if (unavailable === undefined && (!result || !flag(rest, '--model'))) return usage('check needs --attempt and --result --model , or --unavailable ""'); + const r = submitCarryCheck({ out, attempt: flag(rest, '--attempt'), result: result ? path.resolve(result) : undefined, model: flag(rest, '--model'), unavailable, sameFamily: flag(rest, '--same-family') }); + moment = 'transition'; + const status = r.state.status; + const lines = [...r.lines, ...(status === 'gate_pending' ? gateLines(r.state, out) : []), ...(status === 'amend_pending' || status === 'running' ? [nextLine(r.state, out)] : []), resultLineFor(status, out)]; + emit(json, lines, { run: r.state.run, status, gate_rev: r.state.gate_rev ?? null, carry: r.state.carry ?? null, out }); + return EXIT.ok; +} + function doBudget(out: string, rest: string[], json: boolean): number { const state = readState(out); const lines = changeBudget(state, { spendCap: num(rest, '--spend-cap'), maxRounds: num(rest, '--max-rounds'), by: flag(rest, '--by') }); @@ -338,6 +362,7 @@ async function main(argv: string[]): Promise { if (cmd === 'revise') return mutating(out, json, () => doRevise(out, rest, json)); if (cmd === 'close') return mutating(out, json, () => doClose(out, rest, json)); if (cmd === 'budget') return mutating(out, json, () => doBudget(out, rest, json)); + if (cmd === 'check') return mutating(out, json, () => doCheck(out, rest, json)); if (cmd === 'run') { const admission = admit(process.env); if (admission.lines.length) process.stdout.write(admission.lines.join('\n') + '\n'); return await doRun(out, rest, json); } if (cmd === 'status') { const state = readState(out); @@ -416,7 +441,7 @@ async function main(argv: string[]): Promise { if (e instanceof RunError) { process.stderr.write(resultLine(`gstack-autoplan ${cmd}`, e.code, e.detail) + '\n'); if (e.after.lines?.length) process.stdout.write(e.after.lines.join('\n') + '\n'); - if (['next', 'submit', 'answer', 'resume', 'run', 'revise', 'recommend', 'close', 'budget'].includes(cmd)) process.stdout.write(resultLineFor(e.after.status ?? 'refused', out) + '\n'); + if (['next', 'submit', 'answer', 'resume', 'run', 'revise', 'recommend', 'close', 'budget', 'check'].includes(cmd)) process.stdout.write(resultLineFor(e.after.status ?? 'refused', out) + '\n'); return e.exit === 3 ? EXIT.refused : EXIT.fail; } process.stderr.write(`gstack-autoplan ${cmd}: ${e?.message ?? e}\n`); diff --git a/bin/gstack-capy-install b/bin/gstack-capy-install index 62975197f..93b51b75c 100755 --- a/bin/gstack-capy-install +++ b/bin/gstack-capy-install @@ -407,15 +407,32 @@ verdict_kept() { [ "$PROFILE" -eq 1 ] && [ -f "$VERDICT" ] && [ "$(gstack_install_verdict_field "$VERDICT" ok)" = true ] \ && [ "$(gstack_install_verdict_field "$VERDICT" head)" = "$HEAD_SHA" ] && ! gstack_doctor_install_profile "$(gstack_install_verdict_field "$VERDICT" for)" } +# An ok run keeps what an earlier ok install certified for this checkout, project, HEAD and Bun, +# so one machine serving /ship and its docs step stays admitted for both (#3561): required is +# the union, pins count as planning-only only when both runs skipped them, and for= lists every +# workflow (comma-separated). A failing run, another HEAD or another Bun replaces the verdict. record_verdict() { # TRAILER OK — --check keeps the recorded resolution (drift is reported, never re-recorded) + local v_for="${FOR:-}" v_req v_plan e_for id if verdict_kept; then say "kept the install verdict for=$(gstack_install_verdict_field "$VERDICT" for) at $VERDICT (it covers more than $FOR; the trailer below is this check's)" return 0 fi if [ "$CHECK_ONLY" -eq 1 ] && [ -n "$REC_BUN" ]; then set -- "$1" "$2" "$REC_BUN" "$REC_VER" "$REC_RULE" "$REC_BUN_INSTALL" else set -- "$1" "$2" "$RES_BIN" "$RES_VER" "$RES_RULE" "${BUN_INSTALL:-}"; fi - gstack_install_verdict_write "$VERDICT" "$ROOT_REAL" "$HEAD_SHA" "${FOR:-}" "$(printf '%s\n' "${OUT:-}" | sed -n 's/^required: //p' | head -1)" \ - "$(printf '%s\n' "${OUT:-}" | grep -q '^SKIP pins (planning-only' && echo 1 || echo 0)" "$2" "$1" "${MIN_REVISION:-}" "$LAUNCH_DIR" \ + v_req=$(printf '%s\n' "${OUT:-}" | sed -n 's/^required: //p' | head -1) + v_plan=$(printf '%s\n' "${OUT:-}" | grep -q '^SKIP pins (planning-only' && echo 1 || echo 0) + if [ "$2" = 1 ] && [ "$PROFILE" -eq 0 ] && [ -f "$VERDICT" ] && [ "$(gstack_install_verdict_field "$VERDICT" ok)" = true ] \ + && [ "$(gstack_install_verdict_field "$VERDICT" head)" = "$HEAD_SHA" ] && [ "$(gstack_install_verdict_field "$VERDICT" checkout)" = "$ROOT_REAL" ] \ + && [ "$(gstack_install_verdict_field "$VERDICT" bun_path)" = "$3" ] && e_for=$(gstack_install_verdict_field "$VERDICT" for) \ + && ! gstack_doctor_install_profile "$e_for"; then + for id in $(gstack_install_verdict_field "$VERDICT" required); do + case " $v_req " in *" $id "*) ;; *) v_req="$v_req $id" ;; esac + done + [ "$(gstack_install_verdict_field "$VERDICT" pins_planning_only)" = true ] || v_plan=0 + case ",$e_for," in *",$v_for,"*) v_for="$e_for" ;; *) v_for="${e_for:+$e_for${v_for:+,}}$v_for" ;; esac + [ "$v_for" = "$e_for" ] || [ -z "$e_for" ] || say "the install verdict at $VERDICT keeps for=$e_for and adds ${FOR:-$REQUIRE} (for=$v_for)" + fi + gstack_install_verdict_write "$VERDICT" "$ROOT_REAL" "$HEAD_SHA" "$v_for" "$v_req" "$v_plan" "$2" "$1" "${MIN_REVISION:-}" "$LAUNCH_DIR" \ "$PROJECT_REAL" "$PIN_EXACT" "$3" "$4" "$5" "$6" "$NODE_BIN" "$NODE_VER" "$NODE_RULE" \ || say "could not write the install verdict $VERDICT" } diff --git a/bin/gstack-capy-session b/bin/gstack-capy-session index 4296bdec8..3df25b12e 100755 --- a/bin/gstack-capy-session +++ b/bin/gstack-capy-session @@ -23,7 +23,13 @@ # applies: dirty, diverged, pinned, Bun hold, a live workflow lease) and on # success re-execs the NEW checkout's copy of this script with the same # arguments (GSTACK_CAPY_SELF_UPGRADED=1 stops a second attempt) before the -# installer runs. Lines: `SELF_UPGRADE: done -> ` | `skipped ()` +# installer runs. A live lease under 120 minutes old (the lease prune window) +# held by this session's own process chain also skips it (#3571): +# gstack-upgrade never counts the caller's own session, but an install run from +# inside a workflow (/ship's docs step) must not change gstack under it. The age +# bound matters on Capy, where the leased harness pid is the machine's +# long-lived capy-server and a live lease alone would never end the deferral; +# each gstack-skill-start renews it (UPGRADE_BUSY; GSTACK_UPGRADE_FORCE=1 overrides). Lines: `SELF_UPGRADE: done -> ` | `skipped ()` # | `none (current)` | `disabled ()`. # --check never moves the checkout; behind origin it prints @@ -107,6 +113,18 @@ elif [ "${GSTACK_CAPY_SELF_UPGRADED:-}" != 1 ]; then elif ! behind; then echo "SELF_UPGRADE: none (current)" elif [ ! -x "$ROOT/bin/gstack-upgrade" ]; then echo "SELF_UPGRADE: skipped ($ROOT/bin/gstack-upgrade is missing)"; report_behind "$RERUN" export GSTACK_CAPY_BEHIND_BLOCKED="$ROOT/bin/gstack-upgrade is missing; fix: $RERUN (UPGRADE_REFUSED)" + elif [ "${GSTACK_UPGRADE_FORCE:-}" != 1 ] && [ -x "$ROOT/bin/gstack-lease" ] \ + && OWN=$("$ROOT/bin/gstack-lease" live --root "$ROOT" 2>/dev/null | awk '{ a = $2; sub(/m$/, "", a); if (a + 0 < 120) print }') \ + && [ -n "$OWN" ] \ + && ! "$ROOT/bin/gstack-lease" live --root "$ROOT" --exclude-ancestry-of $$ >/dev/null 2>&1; then + HOLDERS="" + while read -r _pid _age; do HOLDERS="$HOLDERS${HOLDERS:+, }pid $_pid ($_age)"; done </dev/null) UP_OUT=$("$ROOT/bin/gstack-upgrade" --ff-only-no-reinstall 2>&1); UP_RC=$? diff --git a/bin/gstack-decision-trail b/bin/gstack-decision-trail index 297c6aee4..750b00da8 100755 --- a/bin/gstack-decision-trail +++ b/bin/gstack-decision-trail @@ -17,7 +17,8 @@ * and a cell whose first byte a spreadsheet would run as a formula (=, +, -, @) * gets a leading apostrophe, so evidence taken from PR titles, filenames or * generated text cannot execute when a reviewer opens the file. License text: - * licenses/MIT-pstack.txt; NOTICE.md carries the entry. + * licenses/MIT-pstack.txt; NOTICE.md carries the entry. The append rules live in + * lib/decision-trail.ts, shared with the autoplan runner. * * The start-row rule is gstack's mechanisation of the same skill's prose: a run * (one agent conversation, with its later turns) that writes to a trail already @@ -26,11 +27,8 @@ * id, and an append with `--run ` refuses until that run's start row is the * newest start row in the file (DECISION_TRAIL_START_REQUIRED, exit 3). */ -import * as fs from "node:fs"; -import * as path from "node:path"; +import { appendTrailRow as appendRow, readTrailRows as readRows, type TrailRow as Row } from "../lib/decision-trail"; -const COLUMNS = ["ts", "phase", "decision", "why", "evidence", "result"] as const; -const HEADER = COLUMNS.join("\t") + "\n"; const USAGE = `Usage: gstack-decision-trail [--run ] gstack-decision-trail start @@ -56,58 +54,6 @@ letters, digits and . _ : @ / - (a Capy jam_ id, a session id, a PR number). when the trail has rows and the newest start row is another run's. `; -type Row = { line: number; cells: string[] }; - -function clean(cell: string): string { - const flat = cell.replace(/[\t\n\r]/g, " "); - return /^[=+\-@]/.test(flat) ? `'${flat}` : flat; -} - -function readRows(file: string): Row[] { - if (!fs.existsSync(file)) return []; - const lines = fs.readFileSync(file, "utf8").split("\n"); - const rows: Row[] = []; - lines.forEach((raw, i) => { - let text = raw.endsWith("\r") ? raw.slice(0, -1) : raw; - if (i === 0 && text.startsWith("\uFEFF")) text = text.slice(1); - // A repeated header (the append-on-flaky-mount case) is never a row. - if (text === "" || text === HEADER.trimEnd()) return; - rows.push({ line: i + 1, cells: text.split("\t") }); - }); - return rows; -} - -function appendRow(file: string, cells: readonly string[]): number { - const dir = path.dirname(file); - if (dir && dir !== "." && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); - // Append the header too, never truncate: on a flaky mount the worst case is - // one stray header line, not lost rows. - // A file with no header line anywhere (empty, blank, or rows written by hand) - // gets one appended once; readRows skips a header line wherever it sits. - const size = fs.existsSync(file) ? fs.statSync(file).size : 0; - if (size > 0 && !endsWithNewline(file, size)) fs.appendFileSync(file, "\n"); - if (size === 0 || !hasHeader(file)) fs.appendFileSync(file, HEADER); - const ts = new Date().toISOString().replace(/\.\d{3}Z$/, "Z"); - fs.appendFileSync(file, [ts, ...cells.map(clean)].join("\t") + "\n"); - return readRows(file).length; -} - -function hasHeader(file: string): boolean { - return fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "").split("\n") - .some(line => line.replace(/\r$/, "") === HEADER.trimEnd()); -} - -function endsWithNewline(file: string, size: number): boolean { - const fd = fs.openSync(file, "r"); - try { - const last = Buffer.alloc(1); - fs.readSync(fd, last, 0, 1, size - 1); - return last[0] === 0x0a; - } finally { - fs.closeSync(fd); - } -} - const RUN_ID = /^[A-Za-z0-9._:@/-]+$/; function checkRunId(runId: string): void { if (!RUN_ID.test(runId)) fail(`run id must match ${RUN_ID} (letters, digits, . _ : @ / -), got ${JSON.stringify(runId)}`, 2); diff --git a/bin/gstack-diff-scope b/bin/gstack-diff-scope index 2fa10b41d..3ec81cf09 100755 --- a/bin/gstack-diff-scope +++ b/bin/gstack-diff-scope @@ -2,6 +2,9 @@ # gstack-diff-scope — categorize what changed in the diff against a base branch # Usage: source <(gstack-diff-scope main) → sets SCOPE_FRONTEND=true SCOPE_BACKEND=false ... # Or: gstack-diff-scope main → prints SCOPE_*=... lines +# Or: gstack-diff-scope --head → the committed range ... only +# (no working tree, no untracked files): what a receipt writer and the +# merge queue compute for one commit, from any checkout (GSTA-147). # # Output contract (#2526 — all-false must be distinguishable from "we could # not look" and from "nothing matched"): @@ -31,6 +34,8 @@ _default_base() { echo "main" } BASE="${1:-$(_default_base)}" +HEAD_REF="" +if [ "${2:-}" = "--head" ]; then HEAD_REF="${3:-}"; fi FRONTEND=false BACKEND=false @@ -79,6 +84,21 @@ _collect() { [ -n "$f" ] && FILES_LIST+=("$f") done } +if [ -n "$HEAD_REF" ] || [ "${2:-}" = "--head" ]; then + if ! git rev-parse --verify -q "${HEAD_REF}^{commit}" >/dev/null 2>&1; then + _print_flags + echo "SCOPE_ERROR=no_head" + echo "# --head '${HEAD_REF}' is not a commit in this repository" + exit 2 + fi + if ! git merge-base "${BASE}" "${HEAD_REF}" >/dev/null 2>&1; then + _print_flags + echo "SCOPE_ERROR=no_merge_base" + echo "# '${BASE}' and '${HEAD_REF}' share no merge base" + exit 2 + fi + _collect < <(git diff -z "${BASE}...${HEAD_REF}" --name-only 2>/dev/null) +else # Committed diff vs base (merge-base form; two-dot fallback when no merge base). _collect < <(git diff -z "${BASE}...HEAD" --name-only 2>/dev/null || git diff -z "${BASE}" --name-only 2>/dev/null || true) # Working-tree changes (staged + unstaged). `git diff HEAD` fails on a repo @@ -87,6 +107,7 @@ _collect < <(git diff -z HEAD --name-only 2>/dev/null || true) # Untracked files: a brand-new component/migration/test is exactly what a # reviewer should see, and /ship commits it in Step 15 regardless. _collect < <(git ls-files -z --others --exclude-standard 2>/dev/null || true) +fi if [ "${#FILES_LIST[@]}" -eq 0 ]; then _print_flags diff --git a/bin/gstack-doctor-components.sh b/bin/gstack-doctor-components.sh index 221e5c993..f3c867766 100644 --- a/bin/gstack-doctor-components.sh +++ b/bin/gstack-doctor-components.sh @@ -286,6 +286,8 @@ gstack_result_anchor() { QUEUE_TRAIN_FROZEN) printf '%s' 'queue-train-frozen' ;; QUEUE_RECEIPT_MISSING) printf '%s' 'queue-receipt-missing' ;; QUEUE_RECEIPT_STALE) printf '%s' 'queue-receipt-stale' ;; + QUEUE_RECEIPT_DEPTH_RAISED) printf '%s' 'queue-receipt-depth-raised' ;; + QUEUE_RECEIPT_EXCEPTION_INVALID) printf '%s' 'queue-receipt-exception-invalid' ;; QUEUE_SCREEN_STALE_REF) printf '%s' 'queue-screen-stale-ref' ;; QUEUE_SCREEN_NOT_RUN) printf '%s' 'queue-screen-not-run' ;; QUEUE_TRAIN_STACK_RED) printf '%s' 'queue-train-stack-red' ;; @@ -306,6 +308,8 @@ gstack_result_anchor() { REVIEW_SCOPE_RANGE) printf '%s' 'review-scope-range' ;; RECEIPT_CARRY_REFUSED) printf '%s' 'receipt-carry-refused' ;; PROSE_LINT_FOUND) printf '%s' 'prose-lint-found' ;; + REVIEW_LOOP_EXCEPTION_INVALID) printf '%s' 'review-loop-exception-invalid' ;; + RECEIPT_CARRY_TREE_MISMATCH) printf '%s' 'receipt-carry-tree-mismatch' ;; RECEIPT_CARRY_PRODUCT_CHANGED) printf '%s' 'receipt-carry-product-changed' ;; DOCS_AUDIT_BLOCKED) printf '%s' 'docs-audit-blocked' ;; RECEIPT_PROSE_MISMATCH) printf '%s' 'receipt-prose-mismatch' ;; @@ -328,6 +332,13 @@ gstack_result_anchor() { PROJECT_FLOOR_UNMET) printf '%s' 'project-floor-unmet' ;; PROJECT_NODE_PIN_UNMET) printf '%s' 'project-node-pin-unmet' ;; UPGRADE_SKIPPED) printf '%s' 'upgrade-skipped' ;; + BUDGET_CAP_REACHED) printf '%s' 'budget-cap-reached' ;; + BUDGET_READING_MISSING) printf '%s' 'budget-reading-missing' ;; + BUDGET_READING_REJECTED) printf '%s' 'budget-reading-rejected' ;; + BUDGET_METER_UNAVAILABLE) printf '%s' 'budget-meter-unavailable' ;; + BUDGET_LEDGER_INVALID) printf '%s' 'budget-ledger-invalid' ;; + BUDGET_CHECK_SKIPPED) printf '%s' 'budget-check-skipped' ;; + HANDOFF_PIN_MOVED) printf '%s' 'handoff-pin-moved' ;; *) return 1 ;; esac } diff --git a/bin/gstack-harness b/bin/gstack-harness index 5bb446904..5bd39f320 100755 --- a/bin/gstack-harness +++ b/bin/gstack-harness @@ -8,7 +8,10 @@ * * Usage: * gstack-harness detect [--json] - * gstack-harness register [--skills router|all] [--skills-dir

] [--context ] [--print] [--yes] [--no-registry] + * gstack-harness register [--skills router|hybrid|all] [--skills-dir ] [--context ] [--print] [--yes] [--no-registry] + * --context writes gstack's marked routing block into that file only + * (opt-in: setup, upgrades and refresh never add one, and a block you + * delete stays deleted); it prints the file and its scope before writing * gstack-harness unregister [--remote] * gstack-harness status [--json] [--no-check] * gstack-harness refresh @@ -20,7 +23,7 @@ import * as os from 'node:os'; import * as path from 'node:path'; import { resolveStateRoot } from '../lib/state-root'; import { - HarnessError, TARGETS, detect, getTarget, harnessSees, listLedgers, printPayload, refresh, register, sourceSkills, status, unregister, + HarnessError, TARGETS, contextScope, detect, getTarget, harnessSees, listLedgers, printPayload, refresh, register, sourceSkills, status, unregister, type RegisterResult, type SkillsMode, type TargetName, } from '../lib/harness-register'; import { registerQm, removeQmPack } from '../lib/harness-qm'; @@ -38,9 +41,10 @@ const self = path.join(checkout, 'bin', 'gstack-harness'); function receiptLines(r: RegisterResult): string[] { const t = TARGETS[r.target]; + const how = { router: 'reachable through one router skill', hybrid: 'registered, the task skills listed directly and the rest through one router skill', all: 'registered' }[r.mode]; return [ - 'gstack-harness: ' + t.displayName + ': ' + r.skills + ' gstack skills ' + (r.mode === 'router' ? 'reachable through one router skill' : 'registered') + ' at ' + r.dest + ' (' + r.status + (r.written ? ', ' + r.written + ' files written' : '') + ')', - ...(r.router ? [' router: ' + r.router + (r.mode === 'router' ? ' (register with --skills all to list every skill natively)' : '')] : []), + 'gstack-harness: ' + t.displayName + ': ' + r.skills + ' gstack skills ' + how + ' at ' + r.dest + ' (' + r.status + (r.written ? ', ' + r.written + ' files written' : '') + ')', + ...(r.router ? [' router: ' + r.router + ' (register with --skills all to list every skill natively)'] : []), ...r.kept.map(k => ' kept your edit: ' + k), ' ledger: ' + r.ledger, ' remove: ' + self + ' unregister ' + r.id, @@ -83,6 +87,7 @@ async function main(): Promise { console.log('gstack-harness: ' + t.displayName + ': unverified (' + (seen.checked ? seen.checked + ' did not list gstack' : t.name + ' is not on PATH') + '). Install gstack for Claude Code (./setup), or paste the block from: ' + self + ' register generic --print'); return 3; } + if (context) (json ? console.error : console.log)('gstack-harness: context block: ' + path.resolve(context) + ' (' + contextScope(t, context, env, home) + ' scope)'); const r = register({ ...base, target: t, mode, skillsDir, context, registry: !noRegistry }); if (json) console.log(JSON.stringify({ ...r, receipt: receiptLines(r).map(l => l.trim()).join('; ') })); else receipt(r); diff --git a/bin/gstack-harness-ledger.sh b/bin/gstack-harness-ledger.sh index 85a6d6c47..210e85326 100644 --- a/bin/gstack-harness-ledger.sh +++ b/bin/gstack-harness-ledger.sh @@ -13,8 +13,11 @@ # uninstall of the state root and the checkout. Only paths below the recorded # destination, reached through no symlink, are touched. A context block is cut # only when its file holds exactly one whole-line begin/end marker pair whose -# lines hash to the ledger's block hash; otherwise the file is left as it is -# (the file is removed only when nothing else is left in it). Folders gstack +# lines hash to the ledger's block hash; otherwise the file is left as it is. +# Its blockpad row says what gstack added before the block, so the cut restores +# the file byte for byte: the blank line (and newline) it appended are removed +# too, and a file gstack created is removed when nothing else is left in it +# (ledgers without the row: when only whitespace is left). Folders gstack # created are removed only when empty. A QM pack is never touched here: detaching it from # the org is `gstack-harness unregister qm --remote`. @@ -33,7 +36,7 @@ _gstack_harness_owned() { } _gstack_harness_cut_block() { - local file="$1" want="$2" span s e tmp + local file="$1" want="$2" pad="${3:-}" span s e tmp local begin='' end='' { [ -f "$file" ] && [ ! -L "$file" ]; } || return 0 span="$(awk -v B="$begin" -v E="$end" '$0 == B { nb++; s = NR } $0 == E { ne++; e = NR } END { if (nb == 1 && ne == 1 && e > s) print s, e; else if (nb || ne) print "bad" }' "$file")" @@ -44,13 +47,18 @@ _gstack_harness_cut_block() { return 0 fi tmp="$file.gstack-cut.$$" - awk -v s="$s" -v e="$e" 'NR < s || NR > e' "$file" > "$tmp" || { rm -f "$tmp"; return 1; } - if [ -z "$(tr -d '[:space:]' < "$tmp")" ]; then rm -f "$file"; else cat "$tmp" > "$file"; fi + awk -v s="$s" -v e="$e" -v pad="$pad" '{ line[NR] = $0 } + END { + from = s; if ((pad == "1" || pad == "2") && s > 1 && line[s - 1] == "") from = s - 1 + n = 0; for (i = 1; i <= NR; i++) if (i < from || i > e) out[++n] = line[i] + for (i = 1; i <= n; i++) { printf "%s", out[i]; if (i < n || !(pad == "2" && e == NR)) printf "\n" } + }' "$file" > "$tmp" || { rm -f "$tmp"; return 1; } + if { [ "$pad" = new ] && [ ! -s "$tmp" ]; } || { [ -z "$pad" ] && [ -z "$(tr -d '[:space:]' < "$tmp")" ]; }; then rm -f "$file"; else cat "$tmp" > "$file"; fi rm -f "$tmp" } gstack_harness_unregister_ledger() { - local ledger="$1" stamp kind a b target="" dest="" pack="" + local ledger="$1" stamp kind a b target="" dest="" pack="" pad="" padpath="" : "${GSTACK_STATE_ROOT:?gstack-harness-ledger: GSTACK_STATE_ROOT is not set}" [ -f "$ledger" ] || return 0 stamp="$(date -u +%Y-%m-%dT%H-%M-%SZ)" @@ -61,7 +69,8 @@ gstack_harness_unregister_ledger() { { [ -f "$b" ] && _gstack_harness_owned "$b" "$dest"; } || continue if [ "$(_gstack_harness_sha "$b")" = "$a" ]; then rm -f "$b" else mv "$b" "$b.edited-$stamp" && echo " kept your edit: $b.edited-$stamp"; fi ;; - block) _gstack_harness_cut_block "$b" "$a" ;; + blockpad) pad="$a"; padpath="$b" ;; + block) if [ "$padpath" = "$b" ]; then _gstack_harness_cut_block "$b" "$a" "$pad"; else _gstack_harness_cut_block "$b" "$a"; fi ;; esac done < "$ledger" while IFS=$'\t' read -r kind a b; do diff --git a/bin/gstack-install-verdict.sh b/bin/gstack-install-verdict.sh index 5f553376d..73ad365cf 100644 --- a/bin/gstack-install-verdict.sh +++ b/bin/gstack-install-verdict.sh @@ -8,7 +8,9 @@ # one checkout and one project (the caller's git toplevel, or none): # /install-verdicts//.json # written atomically by bin/gstack-capy-install (install and --check) with -# schema_version 2, checkout, head, for, required[], pins_planning_only, ok, +# schema_version 2, checkout, head, for (comma-separated: an ok run at the same +# HEAD and Bun keeps the workflows an earlier ok install certified, #3561), +# required[] (their union), pins_planning_only, ok, # trailer, min_revision, launch_path, time, project, pin (the exact Bun pin), # bun_path (realpath), bun_version, bun_rule (gstack_bun_resolve), bun_install, # node_path (realpath), node_version, node_rule (gstack_node_resolve; empty diff --git a/bin/gstack-modules b/bin/gstack-modules new file mode 100755 index 000000000..fa3f98d8d --- /dev/null +++ b/bin/gstack-modules @@ -0,0 +1,8 @@ +#!/usr/bin/env -S bun --no-env-file --config=/dev/null +import { modulesMain } from '../scripts/modules-cli.ts'; + +void modulesMain(process.argv.slice(2)).then(result => { + if (result.stdout) process.stdout.write(result.stdout); + if (result.stderr) process.stderr.write(result.stderr); + process.exitCode = result.code; +}); diff --git a/bin/gstack-pregate b/bin/gstack-pregate index 8613150ed..446e4be7a 100755 --- a/bin/gstack-pregate +++ b/bin/gstack-pregate @@ -40,7 +40,7 @@ import { DEFAULT_STALL_TIMEOUT_S } from '../lib/pregate/context'; import { cancelActive } from '../lib/pregate/supervise'; import { defaultGh, evaluateRegate, renderRegate } from '../lib/pregate/regate'; import { GATE_AHEAD_REL } from '../lib/restamp'; -import { evaluateSealed, publishedCommits, rangeCommits, renderSealed } from '../lib/sealed-guard'; +import { evaluateSealed, publishedCommits, rangeCommits, renderSealed, sealedErrorReport } from '../lib/sealed-guard'; import { isUnavailable, loadPolicyFromBase, policyUnavailableLine, resolveBaseBranch } from '../lib/ship-policy'; import { fromGateAhead } from '../lib/tree-receipt'; @@ -244,13 +244,13 @@ function cmdSealed(root: string, rest: string[], json: boolean): number { const baseRef = gitOut(root, ['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/${base}^{commit}`]) ? `refs/remotes/${remote}/${base}` : null; const remoteUrl = gitOut(root, ['remote', 'get-url', remote]); const report = 'error' in listed - ? { status: 'error' as const, error: listed.error, policyLabels: [], commits: 0, findings: [], waived: [], visibility: 'unknown' as const, visibilitySource: '', target: remoteUrl ?? remote } + ? sealedErrorReport(listed.error, remoteUrl ?? remote) : evaluateSealed({ repoRoot: root, targets: [{ commits: listed.commits, pushedSha }], baseRef, baseLabel: `${remote}/${base}`, remoteUrl, target: remoteUrl ?? remote }); const blocks = report.status === 'refused' || report.status === 'error'; if (json) { process.stdout.write(JSON.stringify({ ...report, ok: !blocks }) + '\n'); return blocks ? EXIT.fail : EXIT.ok; } process.stderr.write(renderSealed(report, 'gstack-pregate sealed')); const policy = report.policyLabels.length ? report.policyLabels.join(' + ') : `no sealed key on ${baseRef ?? `${remote}/${base}`} or ${end}`; - process.stdout.write(`SEALED: ${report.status} findings=${report.findings.length} commits=${report.commits} visibility=${report.visibility}${report.visibility === 'unknown' ? ' (counted public)' : ''} waived=${report.waived.length} policy=${policy}\n`); + process.stdout.write(`SEALED: ${report.status} findings=${report.findings.length} commits=${report.commits} visibility=${report.visibility}${report.visibility === 'unknown' ? ' (counted public)' : ''} waived=${report.waived.length} exempt=${report.exempt.length} policy=${policy}\n`); return blocks ? EXIT.fail : EXIT.ok; } diff --git a/bin/gstack-redact-prepush b/bin/gstack-redact-prepush index 252dc4389..80ebddeed 100755 --- a/bin/gstack-redact-prepush +++ b/bin/gstack-redact-prepush @@ -43,7 +43,7 @@ import * as path from "path"; import { normalizeWithMap, scan, type Finding, type ScanOptions } from "../lib/redact-engine"; import { mkdirpSync } from "../lib/fs-utils"; import { resolveStateRoot } from "../lib/state-root"; -import { evaluateSealed, publishedCommits, renderSealed, type SealedReport } from "../lib/sealed-guard"; +import { evaluateSealed, publishedCommits, renderSealed, sealedErrorReport, type SealedReport } from "../lib/sealed-guard"; const ZERO = /^0+$/; let emptyTree: string | undefined; @@ -608,7 +608,7 @@ function sealedForPush(refs: Array<{ localSha: string; remoteSha: string }>): Se const targets: Array<{ commits: string[]; pushedSha: string }> = []; for (const ref of refs) { const published = publishedCommits(".", { localSha: ref.localSha, remoteSha: ref.remoteSha, remoteName }); - if ("error" in published) return { status: "error", error: published.error, policyLabels: [], commits: 0, findings: [], waived: [], visibility: "unknown", visibilitySource: "", target: remoteUrl ?? "the push target" }; + if ("error" in published) return sealedErrorReport(published.error, remoteUrl ?? "the push target"); targets.push({ commits: published.commits, pushedSha: ref.localSha }); } return evaluateSealed({ repoRoot: ".", targets, baseRef: defaultRemoteBranch(), remoteUrl, target: remoteUrl ?? remoteName ?? "the push target" }); diff --git a/bin/gstack-review-log b/bin/gstack-review-log index b60832497..0a7037120 100755 --- a/bin/gstack-review-log +++ b/bin/gstack-review-log @@ -3,6 +3,10 @@ # Usage: gstack-review-log '{"skill":"...","timestamp":"...","status":"..."}' # # Before reading a diff: gstack-review-log --start review +# Under a /ship token cap (docs/ship-budget.md): --start SKILL --reservation ID +# with the RESERVATION id gstack-ship-budget check printed for this dispatch +# batch; refuses (exit 1, BUDGET_CHECK_SKIPPED) without an unspent one, and +# --finish settles it. Without a cap no marker exists and nothing changes. # Fix-range repeat (#3339): gstack-review-log --start review --fix-range # prints the token, then FIX_BASE=; refuses (exit 1) unless the latest # pass completed with fixes on unchanged content and its commit is an @@ -32,15 +36,18 @@ export GSTACK_REVIEW_DIR="$GSTACK_HOME/projects/$SLUG" export GSTACK_REVIEW_REPO="$(git rev-parse --show-toplevel 2>/dev/null || true)" export GSTACK_REVIEW_BRANCH="$(git symbolic-ref --short HEAD 2>/dev/null || git rev-parse HEAD 2>/dev/null || true)" export GSTACK_REVIEW_LIB="$SCRIPT_DIR/../lib/review-evidence.ts" +export GSTACK_SHIP_BUDGET_LIB="$SCRIPT_DIR/../lib/ship-budget.ts" case "$(uname -s)" in MINGW*|MSYS*|CYGWIN*) if command -v cygpath >/dev/null 2>&1; then GSTACK_REVIEW_LIB="$(cygpath -m "$GSTACK_REVIEW_LIB")" + GSTACK_SHIP_BUDGET_LIB="$(cygpath -m "$GSTACK_SHIP_BUDGET_LIB")" GSTACK_REVIEW_DIR="$(cygpath -m "$GSTACK_REVIEW_DIR")" fi ;; esac export GSTACK_REVIEW_LOG="$GSTACK_REVIEW_DIR/$BRANCH-reviews.jsonl" +export GSTACK_SHIP_BUDGET_MARKER="$GSTACK_REVIEW_DIR/$BRANCH-ship-budget.json" # Compute binding fields (best-effort; empty outside a git repo). COMMIT_FULL=$(git rev-parse HEAD 2>/dev/null || true) @@ -77,10 +84,28 @@ fi SESSION_KIND=$("$SCRIPT_DIR/gstack-session-kind" 2>/dev/null || echo interactive) export GSTACK_STAMP_COMMIT_FULL="$COMMIT_FULL" GSTACK_STAMP_TREE="$TREE" GSTACK_STAMP_WTREE="$WTREE" GSTACK_STAMP_DIRTY="$DIRTY" GSTACK_STAMP_SESSION_KIND="$SESSION_KIND" if [ "$INPUT" = --start ]; then - case "${3:-}" in ''|--fix-range) ;; *) echo 'Usage: gstack-review-log --start SKILL [--fix-range]' >&2; exit 2 ;; esac - GSTACK_REVIEW_SKILL="${2:-}" GSTACK_REVIEW_FIX_RANGE="${3:-}" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e ' + START_SKILL="${2:-}" START_FIX="" START_RESERVATION="" + if [ "$#" -ge 2 ]; then shift 2; else shift "$#"; fi + while [ "$#" -gt 0 ]; do + case "$1" in + --fix-range) START_FIX=--fix-range; shift ;; + --reservation) [ "$#" -ge 2 ] || { echo 'Usage: gstack-review-log --start SKILL [--fix-range] [--reservation ID]' >&2; exit 2; }; START_RESERVATION="$2"; shift 2 ;; + *) echo 'Usage: gstack-review-log --start SKILL [--fix-range] [--reservation ID]' >&2; exit 2 ;; + esac + done + if [ ! -f "$GSTACK_SHIP_BUDGET_MARKER" ]; then + GSTACK_REVIEW_SKILL="$START_SKILL" GSTACK_REVIEW_FIX_RANGE="$START_FIX" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e ' + const { captureReviewStart } = await import(process.env.GSTACK_REVIEW_LIB); + try { console.log(captureReviewStart(process.env.GSTACK_REVIEW_SKILL, process.env, process.env.GSTACK_REVIEW_FIX_RANGE === "--fix-range")); } + catch (e) { console.error(e.message); process.exit(1); } + ' + exit $? + fi + GSTACK_REVIEW_SKILL="$START_SKILL" GSTACK_REVIEW_FIX_RANGE="$START_FIX" GSTACK_REVIEW_RESERVATION="$START_RESERVATION" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e ' const { captureReviewStart } = await import(process.env.GSTACK_REVIEW_LIB); - try { console.log(captureReviewStart(process.env.GSTACK_REVIEW_SKILL, process.env, process.env.GSTACK_REVIEW_FIX_RANGE === "--fix-range")); } + const { admitReviewStart } = await import(process.env.GSTACK_SHIP_BUDGET_LIB); + const capture = () => captureReviewStart(process.env.GSTACK_REVIEW_SKILL, process.env, process.env.GSTACK_REVIEW_FIX_RANGE === "--fix-range"); + try { console.log(admitReviewStart(process.env.GSTACK_SHIP_BUDGET_MARKER, process.env.GSTACK_REVIEW_RESERVATION || undefined, capture)); } catch (e) { console.error(e.message); process.exit(1); } ' exit $? @@ -93,7 +118,7 @@ if [ "$INPUT" = --check-shared-libs ] && [ "$#" -eq 2 ]; then exit $? fi usage() { - echo 'Usage: gstack-review-log JSON [--finish TOKEN] [--findings FILE] | --start SKILL [--fix-range] | --check-shared-libs TOKEN < finding.json' >&2 + echo 'Usage: gstack-review-log JSON [--finish TOKEN] [--findings FILE] | --start SKILL [--fix-range] [--reservation ID] | --check-shared-libs TOKEN < finding.json' >&2 echo 'Exit codes: 0 written · 1 rejected · 2 usage' >&2 exit 2 } @@ -126,6 +151,16 @@ try { echo "$STAMPED" >> "$GSTACK_HOME/projects/$SLUG/$BRANCH-reviews.jsonl" +# A finished dispatch settles the budget reservation its start consumed (its +# completion receipt); stdout stays unchanged and a failure never undoes the row. +if [ -n "$TOKEN" ] && [ -f "$GSTACK_SHIP_BUDGET_MARKER" ]; then + GSTACK_REVIEW_TOKEN="$TOKEN" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e ' + const { settleReviewFinish } = await import(process.env.GSTACK_SHIP_BUDGET_LIB); + try { const id = settleReviewFinish(process.env.GSTACK_SHIP_BUDGET_MARKER, process.env.GSTACK_REVIEW_TOKEN); if (id) console.error("review-log: settled budget reservation " + id); } + catch (e) { console.error("review-log: budget reservation not settled: " + e.message); } + ' || true +fi + # gbrain-sync: enqueue for cross-machine sync (no-op if sync is off). Plan B1: # an unattended session never enqueues, whatever the inherited sync mode. if [ "$("$SCRIPT_DIR/gstack-session-kind" 2>/dev/null || echo interactive)" = "unattended" ]; then diff --git a/bin/gstack-review-plan b/bin/gstack-review-plan index a5424c25a..06f3e3976 100755 --- a/bin/gstack-review-plan +++ b/bin/gstack-review-plan @@ -4,20 +4,25 @@ * * gstack-review-plan --base [--pass ] [--last none|full|fix-check] [--fixed-blocking] [--fixed-below] * [--blocking-open] [--touched-gate] [--critical-found] [--adversarial-ran] [--gate-tagged ] [--gated a,b] [--force a,b|all] - * [--reviewed-numbers ] [--no-tiers] [--json] + * [--reviewed-numbers ] [--depth-floor standard|full] [--no-tiers] [--json] * gstack-review-plan --fix-check-prompt --fix-list --hunks --tests [--callers ] * - * Reads the diff against the merge base with (committed, working tree and - * untracked), runs gstack-diff-scope and, unless --gate-tagged is given, - * gstack-gate-diff; prints REVIEW_CLASS:, REVIEW_PLAN:, one DISPATCH: line per - * reviewer and one SKIP: line per reviewer left out. Logic: lib/review-depth.ts. + * Reads the diff against the merge base with (committed, tracked uncommitted + * edits and untracked files, through lib/review-collect.ts collectLive), runs + * gstack-diff-scope and, unless --gate-tagged is given, gstack-gate-diff; prints + * REVIEW_CLASS:, REVIEW_DEPTH: (depth, runtime lines, the rules hash, reasons and + * result codes), GATE_SCAN:, REVIEW_PLAN:, one DEPTH_ERROR: per input that failed + * the depth closed, one DISPATCH: plus DIFF_CMD: (and DIFF_EXCLUDE: none) per + * reviewer and one SKIP: per reviewer left out. A plan that fails closed to full + * exits 0; a diff git cannot list exits 1. Logic: lib/review-depth.ts. */ -import { spawnSync } from 'node:child_process'; import * as fs from 'node:fs'; import * as path from 'node:path'; +import { spawnSync } from 'node:child_process'; import { EXIT, exitTableHelp } from '../lib/headless-artifacts'; import { runScriptSync } from '../lib/script-invocation'; -import { planReview, reviewPlanLine, scanNumbers, type History } from '../lib/review-depth'; +import { collectLive } from '../lib/review-collect'; +import { diffCommand, planReview, reviewDepthLine, reviewPlanLine, scanNumbers, type Depth, type History } from '../lib/review-depth'; import { renderFixCheckPrompt } from '../scripts/resolvers/fix-check'; const HELP = `gstack-review-plan — the review depth of the next /ship step (docs/review-policy.md#review-depth) @@ -25,19 +30,23 @@ const HELP = `gstack-review-plan — the review depth of the next /ship step (do --base the base branch (merge base with HEAD is the diff base); required --pass full review passes already run in this invocation (default 0) --last none|full|fix-check the step that just finished (default none: plan pass 1) - --fixed-blocking the finished step fixed a blocking finding + --fixed-blocking the finished step fixed a blocking finding (raises light to standard) --fixed-below the finished step fixed findings below the floor --blocking-open a blocking finding is still open in fix scope --touched-gate a fix touched a gate-class path - --critical-found a specialist reported a CRITICAL finding (Red Team on code class) + --critical-found a specialist reported a CRITICAL finding (Red Team on code class; raises light to standard) --adversarial-ran Step 11's native adversarial pass already ran (a repeat skips it) --gate-tagged gate hunks the gate scan tagged (default: run gstack-gate-diff; failure means unavailable) --gated a,b specialists the hit-rate stats tag GATE_CANDIDATE --force a,b|all specialists forced by prompt flags (--all-specialists is all) --reviewed-numbers the numeric-claim fingerprint the outside voice already reviewed + --depth-floor standard|full raise the depth to at least this (never lowers it); /ship passes its prompt flag on every run --no-tiers audits and watchers at the host's default effort too (as gstack-config review_effort_tiers off does) - --json the plan as JSON + --json the plan as JSON (depth, runtime_lines, rules, errors with input and repair, gate_scan, per-dispatch exclude) --fix-check-prompt print the fix-check reviewer's prompt from --fix-list, --hunks, --tests and --callers files + +Depth: light (runtime lines <= 50), standard (above 50), full (gate class or any DEPTH_ERROR). A full plan +from an error exits 0; exit 1 means no plan could be built (git could not list the diff). ${exitTableHelp()}`; const args = process.argv.slice(2); @@ -65,34 +74,17 @@ function main(): number { if (!['none', 'full', 'fix-check'].includes(last)) { process.stderr.write('gstack-review-plan: --last must be none, full or fix-check\n'); return EXIT.usage; } const pass = Number(flag('--pass') ?? '0'); if (!Number.isInteger(pass) || pass < 0) { process.stderr.write('gstack-review-plan: --pass needs an integer >= 0\n'); return EXIT.usage; } + const floor = flag('--depth-floor') as Depth | undefined; + if (has('--depth-floor') && floor !== 'standard' && floor !== 'full') { process.stderr.write('gstack-review-plan: --depth-floor must be standard or full (a floor only raises the depth)\n'); return EXIT.usage; } const root = git(['rev-parse', '--show-toplevel'])?.trim(); if (!root) { process.stderr.write('gstack-review-plan: run it inside a git checkout\n'); return EXIT.fail; } process.chdir(root); - const ref = git(['rev-parse', '--verify', '-q', `origin/${base}`]) !== null ? `origin/${base}` : base; - const mergeBase = git(['merge-base', ref, 'HEAD'])?.trim(); - if (!mergeBase) { process.stderr.write(`gstack-review-plan: no merge base with ${ref} (fetch the base first)\n`); return EXIT.fail; } - const nameStatusRaw = git(['diff', '--name-status', '--no-renames', mergeBase]); - const untrackedRaw = git(['ls-files', '--others', '--exclude-standard']); - const numstatRaw = git(['diff', '--numstat', mergeBase]); - if (nameStatusRaw === null || untrackedRaw === null || numstatRaw === null) { process.stderr.write('gstack-review-plan: git could not list the diff; no plan is safer than a plan for an empty diff\n'); return EXIT.fail; } - const scratch = (p: string) => p.startsWith('.gstack/tmp/'); - const nameStatus = nameStatusRaw.split('\n').filter(Boolean).map(l => l.split('\t')).filter(c => !scratch(c[1] ?? '')); - const untracked = untrackedRaw.split('\n').filter(Boolean).filter(p => !scratch(p)); - const paths = [...new Set([...nameStatus.map(c => c[1]!).filter(Boolean), ...untracked])].sort(); - const deleted = nameStatus.filter(c => c[0] === 'D').map(c => c[1]!); - const stampOnly = paths.filter(p => p.endsWith('package.json') && !untracked.includes(p)).filter(p => { - const changed = (git(['diff', '-U0', '--no-color', mergeBase, '--', p]) ?? '').split('\n').filter(l => /^[+-]/.test(l) && !/^(\+\+\+|---) /.test(l)); - return changed.length > 0 && changed.every(l => /^[+-]\s*"version"\s*:/.test(l)); - }); - const diffLines = numstatRaw.split('\n').reduce((n, l) => { const [a, d] = l.split('\t'); return n + (Number(a) || 0) + (Number(d) || 0); }, 0) - + untracked.reduce((n, p) => { try { return n + fs.readFileSync(p, 'utf8').split('\n').length; } catch { return n; } }, 0); - const added: Record = {}; - let current = ''; - for (const line of (git(['diff', '-U0', '--no-color', mergeBase]) ?? '').split('\n')) { - if (line.startsWith('+++ b/')) { current = line.slice(6); continue; } - if (line.startsWith('+') && !line.startsWith('+++') && current) (added[current] ??= []).push(line.slice(1)); + const collected = collectLive(root, base); + if (collected.errors.length) { + for (const e of collected.errors) process.stderr.write(`gstack-review-plan: git could not list the diff (${e.input}: ${e.detail}); fix: ${e.repair}; no plan is safer than a plan for an empty diff\n`); + return EXIT.fail; } - for (const p of untracked) { try { added[p] = fs.readFileSync(p, 'utf8').split('\n'); } catch { /* unreadable: no claims */ } } + const head = git(['rev-parse', 'HEAD'])?.trim() ?? 'unknown'; const binDir = path.dirname(Bun.fileURLToPath(import.meta.url)); const scopeRun = runScriptSync(path.join(binDir, 'gstack-diff-scope'), [base], { encoding: 'utf8', timeout: 60_000 }); const scope: Record = {}; @@ -109,14 +101,25 @@ function main(): number { const force = flag('--force') === 'all' ? 'all' as const : list('--force'); const tiersSetting = runScriptSync(path.join(binDir, 'gstack-config'), ['get', 'review_effort_tiers'], { encoding: 'utf8', timeout: 15_000 }); const auditEffort = has('--no-tiers') || (tiersSetting.stdout ?? '').trim() === 'off' ? 'host' : 'light'; + const { added, diffLines, paths, deleted, stampOnly, perPath, registry } = collected; const plan = planReview({ - paths, deleted, stampOnly, root, scope, gateTagged, diffLines, numbers: scanNumbers(added), force, gated: list('--gated'), + ...collected, scope, gateTagged, numbers: scanNumbers(added), force, gated: list('--gated'), floor, criticalFound: has('--critical-found'), adversarialRan: has('--adversarial-ran'), reviewedNumbers: flag('--reviewed-numbers'), history: { fullPasses: pass, last, fixedBlocking: has('--fixed-blocking'), fixedBelow: has('--fixed-below'), blockingOpen: has('--blocking-open'), touchedGate: has('--touched-gate') }, }); - if (has('--json')) { process.stdout.write(JSON.stringify({ ...plan, diff_lines: diffLines, pass, audit_effort: auditEffort, scope, gate_tagged: gateTagged, paths, deleted, stamp_only: stampOnly }) + '\n'); return EXIT.ok; } - const out = [`REVIEW_CLASS: ${plan.class} (${plan.reasons.slice(0, 3).join('; ') || 'no signals'})`, reviewPlanLine(plan, pass + (plan.next.step === 'full' ? 1 : 0)), `NEXT: ${plan.next.step} (${plan.next.reason})`]; - for (const d of plan.dispatches) out.push(`DISPATCH: ${d.role} ${d.name} effort=${d.effort}`); + const gateScan = { tagged: gateTagged, head }; + if (has('--json')) { + const { runtimeLines, stepDepth, depthReasons, ...rest } = plan; + process.stdout.write(JSON.stringify({ ...rest, step_depth: stepDepth, runtime_lines: runtimeLines, depth_reasons: depthReasons, depth_floor: floor ?? null, gate_scan: gateScan, registry: { sha: registry.sha, outputs: registry.outputs }, per_path: perPath, diff_lines: diffLines, pass, audit_effort: auditEffort, scope, gate_tagged: gateTagged, paths, deleted, stamp_only: stampOnly }) + '\n'); + return EXIT.ok; + } + const out = [`REVIEW_CLASS: ${plan.class} (${plan.reasons.slice(0, 3).join('; ') || 'no signals'})`, reviewDepthLine(plan), `GATE_SCAN: ${gateTagged === null ? 'unavailable' : `tagged=${gateTagged}`} head=${head}`, reviewPlanLine(plan, pass + (plan.next.step === 'full' ? 1 : 0)), `NEXT: ${plan.next.step} (${plan.next.reason})`]; + for (const e of plan.errors) out.push(`DEPTH_ERROR: ${e.code} input=${e.input} detail=${e.detail}; fix: ${e.repair}${e.result ? ` (${e.result})` : ''}`); + for (const d of plan.dispatches) { + const key = d.name.split(' ')[0]; + out.push(`DISPATCH: ${d.role} ${d.name} effort=${d.effort}${d.checklists ? ` checklists=${d.checklists.join(',')}` : ''}${d.reason ? ` reason=${d.reason}` : ''}`, `DIFF_CMD: ${key} ${diffCommand(d)}`); + if (!d.exclude.length) out.push(`DIFF_EXCLUDE: ${key} none`); + } for (const s of plan.skipped) out.push(`SKIP: ${s}`); out.push(`AUDIT_EFFORT: ${auditEffort} (coverage, plan-completion and docs audits, decision-trail reviewers, watchers; reviewers above stay full)`); process.stdout.write(out.join('\n') + '\n'); diff --git a/bin/gstack-ship-budget b/bin/gstack-ship-budget new file mode 100755 index 000000000..ecb3277dc --- /dev/null +++ b/bin/gstack-ship-budget @@ -0,0 +1,50 @@ +#!/usr/bin/env -S bun --no-env-file --config=/dev/null +/** + * gstack-ship-budget — the /ship token budget and fresh-context handoff + * (docs/ship-budget.md). An admission cap: no step or dispatch starts unless + * used + open reservations + unknown + its projection + the tail and stop + * reserve fit under the cap. + * + * start --record [--token-cap ] [--meter capy|claude|estimate] [--reading ] [--prior-reading ] + * [--session |--nonce ] [--reserve ] [--delegate auto|never] [--calibration ] [--ledger ] + * check --run |--record --step --next [,...]> [--reading ] [--prior-reading ] + * settle --run|--record --reservation [--unknown] release --run|--record --reservation + * handoff --run|--record --from --to --base origin/ [--reviewed-tree ] [--trail --trail-run ] + * [--sub-cap ] [--reading ] [--child-session ] + * launch --in (Claude Code: background headless child with explicit permissions) + * verify-handoff --in [--reading ] [--session ] + * return --run --to [--changed ] [--status complete|refused|incomplete] [--reading ] + * reconcile --run|--record (--return |--handoff ) [--reading ] + * resume --record |--run [--reading ] [--meter ] [--session ] [--token-cap --approved-by --words ] + * [--rebuild-from-record] + * close --run|--record [--reading ] [--approved-by --words ] + * + * Exit: 0 continue/delegate · 3 stop (the next step does not start) · 2 usage + * or validation (stderr). Logic: lib/ship-budget.ts, lib/ship-budget-cli.ts, + * lib/ship-handoff.ts. + */ +import { BudgetError } from '../lib/ship-budget'; +import { cmdCheck, cmdClose, cmdResume, cmdSettle, cmdStart, type Outcome } from '../lib/ship-budget-cli'; +import { cmdHandoff, cmdLaunch, cmdReconcile, cmdReturn, cmdVerifyHandoff } from '../lib/ship-handoff'; + +const [command, ...rest] = process.argv.slice(2); +const ctx = { env: process.env, cwd: process.cwd() }; +const commands: Record Outcome> = { + start: () => cmdStart(rest, ctx), check: () => cmdCheck(rest, ctx), settle: () => cmdSettle(rest, ctx), release: () => cmdSettle(rest, ctx, true), + handoff: () => cmdHandoff(rest, ctx), launch: () => cmdLaunch(rest, ctx), 'verify-handoff': () => cmdVerifyHandoff(rest, ctx), return: () => cmdReturn(rest, ctx), + reconcile: () => cmdReconcile(rest, ctx), resume: () => cmdResume(rest, ctx), close: () => cmdClose(rest, ctx), +}; +if (!command || command === '--help' || command === '-h' || !commands[command]) { + const text = (await Bun.file(import.meta.path).text()).split('\n').slice(2, 26).map(l => l.replace(/^ \* ?/, '')).join('\n'); + (command && command !== '--help' && command !== '-h' ? console.error : console.log)(text); + process.exit(command && command !== '--help' && command !== '-h' ? 2 : 0); +} +try { + const out = commands[command]!(); + if (out.stdout.length) console.log(out.stdout.join('\n')); + process.exit(out.exit); +} catch (e) { + if (!(e instanceof BudgetError)) throw e; + if (e.exit === 3) console.log(e.message); else console.error(e.message); + process.exit(e.exit); +} diff --git a/bin/gstack-ship-receipt b/bin/gstack-ship-receipt index d7d3940a0..1b24fd1af 100755 --- a/bin/gstack-ship-receipt +++ b/bin/gstack-ship-receipt @@ -36,16 +36,18 @@ import { EXIT, exitTableHelp, type ShipReceipt } from '../lib/headless-artifacts import { resultLine, resultLineWithDocs } from '../lib/result-codes'; import { versionAtRef } from '../lib/restamp'; import { readPregateFile, verifyPregate } from '../lib/pregate/index'; -import { isUnavailable, loadPolicyFromBase, matchesAny, policyUnavailableLine, resolveBaseBranch, stampFilesInTree, validatePolicy, type ShipPolicy } from '../lib/ship-policy'; +import { isUnavailable, loadPolicyFromBase, matchesAny, policyUnavailableLine, resolveBaseBranch, runningGstackVersion, stampFilesInTree, validatePolicy, type ShipPolicy } from '../lib/ship-policy'; import { approvalForReceipt } from '../lib/approval-citations'; import { CARRY_METADATA_GLOBS, CARRY_NAMED_PATHS, CARRY_TEST_GLOBS, - bindReceipt, carryReceipt, classifyCarryPath, computeCensus, extractReceipt, missingIssueLines, orderReceipt, parseReviewLoop, placeReceiptFirst, planCarry, + bindReceipt, carryReceipt, classifyCarryPath, computeCensus, extractReceipt, missingIssueLines, orderReceipt, parseReviewLoop, placeReceiptFirst, planCarry, planTreeCarry, receiptIssuesFrom, receiptSummaryLine, renderCensus, renderReceiptBlock, validateReceipt, type CensusPr, } from '../lib/ship-receipt'; import { checkDocsCaps, docsCapLine, docsExceptionLine, parseReceiptDocs } from '../lib/ship-receipt-docs'; +import { deeper, depthBelow, exceptionProblems, parseReviewLoopException, receiptDepthAtHead, reviewLoopExceptionLine } from '../lib/ship-receipt-depth'; import { checkReceiptProse, proseLine } from '../lib/ship-receipt-prose'; import { resolveStateRoot } from '../lib/state-root'; +import { isRegistryUnavailable, loadRegistryFromBase } from '../lib/regen'; const HELP = `gstack-ship-receipt — the \`\`\`gstack-ship-receipt\`\`\` block (docs/ship-policy.md#ship-receipt) @@ -61,10 +63,12 @@ const HELP = `gstack-ship-receipt — the \`\`\`gstack-ship-receipt\`\`\` block census --repo --since [--cohort ] the P7 adoption number over merged PRs (deduplicated by run and thread) carry --pr [--repo ] | --body [--base ] [--head ] [--pregate ] [--dry-run] [--out ] - carry the receipt to HEAD when only a base merge, tests or release metadata changed - since its head (product patch-id unchanged): rewrites the receipt with a \`carry\` record, - posts the body (gh pr edit) and prints GSTACK_RESULT: skill=ship status=complete; - RECEIPT_CARRY_PRODUCT_CHANGED / RECEIPT_CARRY_REFUSED leave the body unchanged (exit 3); + carry the receipt to HEAD when only a base merge, tests, release metadata or registered + outputs the --pregate regen check proved (recreated them) changed since its head (product patch-id + unchanged), or after a rebase onto a tree the receipt covers with the recorded product + patch-id: rewrites the receipt with a \`carry\` record, posts the body (gh pr edit) and + prints GSTACK_RESULT: skill=ship status=complete; RECEIPT_CARRY_PRODUCT_CHANGED / + RECEIPT_CARRY_TREE_MISMATCH / RECEIPT_CARRY_REFUSED leave the body unchanged (exit 3); a receipt that records a pregate needs --pregate current for HEAD (RECEIPT_CARRY_PREGATE_STALE); needs git >= 2.39 (RECEIPT_GIT_TOO_OLD) docs-caps [--base ] /ship Step 14.5: one DOCS_CAP: / ok|over line per docs.caps entry of the @@ -80,6 +84,11 @@ write flags: --pr --head --base --version --gated-tree --predecessor --gate ({passes, blocking_found, deferred[, noted, fixed, scope]}: gstack-review-scope summary --out) --docs ({status: updated|current|blocked, scope[, exception: {accepted_by, date, via, reason}]}: Step 14.5's outcome; blocked without an exception is DOCS_AUDIT_BLOCKED, and with --body the body must carry the exception line verbatim) + --review-loop-exception ({accepted_by, date, via, reason, fix_check: {head, findings[, files]}}: the owner accepted a + stop after a fix-check edit; needs --review-loop with fix_checks >= 1, fix_check.head an ancestor of the head, and with --body the + "Review-loop exception: …" line verbatim; else REVIEW_LOOP_EXCEPTION_INVALID). Every receipt records gstack_version and + review_depth: the depth HEAD needs, recomputed from the committed range (--head must be HEAD; a dirty checkout or an + unreadable input records full). --approval-run (repeatable; resolves plan-sha citations) (W2: a class declared in origin/'s .gstack/approval-classes.json with hits needs a citation that resolves and binds to its effects: APPROVAL_CITATION_MISSING) --out --body . Defaults: head=HEAD, base=origin/HEAD's branch, version=the @@ -134,10 +143,30 @@ function receiptVersion(repoRoot: string, head: string, base: string): string | return 'none'; } +/** + * What a later carry across rewritten history compares: the head's tree and its + * product patch-id against the base. Both are evidence, never a gate: a head + * outside a checkout (or a base that does not resolve) records neither, and + * such a receipt then carries only along its own history. + */ +function reviewedProduct(repoRoot: string, base: string, head: string, pregateFile: string | undefined): { head_tree?: string; product_patch_id?: string } { + const tree = git(['rev-parse', '--verify', '--quiet', `${head}^{tree}`], repoRoot); + if (!tree) return {}; + const baseRef = `origin/${base.replace(/^origin\//, '')}`; + const id = productPatchAgainstBase(repoRoot, productRules(repoRoot, base, verifiedOutputs(repoRoot, base, pregateFile)), baseRef, head); + return typeof id === 'string' ? { head_tree: tree, product_patch_id: id || 'none' } : { head_tree: tree }; +} + function cmdWrite(rest: string[], json: boolean): number { const repoRoot = git(['rev-parse', '--show-toplevel']) ?? process.cwd(); - const head = flag(rest, '--head') ?? git(['rev-parse', 'HEAD'], repoRoot); + const checkedOut = git(['rev-parse', 'HEAD'], repoRoot); + const head = flag(rest, '--head') ?? checkedOut; if (!head) { process.stderr.write('gstack-ship-receipt write: --head is required outside a git repository\n'); return EXIT.usage; } + const headSha = git(['rev-parse', '--verify', '--quiet', `${head}^{commit}`], repoRoot); + if (checkedOut && headSha !== checkedOut) { + process.stderr.write(resultLine('gstack-ship-receipt write', 'RECEIPT_INVALID', `--head ${head.slice(0, 12)} is not the checked-out HEAD ${checkedOut.slice(0, 12)}; the receipt binds the reviewed tree, so check out ${head.slice(0, 12)} and write there; nothing written`) + '\n'); + return EXIT.fail; + } const receiptFile = flag(rest, '--receipt'); const tree = receiptFile ? JSON.parse(fs.readFileSync(receiptFile, 'utf8')) : null; let sessionKind = flag(rest, '--session-kind') ?? process.env.GSTACK_SESSION_KIND; @@ -165,6 +194,19 @@ function cmdWrite(rest: string[], json: boolean): number { return EXIT.refused; } } + let loopException: ReturnType | undefined; + if (flag(rest, '--review-loop-exception') !== undefined) { + const refuse = (why: string) => { process.stderr.write(resultLineWithDocs('gstack-ship-receipt write', 'REVIEW_LOOP_EXCEPTION_INVALID', `${why}; nothing written`) + '\n'); return EXIT.fail; }; + try { loopException = parseReviewLoopException(jsonArg(flag(rest, '--review-loop-exception'))); } catch (e: any) { return refuse(`--review-loop-exception: ${e.message}`); } + if (!loopException.ok) return refuse(loopException.message); + let loop: unknown; try { loop = jsonArg(flag(rest, '--review-loop')); } catch {} + if (!parseReviewLoop(loop)?.fix_checks) return refuse('--review-loop-exception needs --review-loop with fix_checks >= 1: the stop it accepts follows a fix-check'); + const fc = loopException.exception.fix_check.head; + if (spawnSync('git', ['merge-base', '--is-ancestor', fc, head], { cwd: repoRoot }).status !== 0) return refuse(`fix_check.head ${fc.slice(0, 12)} is not ${head.slice(0, 12)} or an ancestor of it`); + const line = reviewLoopExceptionLine(loopException.exception); + if (bodyFile && !bodyText.split(/\r?\n/).some(l => l.trim() === line)) return refuse(`${bodyFile} does not carry the exception line verbatim: ${JSON.stringify(line)}`); + } + const reviewDepth = receiptDepthAtHead(repoRoot, base, path.dirname(Bun.fileURLToPath(import.meta.url)), headSha ?? head); const approval = approvalForReceipt({ repoRoot, base, head, citationText: [bodyText, ...flags(rest, '--approval')].join('\n'), runDirs: flags(rest, '--approval-run') }); if (approval.kind === 'invalid') { for (const line of approval.lines) process.stderr.write(resultLine('gstack-ship-receipt write', 'APPROVAL_CLASSES_INVALID', line) + '\n'); @@ -194,7 +236,8 @@ function cmdWrite(rest: string[], json: boolean): number { session_kind: sessionKind, artifacts_consumed: flag(rest, '--artifacts-consumed'), run: flag(rest, '--run'), thread: flag(rest, '--thread'), policy: flag(rest, '--policy') ?? tree?.policy, queue_mode: flag(rest, '--queue-mode'), preregistration: flag(rest, '--preregistration'), history: flag(rest, '--history'), ...pregate, issues: issuesFile ? receiptIssuesFrom(issuesFile) : undefined, approval: approval.kind === 'ok' ? approval.approval : undefined, - review_loop: reviewLoop, ...(docs?.ok ? { docs: docs.docs } : {}), + review_loop: reviewLoop, ...(docs?.ok ? { docs: docs.docs } : {}), ...reviewedProduct(repoRoot, base, head, pregateFile), + gstack_version: runningGstackVersion(), review_depth: reviewDepth, review_loop_exception: loopException?.ok ? loopException.exception : undefined, }; } catch (e: any) { process.stderr.write(`gstack-ship-receipt write: ${e.message}\n`); return EXIT.usage; } if (input.pr !== undefined && !Number.isInteger(input.pr)) { process.stderr.write('gstack-ship-receipt write: --pr must be an integer\n'); return EXIT.usage; } @@ -367,13 +410,73 @@ function pregateFieldFor(repoRoot: string, file: string, head: string): { ok: tr return { ok: true, field: { pregate: `${read.file.verdict ?? 'pass'} @${read.file.tree.slice(0, 12)} (${read.file.checks.length} checks, current for ${head.slice(0, 12)})`, requires_remote: remote.length ? remote.map(r => `${r.lane}: ${r.receipt}`) : undefined } }; } +/** + * Generated outputs the carry may set aside as metadata: the paths the pregate + * passed for HEAD proved (its regen check deleted each touched output and the + * entry's command recreated it byte-identically), when that check ran + * origin/'s `.gstack/generated.json` at the commit this carry reads and the + * path is an output of an entry with a `command` there. A proven name with glob + * syntax is product too: the carry uses these paths as pathspec globs. + */ +function verifiedOutputs(repoRoot: string, base: string, pregateFile: string | undefined): string[] { + if (!pregateFile) return []; + const regen = readPregateFile(pregateFile).file?.checks.find(c => c.id === 'regen'); + if (!regen || regen.status !== 'pass' || !regen.proven?.length) return []; + const load = loadRegistryFromBase(repoRoot, base); + if (isRegistryUnavailable(load) || load.errors.length || regen.inputs?.registry !== load.source.label) return []; + const owned = load.registry.entries.filter(e => e.command).flatMap(e => e.outputs); + return regen.proven.filter(p => !/[*?[\]\\]/.test(p) && matchesAny(owned, p)); +} + +interface ProductRules { extra: { metadata: string[]; outputs: readonly string[] }; metadata: string[]; templates: readonly string[] } +function productRules(repoRoot: string, base: string, outputs: readonly string[]): ProductRules { + const load = loadPolicyFromBase(repoRoot, base); + const policy: ShipPolicy | null = isUnavailable(load) ? null : load.policy; + const extra = { metadata: [...(policy?.stamp_files ?? []), ...(policy?.stamp_paths ?? []), ...(policy?.release_outputs ?? []), ...(policy?.changelog ? [policy.changelog] : [])], outputs }; + return { extra, metadata: [...CARRY_METADATA_GLOBS, ...extra.metadata, ...outputs], templates: policy?.stamp_patterns ?? [] }; +} + +/** + * The product pathspec between two commits: every path but tests and release + * metadata, where a metadata-listed path whose change from `from` to `to` is + * not a stamp stays product (every glob that matches it leaves the exclusion). + */ +function productSpec(repoRoot: string, rules: ProductRules, from: string, to: string): { changed: Array<{ path: string; class: ReturnType }>; product: string[]; tests: string[] } | undefined { + const changedRaw = git(['diff', '--name-only', from, to], repoRoot); + if (changedRaw === undefined) return undefined; + const blobAt = (ref: string, p: string): string | null => { const r = spawnSync('git', ['show', `${ref}:${p}`], { cwd: repoRoot, encoding: 'utf8', timeout: 30_000, maxBuffer: 16 * 1024 * 1024 }); return r.status === 0 ? r.stdout : null; }; + const versionAt = (ref: string): string | null => { + const file = blobAt(ref, 'VERSION'); + if (file !== null) return file.trim() || null; + try { const v = JSON.parse(blobAt(ref, 'package.json') ?? 'null')?.version; return typeof v === 'string' ? v : null; } catch { return null; } + }; + const oldVersion = versionAt(from); + const newVersion = versionAt(to); + const changed = changedRaw.split('\n').filter(Boolean).map(p => ({ path: p, class: classifyCarryPath(p, rules.extra, matchesAny(rules.metadata, p) && !matchesAny(rules.extra.outputs, p) ? { before: blobAt(from, p), after: blobAt(to, p), oldVersion, newVersion, templates: rules.templates } : undefined) })); + const excludeGlobs = (globs: readonly string[]) => globs.map(g => `:(exclude,glob)${g}`); + const demoted = changed.filter(c => c.class === 'product' && matchesAny(rules.metadata, c.path)).map(c => c.path); + const metadataGlobs = rules.metadata.filter(g => !demoted.some(p => matchesAny([g], p))); + return { changed, product: ['.', ...excludeGlobs(CARRY_TEST_GLOBS), ...excludeGlobs(metadataGlobs)], tests: [...CARRY_TEST_GLOBS.map(g => `:(glob)${g}`), ...excludeGlobs(metadataGlobs)] }; +} + +/** A commit's product patch-id against its merge base with the base ('' for no product diff), as write records it and a rewritten-history carry recomputes it. */ +function productPatchAgainstBase(repoRoot: string, rules: ProductRules, baseRef: string, commit: string): string | { error: string } { + const mergeBase = git(['merge-base', baseRef, commit], repoRoot); + if (!mergeBase) return { error: `cannot resolve the merge base of ${baseRef} and ${commit.slice(0, 12)}` }; + const spec = productSpec(repoRoot, rules, mergeBase, commit); + if (!spec) return { error: `git diff ${mergeBase.slice(0, 12)} ${commit.slice(0, 12)} failed` }; + return patchId(repoRoot, mergeBase, commit, spec.product); +} + /** * The receipt follows HEAD when the reviewed product is unchanged * (docs/unattended.md#the-terminal-line; harness lane E row 3). Four Captains * reran a full /ship on identical product code after a base merge or a * test-only fix; the carry compares the product diff against the base at the * receipt's head and at HEAD by patch-id, classifies every changed path, and - * records the range-diff as evidence in the receipt it rewrites. + * records the range-diff as evidence in the receipt it rewrites. After a rebase + * or force-push it carries only onto a tree the receipt covers whose product + * patch-id against the current base is the recorded one (planTreeCarry). */ function cmdCarry(rest: string[], json: boolean): number { const bodyFile = flag(rest, '--body'); @@ -384,7 +487,7 @@ function cmdCarry(rest: string[], json: boolean): number { if (!repoRoot) { process.stderr.write('gstack-ship-receipt carry: run it inside the git checkout whose head carries the receipt\n'); return EXIT.usage; } const head = (flag(rest, '--head') ?? git(['rev-parse', 'HEAD'], repoRoot))?.toLowerCase(); if (!head || !/^[0-9a-f]{40,64}$/.test(head)) { process.stderr.write('gstack-ship-receipt carry: cannot resolve HEAD\n'); return EXIT.usage; } - const refused = (code: 'QUEUE_RECEIPT_MISSING' | 'RECEIPT_CARRY_REFUSED' | 'RECEIPT_CARRY_PRODUCT_CHANGED' | 'RECEIPT_GIT_TOO_OLD' | 'RECEIPT_CARRY_PREGATE_STALE', message: string) => { + const refused = (code: 'QUEUE_RECEIPT_MISSING' | 'RECEIPT_CARRY_REFUSED' | 'RECEIPT_CARRY_PRODUCT_CHANGED' | 'RECEIPT_CARRY_TREE_MISMATCH' | 'RECEIPT_GIT_TOO_OLD' | 'RECEIPT_CARRY_PREGATE_STALE', message: string) => { process.stderr.write(resultLineWithDocs('gstack-ship-receipt carry', code, message) + '\n'); process.stdout.write(json ? JSON.stringify({ skill: 'ship', status: 'refused', run: '-', code, message }) + '\n' : `CARRY: refused (${code})\nGSTACK_RESULT: skill=ship status=refused run=-\n`); return EXIT.refused; @@ -425,66 +528,79 @@ function cmdCarry(rest: string[], json: boolean): number { } const oldGit = gitVersionBelow(repoRoot, CARRY_MIN_GIT); if (oldGit) return refused('RECEIPT_GIT_TOO_OLD', `git ${oldGit} cannot run patch-id --verbatim; the carry needs git ${CARRY_MIN_GIT} or later`); - const ancestor = spawnSync('git', ['merge-base', '--is-ancestor', from, head], { cwd: repoRoot, encoding: 'utf8', timeout: 30_000 }); - if (ancestor.status !== 0) return refused('RECEIPT_CARRY_REFUSED', `the receipt's head ${from.slice(0, 12)} is not an ancestor of HEAD ${head.slice(0, 12)} (rebased or force-pushed); merge the base in next time, and run /ship now`); // The carry binds HEAD alone: pending edits are not in the commits it compares, and a parent that stops at CARRY: carried would report them shipped. const status = spawnSync('git', ['status', '--porcelain', '--untracked-files=all'], { cwd: repoRoot, encoding: 'utf8', timeout: 30_000, maxBuffer: 16 * 1024 * 1024 }); if (status.status !== 0) return refused('RECEIPT_CARRY_REFUSED', 'git status failed; the carry needs a readable working tree'); const dirty = status.stdout.split('\n').filter(Boolean).map(l => l.slice(3).replace(/^.* -> /, '')); if (dirty.length) return refused('RECEIPT_CARRY_REFUSED', `the working tree has uncommitted changes (${dirty.slice(0, 5).join(', ')}${dirty.length > 5 ? ` +${dirty.length - 5} more` : ''}); commit them and carry at the new head, or run /ship`); + const fromKnown = git(['cat-file', '-e', `${from}^{commit}`], repoRoot) !== undefined; + const ancestor = fromKnown && spawnSync('git', ['merge-base', '--is-ancestor', from, head], { cwd: repoRoot, encoding: 'utf8', timeout: 30_000 }).status === 0; + const fromTree = fromKnown ? git(['rev-parse', `${from}^{tree}`], repoRoot) : undefined; + const covered = [...(receipt.head_tree ? [receipt.head_tree] : fromTree ? [fromTree] : []), ...(receipt.carry?.trees ?? [])]; + if (!ancestor && !covered.length) return refused('RECEIPT_CARRY_REFUSED', `the receipt's head ${from.slice(0, 12)} is not an ancestor of HEAD ${head.slice(0, 12)} (rebased or force-pushed), and the receipt records no tree to compare; merge the base in next time, and run /ship now`); const base = flag(rest, '--base') ?? receipt.base ?? resolveBaseBranch(repoRoot); const baseRef = `origin/${base.replace(/^origin\//, '')}`; - const fromBase = git(['merge-base', baseRef, from], repoRoot); const headBase = git(['merge-base', baseRef, head], repoRoot); - if (!fromBase || !headBase) return refused('RECEIPT_CARRY_REFUSED', `cannot resolve the merge base of ${baseRef} (fetch it first)`); - const load = loadPolicyFromBase(repoRoot, base); - const policy = isUnavailable(load) ? null : load.policy; - const extra = { metadata: [...(policy?.stamp_files ?? []), ...(policy?.stamp_paths ?? []), ...(policy?.release_outputs ?? []), ...(policy?.changelog ? [policy.changelog] : [])] }; - const changedRaw = git(['diff', '--name-only', from, head], repoRoot); - if (changedRaw === undefined) return refused('RECEIPT_CARRY_REFUSED', `git diff ${from.slice(0, 12)} ${head.slice(0, 12)} failed`); - // Every metadata-listed path is read at both heads: only a stamp keeps it out of the product patch. - const blobAt = (ref: string, p: string): string | null => { const r = spawnSync('git', ['show', `${ref}:${p}`], { cwd: repoRoot, encoding: 'utf8', timeout: 30_000, maxBuffer: 16 * 1024 * 1024 }); return r.status === 0 ? r.stdout : null; }; - const versionAt = (ref: string): string | null => { - const file = blobAt(ref, 'VERSION'); - if (file !== null) return file.trim() || null; - try { const v = JSON.parse(blobAt(ref, 'package.json') ?? 'null')?.version; return typeof v === 'string' ? v : null; } catch { return null; } - }; - const oldVersion = versionAt(from); - const newVersion = versionAt(head); - const allMetadataGlobs = [...CARRY_METADATA_GLOBS, ...extra.metadata]; - const changed = changedRaw.split('\n').filter(Boolean).map(p => ({ path: p, class: classifyCarryPath(p, extra, matchesAny(allMetadataGlobs, p) ? { before: blobAt(from, p), after: blobAt(head, p), oldVersion, newVersion, templates: policy?.stamp_patterns ?? [] } : undefined) })); - // Pathspecs by class: tests and metadata are excluded from the product patch; the test patch is the tests alone. - // A metadata-listed path whose change was not a stamp stays in the product patch: every glob that matches it is dropped from the exclusion. - const excludeGlobs = (globs: readonly string[]) => globs.map(g => `:(exclude,glob)${g}`); - const demoted = changed.filter(c => c.class === 'product' && matchesAny(allMetadataGlobs, c.path)).map(c => c.path); - const metadataGlobs = allMetadataGlobs.filter(g => !demoted.some(p => matchesAny([g], p))); - const productSpec = ['.', ...excludeGlobs(CARRY_TEST_GLOBS), ...excludeGlobs(metadataGlobs)]; - const testSpec = [...CARRY_TEST_GLOBS.map(g => `:(glob)${g}`), ...excludeGlobs(metadataGlobs)]; - const productFrom = patchId(repoRoot, fromBase, from, productSpec); - const productHead = patchId(repoRoot, headBase, head, productSpec); - const asId = (r: string | { error: string }) => (typeof r === 'string' ? r : ''); - const testFrom = asId(patchId(repoRoot, fromBase, from, testSpec)); - const testHead = asId(patchId(repoRoot, headBase, head, testSpec)); - for (const r of [productFrom, productHead]) if (typeof r !== 'string') return refused('RECEIPT_CARRY_REFUSED', `git could not compute the product patch-id at one of the heads: ${r.error}`); - // planCarry names at most CARRY_NAMED_PATHS differing paths, so the per-path comparison (two patch-ids each) stops there, - // and it walks only the paths the branch itself touched against the base at either head: a base merge brings in every - // path the base changed, none of which can differ between the two base diffs. - const changedProduct: string[] = []; - if (productFrom !== productHead) { - const touched = new Set([...(git(['diff', '--name-only', fromBase, from], repoRoot) ?? '').split('\n'), ...(git(['diff', '--name-only', headBase, head], repoRoot) ?? '').split('\n')].filter(Boolean)); - for (const p of [...touched].sort()) { - if (changedProduct.length >= CARRY_NAMED_PATHS) break; - const cls = changed.find(c => c.path === p)?.class ?? classifyCarryPath(p, extra); - if (cls !== 'product') continue; - if (asId(patchId(repoRoot, fromBase, from, [p])) !== asId(patchId(repoRoot, headBase, head, [p]))) changedProduct.push(p); + if (!headBase) return refused('RECEIPT_CARRY_REFUSED', `cannot resolve the merge base of ${baseRef} (fetch it first)`); + const rules = productRules(repoRoot, base, verifiedOutputs(repoRoot, base, flag(rest, '--pregate'))); + const headTree = git(['rev-parse', `${head}^{tree}`], repoRoot); + if (!headTree) return refused('RECEIPT_CARRY_REFUSED', `git could not read the tree of HEAD ${head.slice(0, 12)}`); + const headPatch = productPatchAgainstBase(repoRoot, rules, baseRef, head); + if (typeof headPatch !== 'string') return refused('RECEIPT_CARRY_REFUSED', `git could not compute HEAD's product patch-id: ${headPatch.error}`); + const reviewedBase = receipt.base.replace(/^origin\//, ''); + const retarget = reviewedBase !== base.replace(/^origin\//, ''); + let plan: ReturnType; + if (!ancestor) { + // Rewritten history: the receipt follows only onto a tree it already covers, with the product diff it recorded. + const recorded = receipt.product_patch_id !== undefined ? (receipt.product_patch_id === 'none' ? '' : receipt.product_patch_id) : fromKnown ? productPatchAgainstBase(repoRoot, rules, baseRef, from) : { error: 'the receipt records no product patch-id and its head is not in this clone' }; + if (typeof recorded !== 'string') return refused('RECEIPT_CARRY_REFUSED', `the reviewed product patch-id is unavailable: ${recorded.error}; run /ship on ${head.slice(0, 12)}`); + plan = planTreeCarry({ from, head, headTree, coveredTrees: covered, productPatchId: { recorded, head: headPatch } }); + } else { + const fromBase = git(['merge-base', baseRef, from], repoRoot); + if (!fromBase) return refused('RECEIPT_CARRY_REFUSED', `cannot resolve the merge base of ${baseRef} (fetch it first)`); + const spec = productSpec(repoRoot, rules, from, head); + if (!spec) return refused('RECEIPT_CARRY_REFUSED', `git diff ${from.slice(0, 12)} ${head.slice(0, 12)} failed`); + const { changed } = spec; + const productFrom = patchId(repoRoot, fromBase, from, spec.product); + const productHead = patchId(repoRoot, headBase, head, spec.product); + const asId = (r: string | { error: string }) => (typeof r === 'string' ? r : ''); + const testFrom = asId(patchId(repoRoot, fromBase, from, spec.tests)); + const testHead = asId(patchId(repoRoot, headBase, head, spec.tests)); + for (const r of [productFrom, productHead]) if (typeof r !== 'string') return refused('RECEIPT_CARRY_REFUSED', `git could not compute the product patch-id at one of the heads: ${r.error}`); + // A stacked child whose parent landed on the base (#3570): the receipt reviewed the child's own range against the + // parent branch, and the PR now targets the base. That reviewed range (the recorded product patch-id, else the one + // against origin/ when it still resolves) must be HEAD's whole product diff against the base, computed + // the way write records it (headPatch): the parent fully landed and the child is unchanged. Anything else fails closed. + let reviewed = productFrom; + if (retarget) { + const parentRef = `origin/${reviewedBase}`; + const recorded = receipt.product_patch_id !== undefined ? (receipt.product_patch_id === 'none' ? '' : receipt.product_patch_id) + : git(['rev-parse', '--verify', '--quiet', `${parentRef}^{commit}`], repoRoot) ? productPatchAgainstBase(repoRoot, rules, parentRef, from) : { error: `the receipt records no product patch-id and ${parentRef} no longer resolves` }; + if (typeof recorded !== 'string') return refused('RECEIPT_CARRY_REFUSED', `the receipt was reviewed against ${reviewedBase}, not ${base}, and its reviewed product diff is unavailable: ${recorded.error}; run /ship on ${head.slice(0, 12)}`); + reviewed = recorded; } - if (!changedProduct.length) changedProduct.push('(a product path outside the branch\'s touched files; compare the two base diffs)'); + const current = retarget ? headPatch : productHead; + const changedProduct: string[] = []; + if (retarget && reviewed !== current) changedProduct.push(`HEAD's product diff against ${base} is not the one reviewed against ${reviewedBase} (the parent has not fully landed on ${base}, or the branch changed since)`); + else if (productFrom !== productHead && !retarget) { + // planCarry names at most CARRY_NAMED_PATHS differing paths, so the per-path comparison (two patch-ids each) stops there, + // and it walks only the paths the branch itself touched against the base at either head: a base merge brings in every + // path the base changed, none of which can differ between the two base diffs. + const touched = new Set([...(git(['diff', '--name-only', fromBase, from], repoRoot) ?? '').split('\n'), ...(git(['diff', '--name-only', headBase, head], repoRoot) ?? '').split('\n')].filter(Boolean)); + for (const p of [...touched].sort()) { + if (changedProduct.length >= CARRY_NAMED_PATHS) break; + const cls = changed.find(c => c.path === p)?.class ?? classifyCarryPath(p, rules.extra); + if (cls !== 'product') continue; + if (asId(patchId(repoRoot, fromBase, from, [p])) !== asId(patchId(repoRoot, headBase, head, [p]))) changedProduct.push(p); + } + if (!changedProduct.length) changedProduct.push('(a product path outside the branch\'s touched files; compare the two base diffs)'); + } + const mergeCommits = (git(['rev-list', '--merges', '--count', `${from}..${head}`], repoRoot) ?? '0').trim(); + // Evidence for the record, never the decision: a slow range-diff is reported unavailable rather than waited for. + const rangeRaw = spawnSync('git', ['range-diff', '--no-color', `${fromBase}..${from}`, `${headBase}..${head}`], { cwd: repoRoot, encoding: 'utf8', timeout: 15_000, maxBuffer: 64 * 1024 * 1024 }); + const rangeDiff = rangeRaw.status === 0 ? (rangeRaw.stdout.trim().split('\n').slice(0, 20).join('\n') || '(empty: identical ranges)') : `unavailable: ${(rangeRaw.stderr ?? '').trim().split('\n')[0] || (rangeRaw.signal ? `range-diff killed by ${rangeRaw.signal} after 15 s` : 'range-diff failed')}`; + plan = planCarry({ from, head, changed, productPatchId: { from: reviewed as string, head: current as string }, testPatchId: { from: testFrom, head: testHead }, changedProduct, mergeCommits: Number(mergeCommits) || 0, rangeDiff, ...(retarget ? { retargetedFrom: reviewedBase } : {}) }); } - const mergeCommits = (git(['rev-list', '--merges', '--count', `${from}..${head}`], repoRoot) ?? '0').trim(); - // Evidence for the record, never the decision: a slow range-diff is reported unavailable rather than waited for. - const rangeRaw = spawnSync('git', ['range-diff', '--no-color', `${fromBase}..${from}`, `${headBase}..${head}`], { cwd: repoRoot, encoding: 'utf8', timeout: 15_000, maxBuffer: 64 * 1024 * 1024 }); - const rangeDiff = rangeRaw.status === 0 ? (rangeRaw.stdout.trim().split('\n').slice(0, 20).join('\n') || '(empty: identical ranges)') : `unavailable: ${(rangeRaw.stderr ?? '').trim().split('\n')[0] || (rangeRaw.signal ? `range-diff killed by ${rangeRaw.signal} after 15 s` : 'range-diff failed')}`; - const plan = planCarry({ from, head, changed, productPatchId: { from: productFrom, head: productHead }, testPatchId: { from: testFrom, head: testHead }, changedProduct, mergeCommits: Number(mergeCommits) || 0, rangeDiff }); if (!plan.ok) return refused(plan.code, plan.message); // Eligibility is not publication: a receipt that recorded a pregate is rebound only with a pregate current for HEAD, // so a carried receipt never claims the old tree's checks (docs/ship-policy.md#receipt-carry). @@ -499,7 +615,21 @@ function cmdCarry(rest: string[], json: boolean): number { } else if (receipt.pregate && !rest.includes('--dry-run')) { return refused('RECEIPT_CARRY_PREGATE_STALE', `the receipt records a pregate for ${receipt.head.slice(0, 12)}; run gstack-pregate at HEAD ${head.slice(0, 12)} and pass --pregate `); } - const carried = carryReceipt(pregateField ? { ...receipt, ...pregateField } : receipt, head, plan.carry); + let depthField: Partial = {}; + const isAncestor = (commit: string) => !ancestor || spawnSync('git', ['merge-base', '--is-ancestor', commit, head], { cwd: repoRoot, timeout: 30_000 }).status === 0; + const problems = exceptionProblems(body, receipt, isAncestor); + if (problems.length) return refused('RECEIPT_CARRY_REFUSED', `the receipt's owner exception does not stand: ${problems.join('; ')}; run /ship on ${head.slice(0, 12)}`); + if (receipt.review_depth || receipt.gstack_version) { + if (!receipt.review_depth) return refused('RECEIPT_CARRY_REFUSED', `the receipt records gstack_version but no review_depth, so the queue would refuse it; run /ship on ${head.slice(0, 12)}`); + const checkedOut = git(['rev-parse', 'HEAD'], repoRoot)?.toLowerCase(); + if (checkedOut !== head) return refused('RECEIPT_CARRY_REFUSED', `--head ${head.slice(0, 12)} is not the checked-out HEAD ${(checkedOut ?? 'none').slice(0, 12)}; the gate scan reads the checkout, so check out ${head.slice(0, 12)} and carry there`); + const now = receiptDepthAtHead(repoRoot, base, path.dirname(Bun.fileURLToPath(import.meta.url)), head); + if (depthBelow(receipt.review_depth.depth, now.depth)) return refused('RECEIPT_CARRY_REFUSED', `HEAD ${head.slice(0, 12)} needs ${now.depth} review depth (${now.reasons.join(', ')}), above the receipt's ${receipt.review_depth.depth}; run /ship on ${head.slice(0, 12)}`); + depthField = { review_depth: { ...now, depth: deeper(receipt.review_depth.depth, now.depth) } }; + } + // The rebound product_patch_id is HEAD's diff against the carry's base, so a retargeted receipt names that base from now on. + const rebound = { ...receipt, ...(retarget ? { base: base.replace(/^origin\//, '') } : {}), ...(pregateField ?? {}), ...depthField }; + const carried = carryReceipt(rebound, head, plan.carry, { tree: headTree, fromTree, productPatchId: headPatch }); const errors = validateReceipt(carried); if (errors.length) return refused('RECEIPT_CARRY_REFUSED', `the carried receipt does not validate: ${errors[0]!.message} at ${errors[0]!.path}`); const newBody = placeReceiptFirst(body, carried); diff --git a/bin/gstack-version-bump b/bin/gstack-version-bump index ba6a51254..c9b0d71f1 100755 --- a/bin/gstack-version-bump +++ b/bin/gstack-version-bump @@ -25,8 +25,14 @@ // the caller must handle), exit 2 on bad args / unresolvable base / // broken version source. // -// write --version [--version-path

] [--regen-digest] [--changelog

] +// write --version [--version-path

] [--regen-digest] [--changelog

] [--manifest-form npm|full] // Validates the 4-digit pattern, writes VERSION + package.json.version. +// --manifest-form full: the manifest and its npm lockfiles carry the +// version as written instead of the npm-valid translation (default +// npm). For repos whose declared convention is a four-part manifest +// (gbrain); gstack-restamp passes it only when the policy lists the +// manifest as a stamp file and the base's copy holds four parts. No +// effect when the version path is itself a JSON manifest. // --changelog

(opt-in): re-head the branch's `## [Unreleased]` // entry in

as `## [] - ` at the top, with // lib/changelog-check's reheadChangelog — the same function @@ -455,6 +461,8 @@ function cmdWrite(args: string[], cwd: string): void { if (!VERSION_RE.test(version!)) { fail(`NEW_VERSION (${version}) does not match MAJOR.MINOR.PATCH[.MICRO]. Aborting.`, 2); } + const manifestForm = argVal(args, "--manifest-form") ?? "npm"; + if (manifestForm !== "npm" && manifestForm !== "full") fail("write: --manifest-form needs npm|full", 2); const src = versionSource(cwd, argVal(args, "--version-path")); if (src.outcome === "broken") failBroken(src, "write"); if (src.outcome !== "valid") { @@ -528,7 +536,8 @@ function cmdWrite(args: string[], cwd: string): void { // 3-digit translation — npm rejects a fourth component, so mirroring the // raw 4-digit form breaks `npm ci` in any repo npm actually manages. // VERSION keeps the full 4-digit form; it stays the source of truth. - const manifestV = npmVersion(version!); + // --manifest-form full keeps a repo's declared four-part manifest as is. + const manifestV = manifestForm === "full" ? version! : npmVersion(version!); if (hasPkg) { let pkgWritten = false; try { diff --git a/browse/SKILL.md b/browse/SKILL.md index 21081c0d2..e5792ca58 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -452,8 +452,7 @@ HTML into a PNG or PDF is the render engine's job: use /make-pdf, /diagram, or /design-html for that. On the fallback path, `/setup-browser-cookies` asks the user to choose the source -browser and account/profile; Dia is macOS-only. Navigate to the matching target -before a direct `--domain` import. Cookies copied is **not checked**, not proof +browser and account/profile. Navigate to the matching target before a direct `--domain` import. Cookies copied is **not checked**, not proof of login. `--verify-auth` requires a daemon-configured exact visible identity assertion; HTTP 200 and cookie counts are not enough. Storage stays intact unless the user explicitly approves `--clear-storage` for the captured origin on a Chromium target. Other engines reject reset, not ordinary import or auth checks. Do not diff --git a/browse/SKILL.md.tmpl b/browse/SKILL.md.tmpl index 009a153f0..0655b388a 100644 --- a/browse/SKILL.md.tmpl +++ b/browse/SKILL.md.tmpl @@ -112,8 +112,7 @@ HTML into a PNG or PDF is the render engine's job: use /make-pdf, /diagram, or /design-html for that. On the fallback path, `/setup-browser-cookies` asks the user to choose the source -browser and account/profile; Dia is macOS-only. Navigate to the matching target -before a direct `--domain` import. Cookies copied is **not checked**, not proof +browser and account/profile. Navigate to the matching target before a direct `--domain` import. Cookies copied is **not checked**, not proof of login. `--verify-auth` requires a daemon-configured exact visible identity assertion; HTTP 200 and cookie counts are not enough. Storage stays intact unless the user explicitly approves `--clear-storage` for the captured origin on a Chromium target. Other engines reject reset, not ordinary import or auth checks. Do not diff --git a/browse/sections/command-list.md b/browse/sections/command-list.md index be87f64d9..94b7f8ac2 100644 --- a/browse/sections/command-list.md +++ b/browse/sections/command-list.md @@ -94,7 +94,7 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`. | `click ` | Click element | | `cookie =` | Set cookie on current page domain | | `cookie-import ` | Import cookies from JSON file | -| `cookie-import-browser [browser] [--domain d] [--profile p] [--all] [--clear-storage] [--verify-auth]` | Copy cookies from chrome, chromium, brave, edge, Windows-only opera, opera-gx, or macOS-only comet, arc, dia. Omitted browser retains legacy comet; select the intended browser explicitly. --domain requires a matching current page; no scope flag opens the picker. --profile is the source directory; ambiguous profiles require selection. --all explicitly selects every non-expired cookie and cannot accompany --domain or --clear-storage. Storage is preserved unless --clear-storage resets captured-origin localStorage (shared across context tabs) and target-tab sessionStorage. --verify-auth requires daemon GSTACK_COOKIE_AUTH_SELECTOR and GSTACK_COOKIE_AUTH_EXPECTED_IDENTITY before startup; missing config rejects before mutation. Verified means an exact visible identity match, not cookie counts or HTTP 200. Windows native extraction remains disabled pending qualification. | +| `cookie-import-browser [browser] [--domain d] [--profile p] [--all] [--clear-storage] [--verify-auth]` | Copy cookies from chrome, chromium, brave, edge, Windows-only opera, opera-gx, or macOS-only comet or arc. Omitted browser retains legacy comet; select the intended browser explicitly. --domain requires a matching current page; no scope flag opens the picker. --profile is the source directory; ambiguous profiles require selection. --all explicitly selects every non-expired cookie and cannot accompany --domain or --clear-storage. Storage is preserved unless --clear-storage resets captured-origin localStorage (shared across context tabs) and target-tab sessionStorage. --verify-auth requires daemon GSTACK_COOKIE_AUTH_SELECTOR and GSTACK_COOKIE_AUTH_EXPECTED_IDENTITY before startup; missing config rejects before mutation. Verified means an exact visible identity match, not cookie counts or HTTP 200. Windows native extraction remains disabled pending qualification. | | `dialog-accept [text]` | Auto-accept next alert/confirm/prompt. Optional text is sent as the prompt response | | `dialog-dismiss` | Auto-dismiss next dialog | | `fill ` | Fill input | diff --git a/browse/src/commands.ts b/browse/src/commands.ts index 433561efd..2d2a26015 100644 --- a/browse/src/commands.ts +++ b/browse/src/commands.ts @@ -130,7 +130,7 @@ export const COMMAND_DESCRIPTIONS: Record|auto] [--scale ]' }, 'cookie': { category: 'Interaction', description: 'Set cookie on current page domain', usage: 'cookie =' }, 'cookie-import': { category: 'Interaction', description: 'Import cookies from JSON file', usage: 'cookie-import ' }, - 'cookie-import-browser': { category: 'Interaction', description: 'Copy cookies from chrome, chromium, brave, edge, Windows-only opera, opera-gx, or macOS-only comet, arc, dia. Omitted browser retains legacy comet; select the intended browser explicitly. --domain requires a matching current page; no scope flag opens the picker. --profile is the source directory; ambiguous profiles require selection. --all explicitly selects every non-expired cookie and cannot accompany --domain or --clear-storage. Storage is preserved unless --clear-storage resets captured-origin localStorage (shared across context tabs) and target-tab sessionStorage. --verify-auth requires daemon GSTACK_COOKIE_AUTH_SELECTOR and GSTACK_COOKIE_AUTH_EXPECTED_IDENTITY before startup; missing config rejects before mutation. Verified means an exact visible identity match, not cookie counts or HTTP 200. Windows native extraction remains disabled pending qualification.', usage: 'cookie-import-browser [browser] [--domain d] [--profile p] [--all] [--clear-storage] [--verify-auth]' }, + 'cookie-import-browser': { category: 'Interaction', description: 'Copy cookies from chrome, chromium, brave, edge, Windows-only opera, opera-gx, or macOS-only comet or arc. Omitted browser retains legacy comet; select the intended browser explicitly. --domain requires a matching current page; no scope flag opens the picker. --profile is the source directory; ambiguous profiles require selection. --all explicitly selects every non-expired cookie and cannot accompany --domain or --clear-storage. Storage is preserved unless --clear-storage resets captured-origin localStorage (shared across context tabs) and target-tab sessionStorage. --verify-auth requires daemon GSTACK_COOKIE_AUTH_SELECTOR and GSTACK_COOKIE_AUTH_EXPECTED_IDENTITY before startup; missing config rejects before mutation. Verified means an exact visible identity match, not cookie counts or HTTP 200. Windows native extraction remains disabled pending qualification.', usage: 'cookie-import-browser [browser] [--domain d] [--profile p] [--all] [--clear-storage] [--verify-auth]' }, 'header': { category: 'Interaction', description: 'Set custom request header (colon-separated, sensitive values auto-redacted)', usage: 'header :' }, 'useragent': { category: 'Interaction', description: 'Set user agent', usage: 'useragent ' }, 'dialog-accept': { category: 'Interaction', description: 'Auto-accept next alert/confirm/prompt. Optional text is sent as the prompt response', usage: 'dialog-accept [text]' }, diff --git a/browse/src/config.ts b/browse/src/config.ts index 89cd21418..17f29dd82 100644 --- a/browse/src/config.ts +++ b/browse/src/config.ts @@ -100,6 +100,21 @@ function isIgnoredByGit(projectDir: string, relPath: string): boolean { } } +function gitExcludePath(projectDir: string): string | null { + try { + const proc = Bun.spawnSync(['git', 'rev-parse', '--git-path', 'info/exclude'], { + windowsHide: true, + cwd: projectDir, stdout: 'pipe', stderr: 'pipe', + timeout: 2_000, + }); + if (proc.exitCode !== 0) return null; + const rel = proc.stdout.toString().trim(); + return rel ? path.resolve(projectDir, rel) : null; + } catch { + return null; + } +} + /** * Create the .gstack/ state directory if it doesn't exist. * Throws with a clear message on permission errors. @@ -119,40 +134,36 @@ export function ensureStateDir(config: BrowseConfig): void { // Load-bearing guard: a self-contained ignore INSIDE the state dir so its // contents can NEVER be `git add`-ed, regardless of the project's own - // .gitignore (which may be absent, or the append below may silently fail). - // The state dir holds session-state.json (live cookies + localStorage/ - // sessionStorage tokens) and browse-network.log / browse-audit.jsonl - // (captured request headers can carry bearer tokens). Written unconditionally, - // synchronously, before return — the project-.gitignore dance below is now - // redundant safety, kept so `.gstack/` still reads as ignored in git status. + // ignore rules. The state dir holds session-state.json (live cookies + + // localStorage/sessionStorage tokens) and browse-network.log / + // browse-audit.jsonl (captured request headers can carry bearer tokens). + // Written unconditionally, synchronously, before return. try { fs.writeFileSync(path.join(config.stateDir, '.gitignore'), '*\n'); } catch { - // Best-effort; the project-.gitignore path below is the fallback. + // Best-effort; the repository's info/exclude below is the fallback. } - // Ensure .gstack/ is in the project's .gitignore - // First, check if git already ignores .gstack/ (via global excludes, .git/info/exclude, or parent .gitignore) + // Ensure git reads .gstack/ as ignored through the repository's own + // info/exclude, never the project's .gitignore: that file is tracked, and + // editing it mid-/ship changes the tree after pregate (PREGATE_STALE, #3560). if (isIgnoredByGit(config.projectDir, '.gstack/')) return; - - const gitignorePath = path.join(config.projectDir, '.gitignore'); + const excludePath = gitExcludePath(config.projectDir); + if (!excludePath) return; try { - const content = fs.readFileSync(gitignorePath, 'utf-8'); + const content = fs.existsSync(excludePath) ? fs.readFileSync(excludePath, 'utf-8') : ''; if (!content.match(/^\.gstack\/?$/m)) { - const separator = content.endsWith('\n') ? '' : '\n'; - fs.appendFileSync(gitignorePath, `${separator}.gstack/\n`); + const separator = content === '' || content.endsWith('\n') ? '' : '\n'; + fs.mkdirSync(path.dirname(excludePath), { recursive: true }); + fs.appendFileSync(excludePath, `${separator}.gstack/\n`); } } catch (err: any) { - if (err.code !== 'ENOENT') { - // Write warning to server log (visible even in daemon mode) - const logPath = path.join(config.stateDir, 'browse-server.log'); - try { - fs.appendFileSync(logPath, `[${new Date().toISOString()}] Warning: could not update .gitignore at ${gitignorePath}: ${err.message}\n`); - } catch { - // stateDir write failed too — nothing more we can do - } + const logPath = path.join(config.stateDir, 'browse-server.log'); + try { + fs.appendFileSync(logPath, `[${new Date().toISOString()}] Warning: could not update ${excludePath}: ${err.message}\n`); + } catch { + // stateDir write failed too — nothing more we can do } - // ENOENT (no .gitignore) — skip silently } } diff --git a/browse/src/cookie-import-browser.ts b/browse/src/cookie-import-browser.ts index 86de21b20..52aaa6396 100644 --- a/browse/src/cookie-import-browser.ts +++ b/browse/src/cookie-import-browser.ts @@ -118,7 +118,6 @@ const BROWSER_REGISTRY: BrowserInfo[] = [ { name: 'Chrome', dataDir: 'Google/Chrome/', keychainService: 'Chrome Safe Storage', aliases: ['chrome', 'google-chrome', 'google-chrome-stable'], linuxDataDir: 'google-chrome/', linuxApplication: 'chrome', windowsDataDir: 'Google/Chrome/User Data/', windowsNative: true }, { name: 'Chromium', dataDir: 'chromium/', keychainService: 'Chromium Safe Storage', aliases: ['chromium'], linuxDataDir: 'chromium/', linuxApplication: 'chromium', windowsDataDir: 'Chromium/User Data/', windowsNative: true }, { name: 'Arc', dataDir: 'Arc/User Data/', keychainService: 'Arc Safe Storage', aliases: ['arc'] }, - { name: 'Dia', dataDir: 'Dia/User Data/', keychainService: 'Dia Safe Storage', aliases: ['dia'] }, { name: 'Brave', dataDir: 'BraveSoftware/Brave-Browser/', keychainService: 'Brave Safe Storage', aliases: ['brave'], linuxDataDir: 'BraveSoftware/Brave-Browser/', linuxApplication: 'brave', windowsDataDir: 'BraveSoftware/Brave-Browser/User Data/', windowsNative: true }, { name: 'Edge', dataDir: 'Microsoft Edge/', keychainService: 'Microsoft Edge Safe Storage', aliases: ['edge'], linuxDataDir: 'microsoft-edge/', linuxApplication: 'microsoft-edge', windowsDataDir: 'Microsoft/Edge/User Data/', windowsNative: true }, // Windows-only. Local State sits directly under the browser root in %APPDATA% — no User Data segment. diff --git a/browse/src/terminal-agent-control.ts b/browse/src/terminal-agent-control.ts index bda034539..2c364e1de 100644 --- a/browse/src/terminal-agent-control.ts +++ b/browse/src/terminal-agent-control.ts @@ -24,9 +24,10 @@ import { atomicWriteSync } from '../../lib/fs-atomic'; import { readPidCmdline, readPidStartTime } from './xvfb'; import { emptyBunConfig, findWindowsBunExe, type BunExeLookup } from './bun-child-config'; -function agentProcessInfo(pid: number): { startTime: string; commandLine: string } { - if (!Number.isSafeInteger(pid) || pid <= 0) return { startTime: '', commandLine: '' }; - if (process.platform !== 'win32') return { startTime: readPidStartTime(pid), commandLine: readPidCmdline(pid) }; +const FILETIME_UNIX_EPOCH_MS = 11_644_473_600_000n; +let win32Kernel: any; + +function windowsProcessQuery(pid: number): { startTime: string; commandLine: string } { const script = `(Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}' | Select-Object CreationDate,CommandLine | ConvertTo-Json -Compress)`; try { const result = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { encoding: 'utf8', windowsHide: true, timeout: 2000 }); @@ -36,8 +37,40 @@ function agentProcessInfo(pid: number): { startTime: string; commandLine: string } catch { return { startTime: '', commandLine: '' }; } } +export const win32CreationTimeSource = { + read(pid: number): string | undefined { + if (!process.versions.bun) return; + try { + const { dlopen, FFIType, ptr } = require('bun:ffi'); + win32Kernel ??= dlopen('kernel32.dll', { + OpenProcess: { args: [FFIType.u32, FFIType.i32, FFIType.u32], returns: FFIType.u64 }, + GetProcessTimes: { args: [FFIType.u64, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 }, + CloseHandle: { args: [FFIType.u64], returns: FFIType.i32 }, + }).symbols; + const handle = win32Kernel.OpenProcess(0x1000, 0, pid); + if (!handle) return; + try { + const times = new BigUint64Array(4); + if (!win32Kernel.GetProcessTimes(handle, ptr(times, 0), ptr(times, 8), ptr(times, 16), ptr(times, 24)) || times[0] === 0n) return; + return `/Date(${times[0] / 10_000n - FILETIME_UNIX_EPOCH_MS})/`; + } finally { + win32Kernel.CloseHandle(handle); + } + } catch { return; } + }, +}; + +function agentProcessInfo(pid: number): { startTime: string; commandLine: string } { + if (!Number.isSafeInteger(pid) || pid <= 0) return { startTime: '', commandLine: '' }; + if (process.platform !== 'win32') return { startTime: readPidStartTime(pid), commandLine: readPidCmdline(pid) }; + const query = windowsProcessQuery(pid); + return { startTime: win32CreationTimeSource.read(pid) ?? query.startTime, commandLine: query.commandLine }; +} + export function readAgentStartTime(pid: number): string { - return agentProcessInfo(pid).startTime; + if (!Number.isSafeInteger(pid) || pid <= 0) return ''; + if (process.platform !== 'win32') return readPidStartTime(pid); + return win32CreationTimeSource.read(pid) ?? windowsProcessQuery(pid).startTime; } const pendingAgentExits = new Set(); @@ -335,7 +368,8 @@ function agentStatus(record: AgentRecord, ownerPid?: number): 'owned' | 'gone' | if (ownerPid !== undefined && (record.ownerPid !== ownerPid || record.ownerStartTime !== readAgentStartTime(ownerPid))) return 'unknown'; const actual = agentProcessInfo(record.pid); if (!actual.startTime) return isAgentRecordLive(record) ? 'unknown' : 'gone'; - if (actual.startTime !== record.startTime) return 'gone'; + if (actual.startTime !== record.startTime && process.platform !== 'win32') return 'gone'; + if (actual.startTime !== record.startTime && !actual.commandLine) return 'unknown'; try { let state: string | undefined; if (process.platform === 'linux') { @@ -348,7 +382,7 @@ function agentStatus(record: AgentRecord, ownerPid?: number): 'owned' | 'gone' | } catch {} if (!isAgentRecordLive(record)) return 'gone'; return actual.commandLine.split(/\s+/).some(arg => arg.replace(/^['"]|['"]$/g, '') === `--agent-gen=${record.gen}`) - ? 'owned' : 'unknown'; + ? 'owned' : actual.startTime === record.startTime ? 'unknown' : 'gone'; } export function isOurAgent(record: AgentRecord, ownerPid?: number): boolean { diff --git a/browse/test/config.test.ts b/browse/test/config.test.ts index 53a2081a6..f93a802cf 100644 --- a/browse/test/config.test.ts +++ b/browse/test/config.test.ts @@ -95,68 +95,72 @@ describe('config', () => { fs.rmSync(tmpDir, { recursive: true, force: true }); }); - test('adds .gstack/ to .gitignore if not present', () => { - const tmpDir = path.join(os.tmpdir(), `browse-gitignore-test-${Date.now()}`); - fs.mkdirSync(tmpDir, { recursive: true }); - fs.writeFileSync(path.join(tmpDir, '.gitignore'), 'node_modules/\n'); + // A repository that tracks files under .gstack/ (pregate.json, ship-policy.json) is the case + // where git does not already read .gstack/ as ignored, so the ignore line must land somewhere. + const trackedGstackRepo = (prefix: string) => { + const { spawnSync } = require('child_process'); + const tmpDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix))); + const git = (...args: string[]) => spawnSync('git', args, { cwd: tmpDir, timeout: 30_000, encoding: 'utf-8' }); + git('init', '-q'); + fs.writeFileSync(path.join(tmpDir, '.gitignore'), 'node_modules/\n.gstack/tmp/\n'); + fs.mkdirSync(path.join(tmpDir, '.gstack')); + fs.writeFileSync(path.join(tmpDir, '.gstack', 'pregate.json'), '{}\n'); + git('add', '-A'); + git('-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-qm', 'init'); + const exclude = path.resolve(tmpDir, git('rev-parse', '--git-path', 'info/exclude').stdout.trim()); + return { tmpDir, git, exclude }; + }; + + test('records .gstack/ in .git/info/exclude and leaves the tracked .gitignore unchanged (#3560)', () => { + const { tmpDir, git, exclude } = trackedGstackRepo('browse-exclude-test-'); + fs.writeFileSync(exclude, '# local\n'); const config = resolveConfig({ BROWSE_STATE_FILE: path.join(tmpDir, '.gstack', 'browse.json') }); ensureStateDir(config); - const content = fs.readFileSync(path.join(tmpDir, '.gitignore'), 'utf-8'); - expect(content).toContain('.gstack/'); - expect(content).toBe('node_modules/\n.gstack/\n'); + expect(fs.readFileSync(path.join(tmpDir, '.gitignore'), 'utf-8')).toBe('node_modules/\n.gstack/tmp/\n'); + expect(fs.readFileSync(exclude, 'utf-8')).toBe('# local\n.gstack/\n'); + expect(git('status', '--porcelain').stdout).toBe(''); fs.rmSync(tmpDir, { recursive: true, force: true }); }); - test('does not duplicate .gstack/ in .gitignore', () => { - const tmpDir = path.join(os.tmpdir(), `browse-gitignore-test-${Date.now()}`); - fs.mkdirSync(tmpDir, { recursive: true }); - fs.writeFileSync(path.join(tmpDir, '.gitignore'), 'node_modules/\n.gstack/\n'); - const config = resolveConfig({ BROWSE_STATE_FILE: path.join(tmpDir, '.gstack', 'browse.json') }); + test('does not duplicate .gstack/ in info/exclude, adds a missing trailing newline, and creates info/ when absent', () => { + const dup = trackedGstackRepo('browse-exclude-dup-'); + fs.writeFileSync(dup.exclude, 'build/'); + const config = resolveConfig({ BROWSE_STATE_FILE: path.join(dup.tmpDir, '.gstack', 'browse.json') }); ensureStateDir(config); - const content = fs.readFileSync(path.join(tmpDir, '.gitignore'), 'utf-8'); - expect(content).toBe('node_modules/\n.gstack/\n'); - fs.rmSync(tmpDir, { recursive: true, force: true }); + ensureStateDir(config); + expect(fs.readFileSync(dup.exclude, 'utf-8')).toBe('build/\n.gstack/\n'); + fs.rmSync(dup.tmpDir, { recursive: true, force: true }); + + const bare = trackedGstackRepo('browse-exclude-noinfo-'); + fs.rmSync(path.dirname(bare.exclude), { recursive: true, force: true }); + ensureStateDir(resolveConfig({ BROWSE_STATE_FILE: path.join(bare.tmpDir, '.gstack', 'browse.json') })); + expect(fs.readFileSync(bare.exclude, 'utf-8')).toBe('.gstack/\n'); + fs.rmSync(bare.tmpDir, { recursive: true, force: true }); }); - test('handles .gitignore without trailing newline', () => { - const tmpDir = path.join(os.tmpdir(), `browse-gitignore-test-${Date.now()}`); - fs.mkdirSync(tmpDir, { recursive: true }); - fs.writeFileSync(path.join(tmpDir, '.gitignore'), 'node_modules'); - const config = resolveConfig({ BROWSE_STATE_FILE: path.join(tmpDir, '.gstack', 'browse.json') }); - ensureStateDir(config); - const content = fs.readFileSync(path.join(tmpDir, '.gitignore'), 'utf-8'); - expect(content).toBe('node_modules\n.gstack/\n'); - fs.rmSync(tmpDir, { recursive: true, force: true }); - }); - - test('logs warning to browse-server.log on non-ENOENT gitignore error', () => { + test('logs warning to browse-server.log when info/exclude cannot be written', () => { if (!canRevokeWrites()) return; // chmod is advisory here (win32, root, DAC-override containers) - const tmpDir = path.join(os.tmpdir(), `browse-gitignore-test-${Date.now()}`); - fs.mkdirSync(tmpDir, { recursive: true }); - // Create a read-only .gitignore (no .gstack/ entry → would try to append) - fs.writeFileSync(path.join(tmpDir, '.gitignore'), 'node_modules/\n'); - fs.chmodSync(path.join(tmpDir, '.gitignore'), 0o444); + const { tmpDir, exclude } = trackedGstackRepo('browse-exclude-ro-'); + fs.writeFileSync(exclude, '# local\n'); + fs.chmodSync(exclude, 0o444); const config = resolveConfig({ BROWSE_STATE_FILE: path.join(tmpDir, '.gstack', 'browse.json') }); ensureStateDir(config); // should not throw - // Verify warning was written to server log - const logPath = path.join(config.stateDir, 'browse-server.log'); - expect(fs.existsSync(logPath)).toBe(true); - const logContent = fs.readFileSync(logPath, 'utf-8'); - expect(logContent).toContain('Warning: could not update .gitignore'); - // .gitignore should remain unchanged - const gitignoreContent = fs.readFileSync(path.join(tmpDir, '.gitignore'), 'utf-8'); - expect(gitignoreContent).toBe('node_modules/\n'); - // Cleanup - fs.chmodSync(path.join(tmpDir, '.gitignore'), 0o644); + const logContent = fs.readFileSync(path.join(config.stateDir, 'browse-server.log'), 'utf-8'); + expect(logContent).toContain(`Warning: could not update ${exclude}`); + expect(fs.readFileSync(exclude, 'utf-8')).toBe('# local\n'); + expect(fs.readFileSync(path.join(tmpDir, '.gitignore'), 'utf-8')).toBe('node_modules/\n.gstack/tmp/\n'); + fs.chmodSync(exclude, 0o644); fs.rmSync(tmpDir, { recursive: true, force: true }); }); - test('skips if no .gitignore exists', () => { + test('outside a git repository nothing is written beyond the state dir', () => { const tmpDir = path.join(os.tmpdir(), `browse-gitignore-test-${Date.now()}`); fs.mkdirSync(tmpDir, { recursive: true }); + fs.writeFileSync(path.join(tmpDir, '.gitignore'), 'node_modules/\n'); const config = resolveConfig({ BROWSE_STATE_FILE: path.join(tmpDir, '.gstack', 'browse.json') }); ensureStateDir(config); - expect(fs.existsSync(path.join(tmpDir, '.gitignore'))).toBe(false); + expect(fs.readFileSync(path.join(tmpDir, '.gitignore'), 'utf-8')).toBe('node_modules/\n'); + expect(fs.readdirSync(tmpDir).sort()).toEqual(['.gitignore', '.gstack']); fs.rmSync(tmpDir, { recursive: true, force: true }); }); diff --git a/browse/test/cookie-auth-verification.test.ts b/browse/test/cookie-auth-verification.test.ts index 742c1c2c7..4e073cfcc 100644 --- a/browse/test/cookie-auth-verification.test.ts +++ b/browse/test/cookie-auth-verification.test.ts @@ -423,6 +423,7 @@ describe('cookie auth configuration and bounded operations', () => { }); describe('cookie authentication and storage with isolated Chromium profiles', () => { + const browserOptions = { identitySelector: options.identitySelector, expectedIdentity: options.expectedIdentity }; let browser: Browser; let context: BrowserContext; let page: Page; @@ -486,13 +487,13 @@ describe('cookie authentication and storage with isolated Chromium profiles', () test('verifies a reloaded protected page only with an exact visible identity and synthetic session', async () => { await context.addCookies([{ name: 'fixture_session', value: 'approved', url: origin }]); await page.goto(`${origin}/protected`); - expect(await verifyCookieAuthentication(page, options, origin)).toEqual({ verified: true, reason: 'verified', status: 200 }); + expect(await verifyCookieAuthentication(page, browserOptions, origin)).toEqual({ verified: true, reason: 'verified', status: 200 }); }); for (const path of ['/normalized', '/one-visible', '/hidden-child', '/delayed']) { test(`accepts one normalized visible identity at ${path}`, async () => { await page.goto(`${origin}${path}`); - const result = await verifyCookieAuthentication(page, { ...options, expectedIdentity: ` \n${identity} `, timeoutMs: 1000 }, origin); + const result = await verifyCookieAuthentication(page, { ...browserOptions, expectedIdentity: ` \n${identity} `, timeoutMs: 1000 }, origin); expect(result).toEqual({ verified: true, reason: 'verified', status: 200 }); expect(JSON.stringify(result)).not.toContain(identity); }); @@ -506,7 +507,8 @@ describe('cookie authentication and storage with isolated Chromium profiles', () test(`rejects ${path} with a safe ${reason} result`, async () => { await page.goto(`${origin}${path === '/login-hop' ? '/identity' : path}`); if (path === '/login-hop') await page.evaluate(() => history.replaceState({}, '', '/login-hop')); - const result = await verifyCookieAuthentication(page, options, origin); + // identity_mismatch/missing/ambiguous keep the 400 ms options (GStack Minder, 2026-10-28): they resolve only when the deadline fires (browse/src/cookie-auth-verification.ts:105-120), so the 15 s default would exceed bun's 5 s test timeout. + const result = await verifyCookieAuthentication(page, reason.startsWith('identity_') ? options : browserOptions, origin); expect(result.verified).toBe(false); expect(result.reason).toBe(reason); expect(JSON.stringify(result)).not.toMatch(/Synthetic Account|127\.0\.0\.1/); @@ -517,13 +519,13 @@ describe('cookie authentication and storage with isolated Chromium profiles', () await context.addCookies([{ name: 'fixture_session', value: 'approved', url: origin }]); await page.goto(`${origin}/protected`); await context.clearCookies(); - expect((await verifyCookieAuthentication(page, options, origin)).reason).toBe('login_redirect'); + expect((await verifyCookieAuthentication(page, browserOptions, origin)).reason).toBe('login_redirect'); }); for (const status of [401, 403, 500, 503]) { test(`rejects HTTP ${status} even with a positive identity`, async () => { await page.goto(`${origin}/status/${status}`); - expect(await verifyCookieAuthentication(page, options, origin)).toEqual({ verified: false, reason: 'http_error', status }); + expect(await verifyCookieAuthentication(page, browserOptions, origin)).toEqual({ verified: false, reason: 'http_error', status }); }); } @@ -531,7 +533,7 @@ describe('cookie authentication and storage with isolated Chromium profiles', () for (const destination of ['/redirect-cross', '/roundtrip']) { await page.goto(`${origin}/identity`); await page.evaluate(path => history.replaceState({}, '', path), destination); - expect((await verifyCookieAuthentication(page, options, origin)).reason).toBe('target_changed'); + expect((await verifyCookieAuthentication(page, browserOptions, origin)).reason).toBe('target_changed'); } }); @@ -553,7 +555,7 @@ describe('cookie authentication and storage with isolated Chromium profiles', () return value; }); try { - expect((await verifyCookieAuthentication(page, options, origin)).reason).toBe('target_changed'); + expect((await verifyCookieAuthentication(page, browserOptions, origin)).reason).toBe('target_changed'); } finally { locator.mockRestore(); } @@ -563,7 +565,7 @@ describe('cookie authentication and storage with isolated Chromium profiles', () await page.goto(`${origin}/identity`); await page.evaluate(() => history.replaceState({}, '', '/slow')); try { - expect(await verifyCookieAuthentication(page, { ...options, timeoutMs: 100 }, origin)) + expect(await verifyCookieAuthentication(page, { ...browserOptions, timeoutMs: 100 }, origin)) .toEqual({ verified: false, reason: 'timeout' }); } finally { releaseSlowResponse?.(); @@ -572,11 +574,11 @@ describe('cookie authentication and storage with isolated Chromium profiles', () test('sanitizes invalid selector errors and handles a closed target', async () => { await page.goto(`${origin}/identity`); - const result = await verifyCookieAuthentication(page, { ...options, identitySelector: '[synthetic-token' }, origin); + const result = await verifyCookieAuthentication(page, { ...browserOptions, identitySelector: '[synthetic-token' }, origin); expect(result.reason).toBe('verification_failed'); expect(JSON.stringify(result)).not.toContain('synthetic-token'); await page.close(); - expect((await verifyCookieAuthentication(page, options, origin)).reason).toBe('target_closed'); + expect((await verifyCookieAuthentication(page, browserOptions, origin)).reason).toBe('target_closed'); expect(await clearCookieTargetStorage(page, origin).then(() => null, error => error)).toMatchObject({ code: 'target_closed' }); }); @@ -586,7 +588,7 @@ describe('cookie authentication and storage with isolated Chromium profiles', () localStorage.setItem('local', 'original'); sessionStorage.setItem('session', 'original'); }); - expect((await verifyCookieAuthentication(page, options, origin)).verified).toBe(true); + expect((await verifyCookieAuthentication(page, browserOptions, origin)).verified).toBe(true); expect(await page.evaluate(() => [localStorage.getItem('local'), sessionStorage.getItem('session')])) .toEqual(['original', 'original']); }); diff --git a/browse/test/cookie-credential-deadline.test.ts b/browse/test/cookie-credential-deadline.test.ts index c5c76f091..6e9a3987f 100644 --- a/browse/test/cookie-credential-deadline.test.ts +++ b/browse/test/cookie-credential-deadline.test.ts @@ -14,7 +14,7 @@ let platform: PropertyDescriptor; let spawn: typeof Bun.spawn; function fixture(encrypted: Buffer, hostPlatform: 'darwin' | 'linux' | 'win32' = 'darwin') { - const folder = hostPlatform === 'darwin' ? 'Library/Application Support/Dia/User Data/Default' + const folder = hostPlatform === 'darwin' ? 'Library/Application Support/Arc/User Data/Default' : hostPlatform === 'linux' ? '.config/chromium/Default' : 'AppData/Local/Chromium/User Data/Default'; const dir = path.join(home, folder); fs.mkdirSync(dir, { recursive: true }); @@ -72,7 +72,7 @@ describe('credential subprocess whole-operation deadline', () => { let expire: (() => void) | undefined; const timer = spyOn(globalThis, 'setTimeout').mockImplementation((callback: any) => { expire = callback; return 19 as any; }); try { - const result = importCookies('dia', ['fixture.test']); + const result = importCookies('arc', ['fixture.test']); expect(expire).toBeFunction(); expire!(); await expect(result).rejects.toMatchObject({ code: 'keychain_timeout', action: 'retry' }); @@ -94,7 +94,7 @@ describe('credential subprocess whole-operation deadline', () => { let expire: (() => void) | undefined; const timer = spyOn(globalThis, 'setTimeout').mockImplementation((callback: any) => { expire = callback; return 20 as any; }); try { - const result = importCookies('dia', ['fixture.test']); + const result = importCookies('arc', ['fixture.test']); expect(expire).toBeFunction(); expire!(); await expect(result).rejects.toMatchObject({ code: 'keychain_timeout' }); @@ -114,7 +114,7 @@ describe('credential subprocess whole-operation deadline', () => { Bun.spawn = (() => ({ exited: Promise.resolve(0), stdout: new Blob([privateValue.repeat(4_000)]).stream(), stderr: new Blob([]).stream(), kill() { killed++; } })) as typeof Bun.spawn; let error: any; - try { await importCookies('dia', ['fixture.test']); } catch (caught) { error = caught; } + try { await importCookies('arc', ['fixture.test']); } catch (caught) { error = caught; } expect(error).toBeInstanceOf(CookieImportError); expect(error.code).toBe('keychain_error'); expect(error.message).not.toContain(privateValue); @@ -127,8 +127,8 @@ describe('credential subprocess whole-operation deadline', () => { for (const [code, stderr, expected] of [[0, '', 'fixture-value'], [1, 'user canceled private-detail', 'keychain_denied'], [1, 'could not be found private-detail', 'keychain_not_found']] as const) { Bun.spawn = (() => ({ exited: Promise.resolve(code), stdout: new Blob([code ? '' : 'fixture-password\n']).stream(), stderr: new Blob([stderr]).stream(), kill() { throw new Error('Unexpected kill'); } })) as typeof Bun.spawn; - if (!code) expect((await importCookies('dia', ['fixture.test'])).cookies[0].value).toBe(expected); - else await expect(importCookies('dia', ['fixture.test'])).rejects.toMatchObject({ code: expected }); + if (!code) expect((await importCookies('arc', ['fixture.test'])).cookies[0].value).toBe(expected); + else await expect(importCookies('arc', ['fixture.test'])).rejects.toMatchObject({ code: expected }); } }); @@ -198,7 +198,7 @@ describe('credential subprocess whole-operation deadline', () => { const polyfill = path.resolve(import.meta.dir, '../src/bun-polyfill.cjs'); const nodeFixture = path.join(home, 'node-fixture'); fs.mkdirSync(nodeFixture); - const dir = path.join(nodeFixture, 'Library/Application Support/Dia/User Data/Default'); + const dir = path.join(nodeFixture, 'Library/Application Support/Arc/User Data/Default'); fs.mkdirSync(dir, { recursive: true }); expect(fs.realpathSync(dir).startsWith(fs.realpathSync(nodeFixture) + path.sep)).toBe(true); const db = new Database(path.join(dir, 'Cookies')); @@ -213,7 +213,7 @@ describe('credential subprocess whole-operation deadline', () => { Bun.spawn = (_command, options) => original([process.execPath, '-e', 'console.log("fixture-node-password")'], options); Object.defineProperty(process, 'platform', { value: 'darwin' }); const { importCookies } = await import(process.argv[2]); - const result = await importCookies('dia', ['fixture.test']); + const result = await importCookies('arc', ['fixture.test']); console.log(JSON.stringify({ count: result.count, value: result.cookies[0]?.value })); `, polyfill, pathToFileURL(bundle).href], { encoding: 'utf8', timeout: 15_000, env: { ...process.env, HOME: nodeFixture, USERPROFILE: nodeFixture, NODE_NO_WARNINGS: '1' } }); diff --git a/browse/test/cookie-import-native-job.test.ts b/browse/test/cookie-import-native-job.test.ts index 6b0431008..44b068d52 100644 --- a/browse/test/cookie-import-native-job.test.ts +++ b/browse/test/cookie-import-native-job.test.ts @@ -999,9 +999,9 @@ function safeNativeEnvelope(output: string): object { function assertOwnerReceipt(receipt: { available: boolean; owners: { pid: number; creationMatched: boolean; isTestHost: boolean }[] }, pid: number) { const before = JSON.stringify(receipt); - expect(receipt.available).toBe(true); - expect(Array.isArray(receipt.owners)).toBe(true); - expect(receipt.owners.some(owner => owner.pid === pid && owner.creationMatched && owner.isTestHost)).toBe(true); + expect(receipt.available, before).toBe(true); + expect(Array.isArray(receipt.owners), before).toBe(true); + expect(receipt.owners.some(owner => owner.pid === pid && owner.creationMatched && owner.isTestHost), before).toBe(true); expect(JSON.stringify(receipt)).toBe(before); } diff --git a/browse/test/cookie-import-native.test.ts b/browse/test/cookie-import-native.test.ts index 400789e9a..8c6b372c7 100644 --- a/browse/test/cookie-import-native.test.ts +++ b/browse/test/cookie-import-native.test.ts @@ -149,7 +149,7 @@ describe('native-cookie production admission', () => { }); test('does not substitute a different browser for an unsupported identity', () => { - expect(adapter({ ...options, browserName: 'Dia' })).toMatchObject({ code: 'not_supported', typed: true }); + expect(adapter({ ...options, browserName: 'Arc' })).toMatchObject({ code: 'not_supported', typed: true }); }); test('rejects mismatched and copied profile roots', () => { diff --git a/browse/test/cookie-import-reliability.test.ts b/browse/test/cookie-import-reliability.test.ts index c6ea6ced3..6a029acf1 100644 --- a/browse/test/cookie-import-reliability.test.ts +++ b/browse/test/cookie-import-reliability.test.ts @@ -108,10 +108,10 @@ afterEach(() => { }); describe('cookie import reliability', () => { - test('discovers Dia with only a numbered macOS profile', () => { - profile('Library/Application Support/Dia/User Data', 'Profile 2'); - expect(findInstalledBrowsers().map(browser => browser.name)).toContain('Dia'); - expect(listProfiles('dia')[0].name).toBe('Profile 2'); + test('discovers Arc with only a numbered macOS profile', () => { + profile('Library/Application Support/Arc/User Data', 'Profile 2'); + expect(findInstalledBrowsers().map(browser => browser.name)).toContain('Arc'); + expect(listProfiles('arc')[0].name).toBe('Profile 2'); }); test('prefers current Local State names and sorts profile numbers naturally', () => { @@ -213,13 +213,13 @@ describe('cookie import reliability', () => { }); test('actual Keychain denial is sanitized, never repeated, and clears its deadline', async () => { - const dir = profile('Library/Application Support/Dia/User Data', 'Default'); + const dir = profile('Library/Application Support/Arc/User Data', 'Default'); const db = new Database(path.join(dir, 'Cookies')); db.run("UPDATE cookies SET value = '', encrypted_value = ?", [Buffer.from('v10synthetic-encrypted-row')]); db.close(); let requests = 0; Bun.spawn = ((command: string[]) => { - expect(command).toEqual(['security', 'find-generic-password', '-s', 'Dia Safe Storage', '-w']); + expect(command).toEqual(['security', 'find-generic-password', '-s', 'Arc Safe Storage', '-w']); requests++; return { stdout: new Blob([]).stream(), stderr: new Blob(['user canceled synthetic-private-detail']).stream(), exited: Promise.resolve(1), kill() {} }; }) as typeof Bun.spawn; @@ -227,7 +227,7 @@ describe('cookie import reliability', () => { const clear = spyOn(globalThis, 'clearTimeout').mockImplementation(() => {}); try { let error: any; - try { await withCookieReadRetry(() => importCookies('dia', ['example.test'])); } catch (caught) { error = caught; } + try { await withCookieReadRetry(() => importCookies('arc', ['example.test'])); } catch (caught) { error = caught; } expect(error).toBeInstanceOf(CookieImportError); expect(error.code).toBe('keychain_denied'); expect(error.message).not.toContain('synthetic-private-detail'); @@ -252,7 +252,7 @@ describe('cookie import reliability', () => { Object.defineProperty(process, 'platform', { configurable: true, value: 'win32' }); expect(listSupportedBrowserNames()).toEqual(['Chrome', 'Chromium', 'Brave', 'Edge', 'Opera', 'Opera GX']); Object.defineProperty(process, 'platform', { configurable: true, value: 'darwin' }); - expect(listSupportedBrowserNames()).toEqual(['Comet', 'Chrome', 'Chromium', 'Arc', 'Dia', 'Brave', 'Edge']); + expect(listSupportedBrowserNames()).toEqual(['Comet', 'Chrome', 'Chromium', 'Arc', 'Brave', 'Edge']); Object.defineProperty(process, 'platform', { configurable: true, value: 'linux' }); expect(listSupportedBrowserNames()).toEqual(['Chrome', 'Chromium', 'Brave', 'Edge']); }); @@ -618,7 +618,7 @@ describe('cookie import reliability', () => { test('windowsNative matches exactly the browsers the native extractor maps', () => { const env = { LOCALAPPDATA: 'C:\\Users\\fixture\\AppData\\Local' }; - for (const browser of ['Comet', 'Chrome', 'Chromium', 'Arc', 'Dia', 'Brave', 'Edge', 'Opera', 'Opera GX']) { + for (const browser of ['Comet', 'Chrome', 'Chromium', 'Arc', 'Brave', 'Edge', 'Opera', 'Opera GX']) { let mapped = true; try { nativeBrowserPaths(browser, env); } catch { mapped = false; } expect(resolveBrowserInfo(browser).windowsNative === true).toBe(mapped); diff --git a/browse/test/cookie-picker-ui.test.ts b/browse/test/cookie-picker-ui.test.ts index 3387a723e..1707fb128 100644 --- a/browse/test/cookie-picker-ui.test.ts +++ b/browse/test/cookie-picker-ui.test.ts @@ -51,10 +51,10 @@ describe('rendered cookie picker', () => { requests = []; imported = []; handler = () => undefined; - browsers = [{ name: 'Chrome', aliases: ['chrome', 'google-chrome', 'google-chrome-stable'] }, { name: 'Dia', aliases: ['dia'] }]; + browsers = [{ name: 'Chrome', aliases: ['chrome', 'google-chrome', 'google-chrome-stable'] }, { name: 'Arc', aliases: ['arc'] }]; profiles = { Chrome: { profiles: [{ name: 'Default', displayName: 'Personal' }, { name: 'Profile 1', displayName: 'Personal' }], recommendedProfile: 'Default' }, - Dia: { profiles: [{ name: 'Profile 1', displayName: 'Work' }, { name: 'Profile 2', displayName: 'Work' }], recommendedProfile: 'Profile 2' }, + Arc: { profiles: [{ name: 'Profile 1', displayName: 'Work' }, { name: 'Profile 2', displayName: 'Work' }], recommendedProfile: 'Profile 2' }, }; errors = []; context = await browser.newContext(); @@ -200,8 +200,8 @@ describe('rendered cookie picker', () => { await openPicker(); await page.getByRole('button', { name: 'Import .chrome-profile-1.test', exact: true }).waitFor(); expect(await page.locator('.profile-pill.active').getAttribute('data-profile')).toBe('Profile 1'); - await page.getByRole('button', { name: 'Dia', exact: true }).click(); - await page.getByRole('button', { name: 'Import .dia-profile-2.test', exact: true }).waitFor(); + await page.getByRole('button', { name: 'Arc', exact: true }).click(); + await page.getByRole('button', { name: 'Import .arc-profile-2.test', exact: true }).waitFor(); expect(await page.locator('.profile-pill.active').getAttribute('data-profile')).toBe('Profile 2'); }); @@ -211,12 +211,12 @@ describe('rendered cookie picker', () => { await page.getByRole('button', { name: 'Import .chrome-profile-1.test', exact: true }).waitFor(); expect(await page.locator('.pill.active').textContent()).toBe('Chrome'); expect(await page.locator('.profile-pill.active').getAttribute('data-profile')).toBe('Profile 1'); - await page.getByRole('button', { name: 'Dia', exact: true }).click(); - await page.getByRole('button', { name: 'Import .dia-profile-2.test', exact: true }).waitFor(); + await page.getByRole('button', { name: 'Arc', exact: true }).click(); + await page.getByRole('button', { name: 'Import .arc-profile-2.test', exact: true }).waitFor(); expect(await page.locator('.profile-pill.active').getAttribute('data-profile')).toBe('Profile 2'); await page.getByRole('button', { name: 'Chrome', exact: true }).click(); await page.getByRole('button', { name: 'Import .chrome-profile-1.test', exact: true }).waitFor(); - expect(requests.filter(request => request.path === '/profiles').map(request => request.browser)).toEqual(['Chrome', 'Dia', 'Chrome']); + expect(requests.filter(request => request.path === '/profiles').map(request => request.browser)).toEqual(['Chrome', 'Arc', 'Chrome']); }); test('does not interpret a browser alias substring as an installed browser', async () => { @@ -241,34 +241,34 @@ describe('rendered cookie picker', () => { for (const earlierFirst of [true, false]) { test(`ignores stale profile responses when the earlier request returns ${earlierFirst ? 'first' : 'last'}`, async () => { const chrome = Promise.withResolvers(); - const dia = Promise.withResolvers(); + const arc = Promise.withResolvers(); const chromeSeen = Promise.withResolvers(); - const diaSeen = Promise.withResolvers(); + const arcSeen = Promise.withResolvers(); handler = request => { if (request.path !== '/profiles') return; if (request.browser === 'Chrome') { chromeSeen.resolve(); return chrome.promise; } - diaSeen.resolve(); return dia.promise; + arcSeen.resolve(); return arc.promise; }; await openPicker(); await chromeSeen.promise; - await page.getByRole('button', { name: 'Dia', exact: true }).click(); - await diaSeen.promise; + await page.getByRole('button', { name: 'Arc', exact: true }).click(); + await arcSeen.promise; if (earlierFirst) { const response = page.waitForResponse(response => response.url().includes('/profiles?browser=Chrome')); chrome.resolve(Response.json(profiles.Chrome)); await response; expect(await page.locator('.profile-pill.active').count()).toBe(0); } - dia.resolve(Response.json(profiles.Dia)); - await page.getByRole('button', { name: 'Import .dia-profile-2.test', exact: true }).waitFor(); + arc.resolve(Response.json(profiles.Arc)); + await page.getByRole('button', { name: 'Import .arc-profile-2.test', exact: true }).waitFor(); if (!earlierFirst) { const response = page.waitForResponse(response => response.url().includes('/profiles?browser=Chrome')); chrome.resolve(Response.json(profiles.Chrome)); await response; } - expect(await page.locator('.pill.active').textContent()).toBe('Dia'); + expect(await page.locator('.pill.active').textContent()).toBe('Arc'); expect(await page.locator('.profile-pill.active').getAttribute('data-profile')).toBe('Profile 2'); - expect(requests.filter(request => request.path === '/domains').map(request => request.browser)).toEqual(['Dia']); + expect(requests.filter(request => request.path === '/domains').map(request => request.browser)).toEqual(['Arc']); }); } @@ -347,16 +347,16 @@ describe('rendered cookie picker', () => { const add = page.getByRole('button', { name: 'Import .chrome-default.test', exact: true }); await add.evaluate((element: HTMLButtonElement) => { element.click(); element.click(); }); await seen.promise; - expect(await page.getByRole('button', { name: 'Dia', exact: true }).isDisabled()).toBe(true); + expect(await page.getByRole('button', { name: 'Arc', exact: true }).isDisabled()).toBe(true); expect(await page.getByRole('button', { name: 'Personal (Profile 1)', exact: true }).isDisabled()).toBe(true); for (const selector of ['#btn-import-all', '#clear-storage', '#verify-auth', '#search', '.btn-trash']) expect(await page.locator(selector).isDisabled()).toBe(true); await page.locator('#btn-import-all').evaluate((element: HTMLButtonElement) => element.click()); - await page.getByRole('button', { name: 'Dia', exact: true }).evaluate((element: HTMLButtonElement) => element.click()); + await page.getByRole('button', { name: 'Arc', exact: true }).evaluate((element: HTMLButtonElement) => element.click()); expect(requests.filter(request => request.path === '/import')).toHaveLength(1); result.resolve(Response.json({ imported: 1, failed: 0, domainCounts: { '.chrome-default.test': 1 }, outcome: 'imported', reset: 'not_requested', verification: { verified: false, reason: 'not_requested' } })); await page.getByRole('status').filter({ hasText: 'Cookies imported.' }).waitFor(); expect(await page.locator('.pill.active').textContent()).toBe('Chrome'); - expect(await page.getByRole('button', { name: 'Dia', exact: true }).isEnabled()).toBe(true); + expect(await page.getByRole('button', { name: 'Arc', exact: true }).isEnabled()).toBe(true); expect(requests.filter(request => request.path === '/import')).toHaveLength(1); }); diff --git a/browse/test/dia-gui-readiness.test.ts b/browse/test/dia-gui-readiness.test.ts deleted file mode 100644 index c34ff3bf6..000000000 --- a/browse/test/dia-gui-readiness.test.ts +++ /dev/null @@ -1,174 +0,0 @@ -import { afterAll, beforeAll, describe, expect, test } from 'bun:test'; -import { createHash } from 'node:crypto'; -import { spawnSync } from 'node:child_process'; -import { chmodSync, copyFileSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'; -import { tmpdir } from 'node:os'; -import path from 'node:path'; -import { parseGuiReadiness, runGuiReadiness, validateGuiReadinessAuthority } from '../../.github/scripts/qualify-dia-macos'; - -const root = realpathSync(mkdtempSync(path.join(tmpdir(), 'dia-gui-readiness-test-'))); -const source = path.resolve(import.meta.dir, '../../.github/scripts/dia-gui-readiness.c'); -const executable = path.join(root, 'metadata-probe'); -const names = ['chrome', 'chromium', 'arc', 'dia', 'comet', 'brave', 'edge', 'safari', 'cookies']; -const observation = () => ({ protocol: 1, supported: true, identity: { effectiveUidMatches: true, homeMatchesRegistered: true }, - security: { status: 0, graphicAccess: true, rootSession: false, tty: false, remote: false }, - quartz: { present: true, sameUid: true, loginDone: true, onConsole: true }, browserRoots: null as any }); - -beforeAll(() => { - const wrapper = path.join(root, 'metadata-probe.c'); - writeFileSync(wrapper, `#define main native_readiness_main\n#include ${JSON.stringify(source)}\n#undef main - int main(int argc, char **argv) { - if (argc != 2) return 2; - int home = open(argv[1], O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK); - if (home < 0) return 2; - print_browser_roots(home, getuid()); close(home); printf("\\n"); return 0; - }`); - const compiler = Bun.which('clang'); - if (!compiler) throw new Error('clang is required for the POSIX metadata regression'); - const compiled = spawnSync(compiler, ['-std=c11', '-O2', '-Wall', '-Wextra', wrapper, - ...(process.platform === 'darwin' ? ['-framework', 'Security', '-framework', 'ApplicationServices'] : []), '-o', executable], - { encoding: 'utf8', timeout: 30_000 }); - if (compiled.status !== 0) throw new Error('metadata_fixture_compile_failed'); -}); - -afterAll(() => rmSync(root, { recursive: true, force: true })); - -const inspect = (home: string) => { - const result = spawnSync(executable, [home], { encoding: 'utf8', timeout: 5000 }); - expect(result.status).toBe(0); - expect(result.stderr).toBe(''); - return JSON.parse(result.stdout); -}; - -describe('read-only GUI readiness', () => { - test('metadata inspection reports missing fixed roots without creating state', () => { - const home = realpathSync(mkdtempSync(path.join(root, 'empty-'))); - const before = readdirSync(home); - const result = inspect(home); - expect(Object.keys(result)).toEqual(names); - for (const name of names) expect(result[name]).toEqual({ state: 'absent', kind: null, ownerMatches: null, ancestorBlocked: false }); - expect(readdirSync(home)).toEqual(before); - expect(lstatSync(home).mode & 0o777).toBe(0o700); - }); - - test('metadata inspection never follows ancestor or target symlinks', () => { - const outside = realpathSync(mkdtempSync(path.join(root, 'other-'))); - writeFileSync(path.join(outside, 'private-sentinel'), 'unchanged fixture contents'); - const linked = realpathSync(mkdtempSync(path.join(root, 'linked-'))); - symlinkSync(outside, path.join(linked, 'Library'), 'dir'); - const blocked = inspect(linked); - for (const name of names) expect(blocked[name]).toEqual({ state: 'unavailable', kind: 'symlink', ownerMatches: true, ancestorBlocked: true }); - const home = realpathSync(mkdtempSync(path.join(root, 'target-'))); - mkdirSync(path.join(home, 'Library')); - symlinkSync(outside, path.join(home, 'Library/Safari'), 'dir'); - expect(inspect(home).safari).toEqual({ state: 'present', kind: 'symlink', ownerMatches: true, ancestorBlocked: false }); - expect(readdirSync(outside)).toEqual(['private-sentinel']); - expect(readFileSync(path.join(outside, 'private-sentinel'), 'utf8')).toBe('unchanged fixture contents'); - }); - - test('wrong ancestor types and access failures are unavailable, never absent', () => { - const home = realpathSync(mkdtempSync(path.join(root, 'wrong-type-'))); - writeFileSync(path.join(home, 'Library'), 'not a directory'); - expect(inspect(home).dia).toEqual({ state: 'unavailable', kind: 'file', ownerMatches: true, ancestorBlocked: true }); - const denied = realpathSync(mkdtempSync(path.join(root, 'denied-'))); - const library = path.join(denied, 'Library'); - mkdirSync(library, { mode: 0o700 }); - chmodSync(library, 0); - try { - expect(inspect(denied).dia).toEqual({ state: 'unavailable', kind: 'directory', ownerMatches: true, ancestorBlocked: true }); - expect(lstatSync(library).mode & 0o777).toBe(0); - } finally { chmodSync(library, 0o700); } - }); - - test('present root metadata does not open contents or change them', () => { - const home = realpathSync(mkdtempSync(path.join(root, 'present-'))); - const safari = path.join(home, 'Library/Safari'); - mkdirSync(safari, { recursive: true }); - const file = path.join(safari, 'private-sentinel'); - writeFileSync(file, 'private fixture content'); - chmodSync(file, 0); - const before = lstatSync(file); - const result = inspect(home); - expect(result.safari).toEqual({ state: 'present', kind: 'directory', ownerMatches: true, ancestorBlocked: false }); - expect(lstatSync(file).mode).toBe(before.mode); - expect(lstatSync(file).mtimeMs).toBe(before.mtimeMs); - expect(JSON.stringify(result)).not.toContain('private'); - chmodSync(file, 0o600); - expect(readFileSync(file, 'utf8')).toBe('private fixture content'); - }); - - test('GUI usability requires both the security capability and the caller-owned logged-in Quartz session', () => { - const original = observation(); - const before = JSON.stringify(original); - Object.freeze(original.identity); Object.freeze(original.security); Object.freeze(original.quartz); Object.freeze(original); - expect(parseGuiReadiness(original, false).usableGui).toBe(true); - expect(JSON.stringify(original)).toBe(before); - for (const changed of [ - { ...observation(), security: { ...observation().security, graphicAccess: false } }, - { ...observation(), quartz: { present: false, sameUid: null, loginDone: null, onConsole: null } }, - { ...observation(), quartz: { present: true, sameUid: false, loginDone: null, onConsole: null } }, - { ...observation(), quartz: { ...observation().quartz, loginDone: false } }, - { ...observation(), identity: { effectiveUidMatches: true, homeMatchesRegistered: false } }, - { ...observation(), security: { status: -60500, graphicAccess: null, rootSession: null, tty: null, remote: null } }, - ]) expect(parseGuiReadiness(changed, false).usableGui).toBe(false); - }); - - test('schema rejects extra identity text, cross-UID session details and false absence claims', () => { - for (const changed of [ - { ...observation(), username: 'private-name' }, - { ...observation(), quartz: { ...observation().quartz, uid: 501 } }, - { ...observation(), quartz: { present: true, sameUid: false, loginDone: true, onConsole: true } }, - { ...observation(), security: { ...observation().security, status: -1 } }, - { ...observation(), security: { ...observation().security, graphicAccess: 1 } }, - ]) expect(() => parseGuiReadiness(changed, false)).toThrow('invalid_gui_readiness_receipt'); - const roots = Object.fromEntries(names.map(name => [name, { state: 'absent', kind: null, ownerMatches: null, ancestorBlocked: false }])); - expect(parseGuiReadiness({ ...observation(), browserRoots: roots }, true).browserRoots).toEqual(roots); - expect(() => parseGuiReadiness({ ...observation(), browserRoots: roots }, false)).toThrow('invalid_gui_readiness_receipt'); - expect(() => parseGuiReadiness({ ...observation(), browserRoots: { ...roots, dia: { state: 'absent', kind: 'symlink', ownerMatches: true, ancestorBlocked: true } } }, true)) - .toThrow('invalid_gui_readiness_receipt'); - }); - - test('GUI authority cannot carry browser/comparison authority or placeholder destination hashes', () => { - const account: any = { work: '/private/tmp/dn-fixture', guiReadiness: { mode: 'gui-readiness-only', executable: '/private/tmp/dn-fixture/bin/gui-readiness', - executableSha256: 'a'.repeat(64), sourceSha256: 'b'.repeat(64) } }; - expect(() => validateGuiReadinessAuthority(account, 'coordinator')).not.toThrow(); - for (const changed of [{ ...account, launchComparison: {} }, { ...account, destinationExecutable: '' }, { ...account, destinationSha256: 'a'.repeat(64) }, - { ...account, guiReadiness: null }, { ...account, guiReadiness: { ...account.guiReadiness, executableSha256: ['a'.repeat(64)] } }, - { ...account, guiReadiness: { ...account.guiReadiness, executable: '/unowned/probe' } }]) { - expect(() => validateGuiReadinessAuthority(changed, 'coordinator')).toThrow('gui_readiness_authority_invalid'); - } - expect(() => validateGuiReadinessAuthority(account, 'comparison-driver')).toThrow('gui_readiness_authority_invalid'); - }); - - test('the registered probe validates hashes, bounds execution, and discards unrecognized output', async () => { - const hash = (file: string) => createHash('sha256').update(readFileSync(file)).digest('hex'); - const exeHash = hash(executable); - const sourceHash = hash(source); - const input = observation(); - const execute = ((command: string, args: string[], options: any) => { - expect(command).toBe(executable); expect(args).toEqual([]); - expect(options.timeout).toBeGreaterThan(0); expect(options.timeout).toBeLessThanOrEqual(5000); - expect(options.killSignal).toBe('SIGKILL'); expect(options.maxBuffer).toBe(16 * 1024); - return { status: 0, stdout: JSON.stringify(input), stderr: 'private diagnostic text' }; - }) as typeof spawnSync; - const result = await runGuiReadiness(executable, exeHash, source, sourceHash, false, { HOME: root }, 5000, execute); - expect(result.available).toBe(true); - expect(JSON.stringify(result)).not.toContain('private diagnostic'); - await expect(runGuiReadiness(executable, 'c'.repeat(64), source, sourceHash, false, {}, 5000, execute)).rejects.toThrow('gui_readiness_inputs_changed'); - const malformed = (() => ({ status: 0, stdout: JSON.stringify({ ...input, username: 'private-name' }), stderr: '' })) as typeof spawnSync; - expect((await runGuiReadiness(executable, exeHash, source, sourceHash, false, {}, 5000, malformed)).available).toBe(false); - for (const timeout of [0, NaN, Infinity]) await expect(runGuiReadiness(executable, exeHash, source, sourceHash, false, {}, timeout, execute)).rejects.toThrow('gui_readiness_budget_exhausted'); - }); - - test('the readiness launcher loads without node_modules or Playwright and rejects conflicting CLI modes', () => { - const directory = path.join(root, 'no-dependencies/.github/scripts'); - mkdirSync(directory, { recursive: true }); - for (const file of ['run-dia-native-qualification.ts', 'qualify-dia-macos.ts']) copyFileSync(path.resolve(import.meta.dir, '../../.github/scripts', file), path.join(directory, file)); - for (const args of [['--gui-readiness-only'], ['--gui-readiness-only', '--launch-comparison', 'node']]) { - const result = spawnSync(process.execPath, ['--no-env-file', '--no-install', '--no-macros', '--config=/dev/null', path.join(directory, 'run-dia-native-qualification.ts'), ...args], - { cwd: root, env: { HOME: root, PATH: '/usr/bin:/bin' }, encoding: 'utf8', timeout: 5000 }); - expect(result.status).toBe(2); expect(result.stderr).toBe(''); - expect(JSON.parse(result.stdout).reason).toBe('fresh_account_launcher_preflight_failed'); - } - }); -}); diff --git a/browse/test/dia-launch-comparison.test.ts b/browse/test/dia-launch-comparison.test.ts deleted file mode 100644 index cab823ae6..000000000 --- a/browse/test/dia-launch-comparison.test.ts +++ /dev/null @@ -1,180 +0,0 @@ -import { afterAll, describe, expect, test } from 'bun:test'; -import { createHash } from 'node:crypto'; -import { spawnSync } from 'node:child_process'; -import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'; -import { tmpdir } from 'node:os'; -import path from 'node:path'; -import { pathToFileURL } from 'node:url'; -import { compareDiaLaunchReceipts, normalizedLaunchHashes } from '../../.github/scripts/dia-launch-driver.mjs'; -import { runDiaLaunchComparison, safeDiaComparisonResponse } from '../../.github/scripts/qualify-dia-macos'; - -const root = realpathSync(mkdtempSync(path.join(tmpdir(), 'dc-'))); -const driverFile = path.resolve(import.meta.dir, '../../.github/scripts/dia-launch-driver.mjs'); -afterAll(() => rmSync(root, { recursive: true, force: true })); - -describe('diagnostic-only Dia runtime comparison', () => { - test('normalization replaces only declared owned path boundaries', () => { - const first = normalizedLaunchHashes(['--user-data-dir=/owned/a/home/profile', '--headless'], { HOME: '/owned/a/home', PATH: '/usr/bin:/bin' }, { home: '/owned/a/home' }); - const second = normalizedLaunchHashes(['--user-data-dir=/owned/b/home/profile', '--headless'], { HOME: '/owned/b/home', PATH: '/usr/bin:/bin' }, { home: '/owned/b/home' }); - expect(first).toEqual(second); - expect(normalizedLaunchHashes(['--user-data-dir=/owned/a/home-other'], {}, { home: '/owned/a/home' }).argvSha256) - .not.toBe(normalizedLaunchHashes(['--user-data-dir=/owned/b/home-other'], {}, { home: '/owned/b/home' }).argvSha256); - expect(normalizedLaunchHashes(['--label=https://private.invalid/owned/a/home'], {}, { home: '/owned/a/home' }).argvSha256) - .not.toBe(normalizedLaunchHashes(['--label=https://private.invalid/owned/b/home'], {}, { home: '/owned/b/home' }).argvSha256); - expect(JSON.stringify(first)).not.toContain('/owned'); - }); - - test('IPC rejects raw payloads at any nesting depth', () => { - for (const value of [{ args: ['private-argv'] }, { cleanup: { raw: 'private-value' } }, { error: 'private-error-value' }, - { startupPages: { categories: ['https://private.invalid'] } }, { driver: { release: '/private/path' } }]) { - expect(safeDiaComparisonResponse(value)).toBe(false); - } - expect(safeDiaComparisonResponse({ protocol: 1, purpose: 'source', error: 'operation_timeout', cleanup: { confirmed: false } })).toBe(true); - }); - - test('the actual driver entry refuses an unapproved host without exposing its request', () => { - for (const executable of [process.execPath, Bun.which('node')!]) { - const result = spawnSync(executable, [driverFile, '/private-untrusted/account.json'], { - env: { PATH: '/usr/bin:/bin', HOME: root }, input: '{"private":"request-value"}', encoding: 'utf8', timeout: 10_000, - }); - expect(result.status).toBe(2); - expect(result.stderr).toBe(''); - expect(JSON.parse(result.stdout)).toEqual({ protocol: 1, ready: false, error: 'driver_admission_failed', cleanup: { confirmed: false } }); - } - }); - - test('the real bounded stdin callback works under both runtimes and refuses raw request payloads', () => { - const entry = path.join(root, 'stdin-probe.mjs'); - writeFileSync(entry, `import { readComparisonRequest } from ${JSON.stringify(pathToFileURL(driverFile).href)}; - try { const request = readComparisonRequest(); process.stdout.write(JSON.stringify({purpose:request.purpose})); } - catch { process.stdout.write(JSON.stringify({rejected:true})); }`); - for (const executable of [process.execPath, Bun.which('node')!]) { - for (const input of ['{"purpose":"control"}', '{"purpose":"control","env":{"PRIVATE":"value"}}', 'x'.repeat(16 * 1024 + 1)]) { - const result = spawnSync(executable, [entry], { env: { HOME: root, PATH: '/usr/bin:/bin' }, input, encoding: 'utf8', timeout: 5000 }); - expect(result.status).toBe(0); - expect(result.stderr).toBe(''); - expect(JSON.parse(result.stdout)).toEqual(input === '{"purpose":"control"}' ? { purpose: 'control' } : { rejected: true }); - } - } - }); - test('both pinned runtimes execute the same protected worker with matched normalized inputs', async () => { - const node = Bun.which('node'); - if (!node) throw new Error('Node 24.18 is required for the comparison regression'); - const entry = path.join(root, 'probe.mjs'); - const executablePath = realpathSync((await import('playwright')).chromium.executablePath()); - writeFileSync(entry, `import { runProtectedLaunch } from ${JSON.stringify(pathToFileURL(driverFile).href)}; - const home = process.env.HOME; - const result = await runProtectedLaunch(${JSON.stringify(executablePath)}, home + '/profile', - { HOME: home, TMPDIR: home + '/tmp', PATH: '/usr/bin:/bin:/usr/sbin:/sbin', LANG: 'en_US.UTF-8' }, 'control', { home }); - process.stdout.write(JSON.stringify(result) + '\\n');`); - const results: any[] = []; - for (const [name, executable] of [['bun', process.execPath], ['node', node]]) { - const home = path.join(root, name); - mkdirSync(home); - mkdirSync(path.join(home, 'tmp')); - const result = spawnSync(executable, [entry], { env: { HOME: home, PATH: '/usr/bin:/bin:/usr/sbin:/sbin' }, - encoding: 'utf8', timeout: 40_000, killSignal: 'SIGKILL', maxBuffer: 64 * 1024 }); - expect(result.status).toBe(0); - expect(result.stderr).toBe(''); - const observed = JSON.parse(result.stdout); - expect(observed.ready).toBe(true); - expect(observed.protocolResponded).toBe(true); - expect(observed.cleanup.confirmed).toBe(true); - expect(observed.cleanup.childClosed).toBe(true); - expect(observed.cleanup.groupAbsent).toBe(true); - expect(observed.cleanup.launchSettled).toBe(true); - expect(observed.rootCount).toBe(1); - expect(observed.launchAttempts[0].pipeFlag).toBe(true); - expect(observed.launchAttempts[0].sandboxDisablingFlag).toBe(false); - expect(observed.samplingEnabled).toBe(false); - expect(safeDiaComparisonResponse(observed)).toBe(true); - expect(JSON.stringify(observed)).not.toContain(home); - results.push(observed); - } - expect(results[0].argvSha256).toBe(results[1].argvSha256); - expect(results[0].environmentSha256).toBe(results[1].environmentSha256); - }, 90_000); - - const arm = (runtime: 'bun' | 'node', ready: boolean) => { - const sha = 'a'.repeat(64); - const config = { mode: 'launch-only', runtime, qualificationCredit: false, executableSha256: runtime === 'bun' ? sha : 'b'.repeat(64), driverSha256: sha, helpersSha256: sha }; - const driver = { runtime, version: runtime === 'bun' ? '1.4.2' : '24.18.0', architecture: 'arm64', os: 'darwin', release: '24.6.0', playwright: '1.62.1', - executableSha256: config.executableSha256, driverSha256: sha, helpersSha256: sha }; - const result = (purpose: string, success: boolean) => ({ protocol: 1, purpose, ready: success, launchReturned: success, protocolResponded: success, - samplingEnabled: false, rootCount: 1, supervisor: { closed: true, exitCode: 0 }, cleanup: { confirmed: true, childClosed: true, groupAbsent: true, launchSettled: true, - groups: [{ absenceConfirmed: true, childCloseObserved: true }] }, startupPages: { allowed: true }, postProbePages: { allowed: true }, - argvSha256: sha, environmentSha256: sha, driver, launchAttempts: [{ sandboxRequired: true, sandboxDisablingFlag: false, pipeFlag: true, - tcpDebuggingFlag: false, mockKeychainFlag: false, passwordStoreFlag: false, firstRunSuppressed: false, headlessFlag: true, - expectedProfile: true, detached: true, shellDisabled: true, stdioCount: 5, extraPipeDescriptors: true, profileArgumentCount: 1 }] }); - return { launchComparison: config, counts: { pass: 0, fail: 0, skip: 0 }, launcher: { accountGuid: runtime + '-separate-account', sourceRevision: 'c'.repeat(40), archiveSha256: sha, destinationSha256: sha }, - launcherCleanup: { serviceStopped: true, userDomainStopped: true, userProcessesStopped: true, accountRemoved: true, groupRemoved: true, stagingRemoved: true }, - backgroundPreflight: { status: 'passed', comparisonControl: result('control', true) }, - qualification: { launchComparison: { qualificationCredit: false, source: result('source', ready) }, counts: { pass: 0, fail: 0, skip: 0 }, - keychainStage: 'completed', isolation: { registeredIdentity: true, sharedRegisteredHome: true }, - cleanup: { ownedBrowsersStopped: true, sourceProfileRemoved: true, keychainRestored: true, mountDetached: true, fixtureRemoved: true }, - platform: { os: 'darwin', architecture: 'arm64', bun: '1.4.2', playwright: '1.62.1', release: '24.6.0' }, - artifact: { signatureVerified: true, gatekeeperNotarized: true, macosCompatibility: { compatible: true, hostVersion: '15.7.9' }, - architectures: ['arm64'], sha256: sha, executableSha256: sha, version: '1.49.1', bundleId: 'company.thebrowser.dia', team: 'S6N382Y83G' } } }; - }; - - test('paired receipts distinguish runtime readiness without awarding qualification credit', () => { - expect(compareDiaLaunchReceipts(arm('bun', false), arm('node', true))).toEqual({ comparable: true, qualificationCredit: false, outcome: 'node_only_ready' }); - expect(compareDiaLaunchReceipts(arm('bun', false), arm('node', false)).outcome).toBe('neither_ready'); - expect(compareDiaLaunchReceipts(arm('bun', true), arm('node', true)).outcome).toBe('both_ready'); - }); - - test('incomplete or incompatible arms cannot support a runtime conclusion', () => { - const left = arm('bun', false); - const mutations = [ - (right: any) => { right.backgroundPreflight.comparisonControl.ready = false; }, - (right: any) => { right.launcherCleanup.userDomainStopped = false; }, - (right: any) => { right.qualification.cleanup.sourceProfileRemoved = false; }, - (right: any) => { right.qualification.artifact.executableSha256 = 'b'.repeat(64); }, - (right: any) => { right.qualification.launchComparison.source.argvSha256 = 'b'.repeat(64); }, - (right: any) => { right.qualification.launchComparison.source.launchAttempts[0].sandboxDisablingFlag = true; }, - (right: any) => { right.qualification.launchComparison.source.driver.version = '24.19.0'; }, - (right: any) => { right.qualification.launchComparison.source.cleanup.launchSettled = false; }, - (right: any) => { right.counts.pass = 1; }, - (right: any) => { right.launcher.accountGuid = left.launcher.accountGuid; }, - (right: any) => { delete right.qualification.platform; }, - ]; - for (const mutate of mutations) { - const right = arm('node', true); - mutate(right); - expect(compareDiaLaunchReceipts(left, right).comparable).toBe(false); - } - }); - - test('comparison supervisor binds code hashes and rejects extra private response fields', async () => { - const work = path.join(root, 'ipc'); - mkdirSync(path.join(work, 'bin'), { recursive: true }); - mkdirSync(path.join(work, 'repo/.github/scripts'), { recursive: true }); - const executable = path.join(work, 'bin/node'); - const driver = path.join(work, 'repo/.github/scripts/dia-launch-driver.mjs'); - const helpers = path.join(work, 'repo/.github/scripts/qualify-dia-macos.ts'); - for (const file of [executable, driver, helpers]) writeFileSync(file, 'synthetic code'); - const hash = (file: string) => createHash('sha256').update(readFileSync(file)).digest('hex'); - const account: any = { work, snapshot: path.join(work, 'repo'), configFile: path.join(work, 'account.json'), environment: { HOME: work }, - launchComparison: { mode: 'launch-only', runtime: 'node', executable, executableSha256: hash(executable), driverSha256: hash(driver), helpersSha256: hash(helpers) } }; - const response: any = { protocol: 1, purpose: 'control', ready: false, launchReturned: false, samplingEnabled: false, cleanup: { confirmed: false }, - driver: { runtime: 'node', version: '24.18.0', architecture: 'arm64', os: 'darwin', playwright: '1.62.1', - executableSha256: hash(executable), driverSha256: hash(driver), helpersSha256: hash(helpers) } }; - let calls = 0; - const execute = ((command: string, args: string[], options: any) => { - calls++; - expect(command).toBe(executable); - expect(args).toEqual([driver, account.configFile]); - expect(JSON.parse(options.input)).toEqual({ purpose: 'control' }); - expect(options.timeout).toBeLessThanOrEqual(40_000); - expect(options.maxBuffer).toBe(64 * 1024); - return { status: 0, stdout: JSON.stringify(response), stderr: '' }; - }) as typeof spawnSync; - expect((await runDiaLaunchComparison(account, 'control', undefined, execute)).supervisor.exitCode).toBe(0); - response.error = 'private-error-value'; - expect((await runDiaLaunchComparison(account, 'control', undefined, execute)).error).toBe('driver_exchange_failed'); - writeFileSync(executable, 'changed executable'); - await expect(runDiaLaunchComparison(account, 'control', undefined, execute)).rejects.toThrow('comparison_driver_inputs_changed'); - expect(calls).toBe(2); - await expect(runDiaLaunchComparison({ ...account, launchComparison: undefined }, 'control', undefined, execute)).rejects.toThrow('comparison_driver_authority_missing'); - }); -}); diff --git a/browse/test/dia-macos-qualification.test.ts b/browse/test/dia-macos-qualification.test.ts deleted file mode 100644 index 48e483158..000000000 --- a/browse/test/dia-macos-qualification.test.ts +++ /dev/null @@ -1,1695 +0,0 @@ -import { afterAll, describe, expect, spyOn, test } from 'bun:test'; -import { createRequire } from 'node:module'; -import { spawnSync } from 'node:child_process'; -import { appendFileSync, chmodSync, existsSync, linkSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'; -import { tmpdir } from 'node:os'; -import path from 'node:path'; -import { pathToFileURL } from 'node:url'; -import { Database } from 'bun:sqlite'; -import { - allowedFixturePage, assertDiaSocketPath, assertOwnedDiaProfile, browserCleanupError, browserGroupFacts, browserOperationTimedOut, browserPreflightError, browserRootFacts, - browserStartupCategory, browserStartupFacts, browserStderrFacts, browserStderrReasons, captureUserKeychains, classifyNativeWaitSample, createBrowserStderrCapture, createOwnedDiaProfile, DIA_DOWNLOAD, fixtureKeychainRestoreCommands, - hasSandboxDisablingArgument, inspectMachOArchitectures, joinOwnedBrowserClose, macosCompatibility, nativeDiaLaunchOptions, observeBrowserLaunches, - observePendingBrowserLaunch, sampleOwnedDiaWait, stopOwnedBrowserGroup, - observeDiaKeychainEnvironments, observeFixtureKeychain, parseDefaultKeychain, parseKeychainPaths, playwrightModuleLoadFacts, prepareKeychainHome, - qualifyDia, readFreshAccountConfiguration, removeOwnedDiaProfile, validateQualificationHost, writePrivateReceipt, -} from '../../.github/scripts/qualify-dia-macos'; -import { ARCHIVE_CHECK, FRESH_WORK_PREFIX, PRIVATE_RECEIPT_READ, classifyParentDomain, classifyUserDomain, freshLaunchDefinition, freshQualificationPassed, - inspectParentDomain, inspectUidProcesses, inspectUserDomain, - ownedUserDomainTarget, ownsFreshAccount, ownsLaunchService, parseDirectoryIds, parseDirectoryRecord, passiveUserDomainState, - runFreshAccountQualification, uidProcessFacts } from '../../.github/scripts/run-dia-native-qualification'; - -const require = createRequire(import.meta.url); -const root = mkdtempSync(path.join(tmpdir(), 'dia-qualification-test-')); -const script = path.resolve(import.meta.dir, '../../.github/scripts/qualify-dia-macos.ts'); -const nativeEnvironment = { - CI: 'true', GITHUB_ACTIONS: 'true', RUNNER_ENVIRONMENT: 'github-hosted', RUNNER_OS: 'macOS', RUNNER_ARCH: 'ARM64', - GSTACK_DIA_NATIVE_QUALIFY: '1', RUNNER_TEMP: root, GITHUB_RUN_ID: 'fixture-run', GITHUB_RUN_ATTEMPT: '1', -}; - -afterAll(() => rmSync(root, { recursive: true, force: true })); - -describe('Dia macOS CI qualification safety', () => { - test('admission accepts only the explicitly enabled disposable ARM64 Mac combination', () => { - expect(() => validateQualificationHost(nativeEnvironment, 'darwin', 'arm64')).not.toThrow(); - for (const [platform, architecture] of [['linux', 'arm64'], ['win32', 'arm64'], ['darwin', 'x64']]) { - expect(() => validateQualificationHost(nativeEnvironment, platform as any, architecture as any)).toThrow('disposable_arm64_macos_ci_required'); - } - expect(readdirSync(root)).toEqual([]); - }); - - for (const name of Object.keys(nativeEnvironment)) { - test(`requires admission field ${name} before any native work`, () => { - const env: NodeJS.ProcessEnv = { ...nativeEnvironment }; - delete env[name]; - expect(() => validateQualificationHost(env, 'darwin', 'arm64')).toThrow('disposable_arm64_macos_ci_required'); - expect(readdirSync(root)).toEqual([]); - }); - } - - test('rejects a self-hosted machine even when the OS and opt-in match', () => { - expect(() => validateQualificationHost({ ...nativeEnvironment, RUNNER_ENVIRONMENT: 'self-hosted' }, 'darwin', 'arm64')) - .toThrow('disposable_arm64_macos_ci_required'); - }); - - test('the actual launcher refuses an unapproved environment without staging files', () => { - const nativeTemp = mkdtempSync(path.join(root, 'runner-temp-')); - const result = spawnSync(process.execPath, ['--no-env-file', '--no-install', '--no-macros', `--config=${process.platform === 'win32' ? 'NUL' : '/dev/null'}`, script], { - cwd: root, env: { PATH: path.dirname(process.execPath), HOME: root, RUNNER_TEMP: nativeTemp, - ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}) }, - encoding: 'utf8', timeout: 10_000, - }); - expect(result.status).toBe(2); - expect(result.stderr).toBe(''); - expect(JSON.parse(result.stdout)).toEqual({ status: 'incomplete', reason: 'qualification_preflight_failed', counts: { pass: 0, fail: 0, skip: 0 } }); - expect(readdirSync(nativeTemp)).toEqual([]); - }); - - test('a fresh fixture-HOME child uses unmodified production Dia profile and domain discovery', () => { - const home = realpathSync(mkdtempSync(path.join(root, 'fixture-home-'))); - const ownership = createOwnedDiaProfile(home); - const profile = path.join(ownership.profile, 'Default'); - mkdirSync(profile, { recursive: true }); - const database = new Database(path.join(profile, 'Cookies')); - database.run('CREATE TABLE cookies (host_key TEXT, has_expires INTEGER, expires_utc INTEGER)'); - database.query('INSERT INTO cookies VALUES (?, ?, ?)').run('.fixture.test', 0, 0); - database.close(); - const production = pathToFileURL(path.resolve(import.meta.dir, '../src/cookie-import-browser.ts')).href; - const result = spawnSync(process.execPath, ['--no-env-file', '--no-install', '--no-macros', `--config=${process.platform === 'win32' ? 'NUL' : '/dev/null'}`, '-e', ` - import { homedir } from 'node:os'; - const { listProfiles, listDomains } = await import(${JSON.stringify(production)}); - console.log(JSON.stringify({ homeAtStartup: homedir() === process.env.HOME, - profiles: listProfiles('Dia').map(profile => profile.name), domains: listDomains('Dia', 'Default').domains })); - `], { - cwd: root, env: { PATH: path.dirname(process.execPath), HOME: home, USERPROFILE: home, - ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}) }, - encoding: 'utf8', timeout: 10_000, - }); - expect(result.status).toBe(0); - expect(result.stderr).toBe(''); - expect(JSON.parse(result.stdout)).toEqual({ homeAtStartup: true, profiles: ['Default'], domains: [{ domain: '.fixture.test', count: 1 }] }); - expect(() => assertOwnedDiaProfile(ownership)).not.toThrow(); - removeOwnedDiaProfile(ownership, true); - expect(existsSync(home)).toBe(true); - }); - - for (const precreate of [false, true]) { - test(`late-installed real Playwright loads only with its dependency directory present at startup (${precreate})`, () => { - const fixture = realpathSync(mkdtempSync(path.join(root, 'late-playwright-'))); - const home = path.join(fixture, 'home'); - const scripts = path.join(fixture, '.github/scripts'); - const modules = path.join(fixture, 'node_modules'); - mkdirSync(home); - mkdirSync(scripts, { recursive: true }); - if (precreate) mkdirSync(modules, { mode: 0o700 }); - writeFileSync(path.join(fixture, 'package.json'), JSON.stringify({ type: 'module', dependencies: { playwright: '1.62.1' } })); - const sourceModules = path.resolve(import.meta.dir, '../../node_modules'); - const worker = path.join(scripts, 'worker.ts'); - writeFileSync(worker, ` - import { cpSync, mkdirSync } from 'node:fs'; - import { createRequire } from 'node:module'; - const require = createRequire(import.meta.url); - mkdirSync(${JSON.stringify(modules)}, { recursive: true }); - for (const name of ['playwright', 'playwright-core']) cpSync(${JSON.stringify(sourceModules)} + '/' + name, ${JSON.stringify(modules)} + '/' + name, { recursive: true }); - const version = require(${JSON.stringify(path.join(modules, 'playwright/package.json'))}).version; - try { - const loaded = await import('playwright'); - console.log(JSON.stringify({ version, loaded: !!loaded.chromium })); - } catch (error) { - console.log(JSON.stringify({ version, type: error.name, code: error.code })); - process.exitCode = 2; - } - `); - const result = spawnSync(process.execPath, ['--no-env-file', '--no-install', '--no-macros', - `--config=${process.platform === 'win32' ? 'NUL' : '/dev/null'}`, worker], { - cwd: fixture, env: { HOME: home, PATH: path.dirname(process.execPath) }, encoding: 'utf8', timeout: 30_000, - }); - expect(result.stderr).toBe(''); - expect(result.status).toBe(precreate ? 0 : 2); - expect(JSON.parse(result.stdout)).toEqual(precreate ? { version: '1.62.1', loaded: true } - : { version: '1.62.1', type: 'ResolveMessage', code: 'ERR_MODULE_NOT_FOUND' }); - }); - } - - test('the download is the published HTTPS Dia release endpoint', () => { - expect(DIA_DOWNLOAD).toBe('https://releases.diabrowser.com/release/Dia-latest.dmg'); - }); - - describe('bounded Mach-O architecture inspection', () => { - const thin = (cpu = 0x0100000c, subtype = 0, little = true, wide = true) => { - const buffer = Buffer.alloc((wide ? 32 : 28) + 8); - const word = (value: number, at: number) => little ? buffer.writeUInt32LE(value, at) : buffer.writeUInt32BE(value, at); - word(wide ? 0xfeedfacf : 0xfeedface, 0); - word(cpu, 4); - word(subtype, 8); - word(2, 12); - word(1, 16); - word(8, 20); - return buffer; - }; - const fat = (little = false, wide = false) => { - const buffer = Buffer.alloc(512); - const word = (value: number, at: number) => little ? buffer.writeUInt32LE(value, at) : buffer.writeUInt32BE(value, at); - const wideWord = (value: bigint, at: number) => little ? buffer.writeBigUInt64LE(value, at) : buffer.writeBigUInt64BE(value, at); - word(wide ? 0xcafebabf : 0xcafebabe, 0); - word(2, 4); - for (const [index, cpu, subtype] of [[0, 0x01000007, 3], [1, 0x0100000c, 0]]) { - const at = 8 + index * (wide ? 32 : 20); - const image = thin(cpu, subtype); - word(cpu, at); - word(subtype, at + 4); - if (wide) { wideWord(BigInt(128 * (index + 1)), at + 8); wideWord(BigInt(image.length), at + 16); } - else { word(128 * (index + 1), at + 8); word(image.length, at + 12); } - word(7, at + (wide ? 24 : 16)); - image.copy(buffer, 128 * (index + 1)); - } - return buffer; - }; - const store = (buffer: Buffer) => { - const directory = realpathSync(mkdtempSync(path.join(root, 'macho-'))); - const file = path.join(directory, 'executable'); - writeFileSync(file, buffer, { mode: 0o600 }); - return file; - }; - for (const little of [true, false]) { - test(`thin headers honor byte order (${little}) and distinguish arm64 subtypes`, () => { - expect(inspectMachOArchitectures(store(thin(0x0100000c, 0, little))).architectures).toEqual(['arm64']); - expect(inspectMachOArchitectures(store(thin(0x0100000c, 0x80000002, little))).architectures).toEqual(['arm64e']); - expect(inspectMachOArchitectures(store(thin(0x01000007, 3, little))).architectures).toEqual(['x86_64']); - expect(inspectMachOArchitectures(store(thin(7, 3, little, false))).architectures).toEqual(['i386']); - }); - for (const wide of [true, false]) { - test(`fat headers verify their actual slices (${little}, ${wide})`, () => { - const result = inspectMachOArchitectures(store(fat(little, wide))); - expect(result).toMatchObject({ method: 'bounded_macho_headers', format: wide ? 'fat64' : 'fat32', slices: 2, - architectures: ['x86_64', 'arm64'] }); - expect(result.bytesRead).toBeLessThanOrEqual(4096); - }); - } - } - - for (const invalid of ['magic', 'truncated', 'empty_fat', 'excessive_fat', 'truncated_table', 'table_overlap', 'slice_overlap', - 'slice_out_of_bounds', 'slice_too_short', 'misaligned', 'alignment_overflow', 'cpu_mismatch', 'subtype_mismatch', 'nested_fat', - 'duplicate_architecture', 'wide_offset_overflow', 'reserved', 'header_width', 'file_type', 'load_commands', 'unknown_cpu']) { - test(`architecture inspection rejects ${invalid} rather than guessing arm64`, () => { - let image = fat(); - if (invalid === 'magic') image = Buffer.from('not a macho executable'); - if (invalid === 'truncated') image = thin().subarray(0, 20); - if (invalid === 'empty_fat') image.writeUInt32BE(0, 4); - if (invalid === 'excessive_fat') image.writeUInt32BE(33, 4); - if (invalid === 'truncated_table') image = image.subarray(0, 24); - if (invalid === 'table_overlap') image.writeUInt32BE(0, 16); - if (invalid === 'slice_overlap') image.writeUInt32BE(128, 36); - if (invalid === 'slice_out_of_bounds') image.writeUInt32BE(1024, 36); - if (invalid === 'slice_too_short') image.writeUInt32BE(28, 40); - if (invalid === 'misaligned') image.writeUInt32BE(257, 36); - if (invalid === 'alignment_overflow') image.writeUInt32BE(0xffffffff, 44); - if (invalid === 'cpu_mismatch') image.writeUInt32LE(0x01000007, 260); - if (invalid === 'subtype_mismatch') image.writeUInt32LE(2, 264); - if (invalid === 'nested_fat') image.writeUInt32BE(0xcafebabe, 256); - if (invalid === 'duplicate_architecture') { image.writeUInt32BE(0x01000007, 28); image.writeUInt32BE(3, 32); thin(0x01000007, 3).copy(image, 256); } - if (invalid === 'wide_offset_overflow') { image = fat(false, true); image.writeBigUInt64BE(1n << 60n, 16); } - if (invalid === 'reserved') { image = fat(false, true); image.writeUInt32BE(1, 36); } - if (invalid === 'header_width') image = thin(0x0100000c, 0, true, false); - if (invalid === 'file_type') { image = thin(); image.writeUInt32LE(6, 12); } - if (invalid === 'load_commands') { image = thin(); image.writeUInt32LE(1000, 20); } - if (invalid === 'unknown_cpu') image = thin(0x010000ff, 0); - expect(() => inspectMachOArchitectures(store(image))).toThrow(); - }); - } - - test('architecture inspection rejects links, non-files, and expired budgets', () => { - const file = store(thin()); - symlinkSync(file, file + '.link'); - expect(() => inspectMachOArchitectures(file + '.link')).toThrow('unsafe_macho_file'); - expect(() => inspectMachOArchitectures(path.dirname(file))).toThrow('unsafe_macho_file'); - for (const budget of [0, NaN, Infinity]) expect(() => inspectMachOArchitectures(file, budget)).toThrow('macho_read_budget_exhausted'); - expect(qualifyDia.toString()).not.toContain('/usr/bin/lipo'); - }); - - for (const change of ['append', 'replace']) { - test(`architecture inspection detects a file that changes by ${change}`, () => { - const image = thin(); - const file = store(image); - let ticks = 0; - const clock = spyOn(performance, 'now').mockImplementation(() => { - if (++ticks === 3) { - if (change === 'append') appendFileSync(file, Buffer.from([0])); - else { renameSync(file, file + '.previous'); writeFileSync(file, image); } - } - return 100; - }); - try { expect(() => inspectMachOArchitectures(file)).toThrow('macho_changed_during_inspection'); } - finally { clock.mockRestore(); } - }); - } - }); - test('the exact nested macOS account and qualifier socket layout stays below the unchanged limit', () => { - const sourceProfile = path.posix.join(FRESH_WORK_PREFIX + 'XXXXXX', 'tmp', 'dia-XXXXXX', 'h', 'Library/Application Support/Dia/User Data'); - expect(Buffer.byteLength(sourceProfile + '/SingletonSocket')).toBe(97); - expect(() => assertDiaSocketPath(sourceProfile)).not.toThrow(); - const oldProfile = '/private/tmp/dia-native-XXXXXX/tmp/dia-XXXXXX/h/Library/Application Support/Dia/User Data'; - expect(Buffer.byteLength(oldProfile + '/SingletonSocket')).toBe(105); - expect(() => assertDiaSocketPath(oldProfile)).toThrow('fixture_socket_path_too_long'); - const atLimit = '/' + 'x'.repeat(100 - Buffer.byteLength('//SingletonSocket')); - expect(Buffer.byteLength(atLimit + '/SingletonSocket')).toBe(100); - expect(() => assertDiaSocketPath(atLimit)).toThrow('fixture_socket_path_too_long'); - }); - - test('the registered-home source profile fits the socket bound without a shadow HOME', () => { - const profile = path.posix.join(FRESH_WORK_PREFIX + 'XXXXXX', 'home', 'Library/Application Support/Dia/User Data'); - expect(Buffer.byteLength(profile + '/SingletonSocket')).toBe(85); - expect(() => assertDiaSocketPath(profile)).not.toThrow(); - const implementation = qualifyDia.toString(); - expect(implementation).toContain('readFreshAccountConfiguration'); - expect(implementation).toContain('const home = account.home'); - expect(implementation).not.toMatch(/fixtureEnvironment|systemEnvironment|isolation\.originalHome/); - expect(implementation).toContain('removeOwnedDiaProfile'); - }); - - test('profile ownership is exclusive and cleanup preserves the account home and sibling state', () => { - const home = realpathSync(mkdtempSync(path.join(root, 'owned-profile-home-'))); - prepareKeychainHome(home); - const preserved = path.join(home, 'Library/Keychains/fixture-state'); - writeFileSync(preserved, 'preserved fixture state'); - const ownership = createOwnedDiaProfile(home); - const sibling = path.join(path.dirname(ownership.profile), 'sibling-state'); - writeFileSync(sibling, 'preserved sibling state'); - expect(() => assertOwnedDiaProfile(ownership)).not.toThrow(); - expect(() => createOwnedDiaProfile(home)).toThrow(); - expect(() => removeOwnedDiaProfile(ownership, false)).toThrow('owned_browsers_not_stopped'); - expect(existsSync(ownership.profile)).toBe(true); - removeOwnedDiaProfile(ownership, true); - expect(existsSync(ownership.profile)).toBe(false); - expect(existsSync(home)).toBe(true); - expect(readFileSync(preserved, 'utf8')).toBe('preserved fixture state'); - expect(readFileSync(sibling, 'utf8')).toBe('preserved sibling state'); - }); - - for (const change of ['nonce', 'inode', 'marker_symlink', 'profile_symlink', 'uid', 'home_escape', 'marker_permissions', 'marker_hardlink']) { - test(`profile cleanup refuses changed ${change} ownership without deleting the directory`, () => { - const home = realpathSync(mkdtempSync(path.join(root, 'profile-refusal-'))); - const ownership = createOwnedDiaProfile(home); - const profile = ownership.profile; - const marker = path.join(profile, '.gstack-dia-owner'); - if (change === 'nonce') writeFileSync(marker, (ownership.nonce[0] === '0' ? '1' : '0') + ownership.nonce.slice(1)); - if (change === 'inode') { - renameSync(profile, profile + '.original'); - mkdirSync(profile, { mode: 0o700 }); - writeFileSync(marker, ownership.nonce, { mode: 0o600 }); - } - if (change === 'marker_symlink') { renameSync(marker, marker + '.original'); symlinkSync(marker + '.original', marker); } - if (change === 'profile_symlink') { renameSync(profile, profile + '.original'); symlinkSync(profile + '.original', profile, 'dir'); } - if (change === 'uid') ownership.uid = process.getuid!() + 1; - if (change === 'home_escape') ownership.profile = home; - if (change === 'marker_permissions') chmodSync(marker, 0o644); - if (change === 'marker_hardlink') linkSync(marker, path.join(home, 'marker-link')); - expect(() => removeOwnedDiaProfile(ownership, true)).toThrow(); - expect(existsSync(profile)).toBe(true); - expect(existsSync(home)).toBe(true); - }); - } - - test('source profile creation refuses existing profiles and linked ancestors without writing through them', () => { - const home = realpathSync(mkdtempSync(path.join(root, 'existing-profile-'))); - const profile = path.join(home, 'Library/Application Support/Dia/User Data'); - mkdirSync(profile, { recursive: true }); - writeFileSync(path.join(profile, 'existing-state'), 'untouched'); - expect(() => createOwnedDiaProfile(home)).toThrow(); - expect(readdirSync(profile)).toEqual(['existing-state']); - const linkedHome = realpathSync(mkdtempSync(path.join(root, 'linked-profile-home-'))); - const elsewhere = realpathSync(mkdtempSync(path.join(root, 'linked-profile-target-'))); - symlinkSync(elsewhere, path.join(linkedHome, 'Library'), 'dir'); - expect(() => createOwnedDiaProfile(linkedHome)).toThrow('unsafe_profile_ancestor'); - expect(readdirSync(elsewhere)).toEqual([]); - }); - - test('the qualifier rejects an arbitrary caller-supplied home as fresh account authority', () => { - const fake = path.join(root, 'account.json'); - writeFileSync(fake, JSON.stringify({ home: root, uid: process.getuid?.() })); - expect(() => readFreshAccountConfiguration(fake)).toThrow('unsafe_fresh_account_configuration'); - expect(() => readFreshAccountConfiguration('account.json')).toThrow('unsafe_fresh_account_configuration'); - }); - - test('headless source launch removes mock Keychain and first-run suppression defaults', () => { - const env = { HOME: '/fixture/home', PATH: '/usr/bin:/bin' }; - const options = nativeDiaLaunchOptions('/fixture/Dia.app/Contents/MacOS/Dia', env); - expect(options.headless).toBe(true); - expect(options.chromiumSandbox).toBe(true); - expect(options.timeout).toBe(30_000); - expect(options.ignoreDefaultArgs).toEqual(['--use-mock-keychain', '--password-store=basic', '--no-first-run']); - expect(options.args).toEqual(['--disable-sync', '--no-default-browser-check', '--profile-directory=Default']); - expect(options.env).toBe(env); - expect(options.serviceWorkers).toBe('block'); - expect(options.args.some(arg => /onboarding|skip-login|remote-debugging-port/.test(arg))).toBe(false); - }); - - test('Mac native spawn policy refuses sandbox-disabling arguments regardless of caller options', () => { - const descriptor = Object.getOwnPropertyDescriptor(process, 'platform')!; - const profile = path.join(root, 'mac-sandbox-policy'); - const childProcess = require('node:child_process'); - const observer = observeBrowserLaunches(new Map([[process.execPath, profile]])); - try { - Object.defineProperty(process, 'platform', { ...descriptor, value: 'darwin' }); - for (const disabling of [['--no-sandbox'], ['--no-sandbox=false'], ['--disable-sandbox'], ['--disable-gpu-sandbox'], - ['--disable-setuid-sandbox'], ['--disable-seccomp-filter-sandbox'], ['--disable-namespace-sandbox'], ['--no-zygote-sandbox'], - ['--single-process'], ['--in-process-gpu'], ['--disable-features=GpuSandboxV2'], ['--disable-features', 'RendererSandbox']]) { - expect(hasSandboxDisablingArgument(disabling)).toBe(true); - expect(() => childProcess.spawn(process.execPath, ['--remote-debugging-pipe', '--user-data-dir=' + profile, ...disabling], { - detached: true, shell: false, stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'], chromiumSandbox: false, - allowSandboxDisable: true, env: { DISABLE_SANDBOX: '1' }, - })).toThrow('browser_launch_policy_rejected'); - expect(observer.attempts.at(-1)).toMatchObject({ sandboxRequired: true, sandboxDisablingFlag: true }); - } - expect(observer.children).toHaveLength(0); - } finally { Object.defineProperty(process, 'platform', descriptor); observer.restore(); } - expect(hasSandboxDisablingArgument(['--headless', '--disable-sync', '--disable-features=MediaRouter,Translate'])).toBe(false); - }); - - test('startup admits only blank pages or the exact synthetic loopback origin', () => { - const origin = 'http://127.0.0.1:8123'; - expect(allowedFixturePage('about:blank', origin)).toBe(true); - expect(allowedFixturePage(origin + '/seed', origin)).toBe(true); - for (const url of ['https://www.diabrowser.com/login', 'dia://onboarding', 'chrome://welcome', 'http://localhost:8123/seed', - 'http://127.0.0.1:8124/seed', 'javascript:alert(1)', 'about:config', 'invalid']) expect(allowedFixturePage(url, origin)).toBe(false); - const authenticated = new URL(origin); - authenticated.username = 'fixture-user'; - authenticated.password = 'fixture'; - expect(allowedFixturePage(authenticated.href, origin)).toBe(false); - }); - - test('startup diagnostics classify pages without exposing URLs or broadening admission', () => { - const pages = [ - ['about:blank', 'blank'], ['about:blank#synthetic-private-value', 'other_about'], - ['chrome://newtab/?token=synthetic-private-value', 'chromium_new_tab'], - ['chrome://new-tab-page/', 'chromium_new_tab'], ['chrome://intro/', 'chromium_onboarding'], - ['chrome://welcome/', 'chromium_onboarding'], ['chrome://settings/', 'chromium_internal'], - ['dia://onboarding', 'dia_internal'], ['chrome-extension://fixture/path', 'extension'], - ['https://fixture.invalid/login?token=synthetic-private-value', 'external_web'], - ['http://127.0.0.1:8123' + '/fixture', 'loopback_web'], ['file:///synthetic-private-value', 'file'], - ['data:text/html,synthetic-private-value', 'data'], ['invalid synthetic-private-value', 'invalid'], - ]; - const categories = pages.map(([url]) => browserStartupCategory(url)); - expect(categories).toEqual(pages.map(([, category]) => category)); - expect(JSON.stringify(categories)).not.toContain('synthetic-private-value'); - expect(JSON.stringify(categories)).not.toContain('fixture.invalid'); - for (const [url] of pages.slice(1, 10)) expect(allowedFixturePage(url, 'http://127.0.0.1:8123')).toBe(false); - }); - - test('browser stderr classifies only known policy, pipe, Keychain, loader and bootstrap diagnostics', () => { - for (const [line, reason] of [ - ['DevTools remote debugging requires a non-default data directory. Specify this using --user-data-dir.', 'default_profile_policy'], - ['Remote debugging pipe file descriptors are not open.', 'debugging_pipe_unavailable'], - ['errSecInteractionNotAllowed: User interaction is not allowed.', 'keychain_interaction_disallowed'], - ['errSecInteractionRequired', 'keychain_interaction_required'], - ['errSecAuthFailed', 'keychain_access_failed'], - ['dyld[123]: Library not loaded:', 'dynamic_library_error'], - ['code signature invalid', 'code_signing_error'], - ['bootstrap_check_in failed', 'graphics_or_bootstrap_error'], - ['ProcessSingleton', 'browser_profile_unavailable'], - ]) { - const reasons = browserStderrReasons(line + ' synthetic-private-value /private/fixture/profile'); - expect(reasons).toContain(reason); - expect(JSON.stringify(reasons)).not.toContain('synthetic-private'); - expect(JSON.stringify(reasons)).not.toContain('/private'); - } - for (const line of ['using a non-default data directory', 'remote-debugging-pipe enabled', 'Waiting for Keychain', - 'WindowServer connection available', 'private unknown diagnostic']) expect(browserStderrReasons(line)).toEqual([]); - }); - - test('stderr capture handles chunk boundaries and final unterminated lines without retaining text', () => { - const capture = createBrowserStderrCapture(); - const policy = 'DevTools remote debugging requires a non-default data directory.'; - capture.consume(Buffer.from('synthetic-private-value\n' + policy.slice(0, 23))); - expect(capture.snapshot().reasonCounts.default_profile_policy).toBe(0); - capture.consume(Buffer.from(policy.slice(23))); - const before = capture.snapshot(); - expect(before.reasonCounts.default_profile_policy).toBe(1); - capture.consume(Buffer.from('\n' + policy)); - capture.end(); - expect(capture.snapshot().reasonCounts.default_profile_policy).toBe(2); - expect(before.reasonCounts.default_profile_policy).toBe(1); - expect(capture.snapshot().ended).toBe(true); - expect(JSON.stringify(capture.snapshot())).not.toContain('synthetic-private'); - expect(JSON.stringify(capture.snapshot())).not.toContain('DevTools'); - }); - - test('stderr inspection caps bytes and pending line size while exposing truncation honestly', () => { - const capture = createBrowserStderrCapture(); - capture.consume(Buffer.alloc(65_536, 120)); - capture.consume(Buffer.from('\nDevTools remote debugging requires a non-default data directory.\n')); - const facts = capture.snapshot(); - expect(facts.bytesInspected).toBe(65_536); - expect(facts.bytesSeen).toBeGreaterThan(65_536); - expect(facts.truncated).toBe(true); - expect(facts.discardedLongLines).toBe(1); - expect(facts.reasonCounts.default_profile_policy).toBe(0); - const lines = createBrowserStderrCapture(); - lines.consume('x'.repeat(5000) + '\nRemote debugging pipe file descriptors are not open.\n'); - expect(lines.snapshot().reasonCounts.debugging_pipe_unavailable).toBe(1); - expect(lines.snapshot().truncated).toBe(true); - }); - - test('causal stderr reasons outrank a generic timeout without changing its timeout identity', () => { - const timeout = Object.assign(new Error('synthetic-private-timeout'), { name: 'TimeoutError' }); - expect(browserOperationTimedOut(timeout)).toBe(true); - expect(browserPreflightError(timeout)).toBe('operation_timeout'); - expect(browserPreflightError(timeout, ['default_profile_policy'])).toBe('default_profile_policy'); - expect(browserPreflightError(timeout, ['debugging_pipe_unavailable'])).toBe('debugging_pipe_unavailable'); - expect(browserPreflightError(timeout, ['keychain_interaction_required'])).toBe('keychain_interaction_required'); - const embedded = Object.assign(new Error('Timed out\nDevTools remote debugging requires a non-default data directory.'), { name: 'TimeoutError' }); - expect(browserPreflightError(embedded)).toBe('default_profile_policy'); - expect(browserOperationTimedOut(embedded)).toBe(true); - }); - - test('stderr snapshots keep source, destination, and cleanup-time observations separate', () => { - const source = createBrowserStderrCapture(); - const destination = createBrowserStderrCapture(); - source.consume('DevTools remote debugging requires a non-default data directory.\n'); - const beforeCleanup = source.snapshot(); - source.consume('bootstrap_check_in failed\n'); - destination.consume('Remote debugging pipe file descriptors are not open.\n'); - expect(beforeCleanup.reasonCounts.graphics_or_bootstrap_error).toBe(0); - expect(source.snapshot().reasonCounts.graphics_or_bootstrap_error).toBe(1); - expect(destination.snapshot().reasonCounts.default_profile_policy).toBe(0); - expect(destination.snapshot().reasonCounts.debugging_pipe_unavailable).toBe(1); - }); - - test('signed macOS requirements compare numeric versions and preserve unknown metadata', () => { - expect(macosCompatibility({ LSMinimumSystemVersion: '14.0' }, '15.6.1')).toEqual({ hostVersion: '15.6.1', - minimumSystemVersion: '14.0', minimumArm64Version: null, compatible: true }); - expect(macosCompatibility({ LSMinimumSystemVersion: '26.0' }, '15.6.1').compatible).toBe(false); - expect(macosCompatibility({ LSMinimumSystemVersion: '15.9' }, '15.10').compatible).toBe(true); - expect(macosCompatibility({ LSMinimumSystemVersion: '15.6.1' }, '15.6').compatible).toBe(false); - expect(macosCompatibility({ LSMinimumSystemVersion: '15.6' }, '15.6.0').compatible).toBe(true); - expect(macosCompatibility({ LSMinimumSystemVersion: '14.0', LSMinimumSystemVersionByArchitecture: { arm64: '26.0' } }, '15.6.1').compatible).toBe(false); - expect(macosCompatibility({ LSMinimumSystemVersion: '26.0', LSMinimumSystemVersionByArchitecture: { arm64: '14.0' } }, '15.6.1').compatible).toBe(false); - expect(macosCompatibility({ LSMinimumSystemVersionByArchitecture: { arm64: '14.0' } }, '15.6.1').compatible).toBe(true); - for (const plist of [{}, null, { LSMinimumSystemVersion: 'synthetic-private-value' }, { LSMinimumSystemVersion: 14 }, - { LSMinimumSystemVersion: '14.0', LSMinimumSystemVersionByArchitecture: 'synthetic-private-value' }, - { LSMinimumSystemVersion: '14.0', LSMinimumSystemVersionByArchitecture: [] }, - { LSMinimumSystemVersion: '14.0', LSMinimumSystemVersionByArchitecture: { arm64: 'private-version' } }]) { - const facts = macosCompatibility(plist, '15.6.1'); - expect(facts.compatible).toBeNull(); - expect(JSON.stringify(facts)).not.toContain('private'); - } - expect(macosCompatibility({ LSMinimumSystemVersion: '14.0' }, 'private-host-version').compatible).toBeNull(); - }); - - test('bounded startup categories do not hide a disallowed page beyond the receipt limit', () => { - const urls = [...Array(64).fill('about:blank'), 'https://private.invalid/?token=synthetic-private-value']; - const facts = browserStartupFacts(urls, 'http://127.0.0.1:8123'); - expect(facts).toMatchObject({ count: 65, truncated: true, allowed: false }); - expect(facts.categories).toHaveLength(64); - expect(JSON.stringify(facts)).not.toContain('private'); - }); - - test('browser root facts retain exit and allowlisted signal evidence without process payloads', () => { - const facts = browserRootFacts([ - { pid: 300, process: { exitCode: null, signalCode: null, spawnargs: ['synthetic-private-value'] } }, - { pid: 301, process: { exitCode: 0, signalCode: null } }, - { pid: 302, process: { exitCode: null, signalCode: 'SIGABRT' } }, - { pid: 303, process: { exitCode: null, signalCode: 'synthetic-private-signal' } }, - ] as any); - expect(facts).toEqual([{ pid: 300, exitCode: null, signal: null }, { pid: 301, exitCode: 0, signal: null }, - { pid: 302, exitCode: null, signal: 'SIGABRT' }, { pid: 303, exitCode: null, signal: 'other' }]); - expect(JSON.stringify(facts)).not.toContain('private'); - }); - - test('browser cleanup distinguishes live groups from signal errors without retaining raw errors', () => { - expect(browserCleanupError(new Error('owned_process_group_still_live')).reason).toBe('group_still_live'); - expect(browserCleanupError(new Error('cleanup_budget_exhausted')).reason).toBe('cleanup_deadline'); - expect(browserCleanupError(Object.assign(new Error('synthetic-private-value'), { code: 'EPERM', errno: 1 }))) - .toEqual({ reason: 'signal_or_probe_failed', code: 'EPERM', errno: 1 }); - const unknown = browserCleanupError({ message: 'synthetic-private-value', code: 'private-code', errno: 'private-errno' }); - expect(unknown).toEqual({ reason: 'signal_or_probe_failed', code: 'unclassified', errno: null }); - }); - - test('process-group diagnostics distinguish owned zombies, live members, and unrelated UID counts', () => { - const facts = browserGroupFacts('20000 300 1 300 Z\n20000 301 1 300 S+\n501 302 1 300 S\n20000 400 1 400 S\n', 20000, 300); - expect(facts).toEqual({ available: true, count: 2, foreignUidCount: 1, zombies: 1, live: 1, truncated: false, - processes: [{ pid: 300, ppid: 1, state: 'Z' }, { pid: 301, ppid: 1, state: 'S' }] }); - expect(browserGroupFacts(Array.from({ length: 70 }, (_, index) => `20000 ${index + 300} 1 300 S`).join('\n'), 20000, 300).processes).toHaveLength(64); - expect(() => browserGroupFacts('private-invalid-row', 20000, 300)).toThrow('invalid_group_snapshot'); - expect(() => browserGroupFacts('', 20000, 0)).toThrow('invalid_group_snapshot_target'); - }); - - test('native samples retain fixed wait families only from call-graph frames', () => { - const output = `Process: private-process [123] -Path: /private/sensitive/Security/AppKit/CFNetwork -Call graph: - 100 Thread_11 DispatchQueue_1: com.apple.main-thread (serial) - + 100 NSApplicationMain (in AppKit) private-source-path - + 100 SecKeychainFindGenericPassword (in Security) private-item-name - + 100 mach_msg_trap (in libsystem_kernel) - 100 Thread_12 private-thread-name - + 100 NSURLSessionTask (in CFNetwork) private-request-url -Total number in stack (recursive counted multiple): - 999 SecItemCopyMatching private-unrelated-summary -Binary Images: - Security AppKit CFNetwork /private/image/path -`; - const result = classifyNativeWaitSample(output); - expect(result).toEqual({ available: true, callGraphSeen: true, mainThreadSeen: true, frames: 4, - frameCounts: { security_keychain: 1, appkit_bootstrap: 1, network: 1, runloop: 1 }, - mainThreadFrameCounts: { security_keychain: 1, appkit_bootstrap: 1, network: 0, runloop: 1 }, - shape: { graphLines: 6, nonemptyGraphLines: 6, threadTokenLines: 2, numericPrefixLines: 2, imageAnnotatedLines: 4, - nonAsciiGraphLines: 0, unrecognizedGraphLines: 0, graphEnd: 'totals', binaryImagesSeen: true } }); - expect(JSON.stringify(result)).not.toContain('private'); - expect(JSON.stringify(result)).not.toContain('SecKeychain'); - expect(classifyNativeWaitSample('private missing call graph').available).toBe(false); - expect(classifyNativeWaitSample('x'.repeat(1024 * 1024 + 1))).toEqual({ available: false, reason: 'sample_output_oversized' }); - }); - - test('sample structure distinguishes an empty graph from unrecognized stack rows without exposing text', () => { - const empty = classifyNativeWaitSample('Call graph:\n\nTotal number in stack:\nBinary Images:\nprivate-image'); - expect(empty).toMatchObject({ available: false, frames: 0, callGraphSeen: true, - shape: { graphLines: 1, nonemptyGraphLines: 0, unrecognizedGraphLines: 0, graphEnd: 'totals', binaryImagesSeen: true } }); - const unfamiliar = classifyNativeWaitSample('Call graph:\n ◇ private-row (in Security)\nBinary Images:\nprivate-image'); - expect(unfamiliar).toMatchObject({ available: false, frames: 0, - shape: { nonemptyGraphLines: 1, unrecognizedGraphLines: 1, nonAsciiGraphLines: 1, imageAnnotatedLines: 1, graphEnd: 'binary_images' } }); - expect(JSON.stringify(unfamiliar)).not.toContain('private'); - expect(JSON.stringify(unfamiliar)).not.toContain('Security'); - }); - - test('a pending launch is sampled once with a deadline before the native launch timeout', async () => { - let resolve!: (value: string) => void; - const pending = new Promise(done => { resolve = done; }); - const started = performance.now(); - const deadlines: number[] = []; - const result = await observePendingBrowserLaunch(() => pending, deadline => { deadlines.push(deadline); resolve('ready'); }, started + 60_000, 5); - expect(result).toBe('ready'); - expect(deadlines).toHaveLength(1); - expect(deadlines[0]).toBeLessThan(started + 30_000); - expect(deadlines[0]).toBeGreaterThan(started + 24_000); - }); - - test('settled launches cancel sampling and exhausted sampling windows do not extend the launch', async () => { - let observations = 0; - const observe = () => { observations++; }; - expect(await observePendingBrowserLaunch(async () => 'ready', observe, performance.now() + 60_000, 5)).toBe('ready'); - const original = new Error('original_launch_failure'); - await expect(observePendingBrowserLaunch(async () => { throw original; }, observe, performance.now() + 60_000, 5)).rejects.toBe(original); - expect(await observePendingBrowserLaunch(async () => { await Bun.sleep(10); return 'ready'; }, observe, performance.now() + 100, 0)).toBe('ready'); - await Bun.sleep(10); - expect(observations).toBe(0); - }); - - test('native wait sampling uses only the observed live child and never writes a stack artifact', () => { - const pid = 12345; - const uid = process.getuid!(); - const child: any = { pid, executable: '/owned/Dia', closeObserved: false, process: { pid, exitCode: null, signalCode: null } }; - const calls: string[][] = []; - const result = sampleOwnedDiaWait(child, uid, child.executable, performance.now() + 10_000, { HOME: root }, - ((command: string, args: string[], options: any) => { - calls.push([command, ...args]); - expect(Number.isInteger(options.timeout)).toBe(true); - expect(options.timeout).toBeGreaterThan(0); - expect(options.timeout).toBeLessThanOrEqual(5_000); - expect(options.killSignal).toBe('SIGKILL'); - if (command === '/bin/ps') return { status: 0, stdout: `${uid} ${pid} ${process.pid} S Dia\n`, stderr: '' }; - return { status: 0, stdout: 'private-header\nCall graph:\n 10 Thread_1 DispatchQueue_1: com.apple.main-thread\n + 10 CFRunLoopRun (in CoreFoundation) private-path\nBinary Images:\nprivate-image', stderr: '' }; - }) as typeof spawnSync); - expect(calls).toEqual([['/bin/ps', '-p', String(pid), '-o', 'uid=,pid=,ppid=,state=,ucomm='], - ['/usr/bin/sample', String(pid), '1', '10', '-file', '/dev/stdout']]); - expect(result).toMatchObject({ available: true, attempted: true, ownedLiveChildConfirmed: true, reason: 'sampled', - waitFamilies: { mainThreadFrameCounts: { runloop: 1 } } }); - expect(JSON.stringify(result)).not.toContain('private-'); - expect(JSON.stringify(result)).not.toContain('CFRunLoopRun'); - }); - - test('sampling refuses changed identity, zombies, and closed roots without attempting a native sample', () => { - const uid = process.getuid!(); - const child: any = { pid: 12345, executable: '/owned/Dia', closeObserved: false, process: { pid: 12345, exitCode: null, signalCode: null } }; - for (const row of [`${uid + 1} 12345 ${process.pid} S Dia`, `${uid} 12345 ${process.pid + 1} S Dia`, - `${uid} 12345 ${process.pid} Z Dia`, `${uid} 12345 ${process.pid} S other`, `${uid} 12346 ${process.pid} S Dia`]) { - let calls = 0; - const result = sampleOwnedDiaWait(child, uid, child.executable, performance.now() + 10_000, {}, - ((command: string) => { calls++; expect(command).toBe('/bin/ps'); return { status: 0, stdout: row, stderr: '' }; }) as typeof spawnSync); - expect(calls).toBe(1); - expect(result.attempted).toBe(false); - } - for (const changed of [{ ...child, closeObserved: true }, { ...child, executable: '/other/Chromium' }, - { ...child, process: { ...child.process, exitCode: 0 } }]) { - const result = sampleOwnedDiaWait(changed, uid, '/owned/Dia', performance.now() + 10_000, {}, (() => { throw new Error('must_not_spawn'); }) as typeof spawnSync); - expect(result).toMatchObject({ available: false, attempted: false }); - } - }); - - test('sampling reports OS permission refusal without escalation or raw failure text', () => { - const uid = process.getuid!(); - const child: any = { pid: 12345, executable: '/owned/Dia', closeObserved: false, process: { pid: 12345, exitCode: null, signalCode: null } }; - const result = sampleOwnedDiaWait(child, uid, child.executable, performance.now() + 10_000, {}, - ((command: string) => command === '/bin/ps' - ? { status: 0, stdout: `${uid} 12345 ${process.pid} S Dia`, stderr: '' } - : { status: 1, stdout: '', stderr: 'Failed to get task for pid: private-process-path. Operation not permitted.' }) as typeof spawnSync); - expect(result).toMatchObject({ available: false, attempted: true, reason: 'sampling_permission_denied' }); - expect(JSON.stringify(result)).not.toContain('private-process'); - }); - - test('child close joining stays within its deadline and refuses an unconfirmed close', async () => { - await expect(joinOwnedBrowserClose({ closed: Promise.resolve(), closeObserved: false } as any, performance.now() + 1000)) - .rejects.toThrow('owned_child_close_unconfirmed'); - await expect(joinOwnedBrowserClose({ closed: new Promise(() => {}), closeObserved: false } as any, performance.now() + 5)) - .rejects.toThrow('operation_timeout'); - await expect(joinOwnedBrowserClose({ closed: Promise.resolve(), closeObserved: true } as any, 0)) - .rejects.toThrow('cleanup_budget_exhausted'); - }); - - for (const phase of ['probe', 'signal']) { - test(`an initial ${phase} error is retained while child reaping still precedes the final absence proof`, async () => { - const facts: Record = { signalSent: false, absenceConfirmed: false }; - const child: any = { pid: 12345, closeObserved: false }; - child.closed = Promise.resolve().then(() => { child.closeObserved = true; }); - const calls: Array<0 | 'SIGKILL'> = []; - await stopOwnedBrowserGroup(child, performance.now() + 1000, facts, (_pid, signal) => { - calls.push(signal); - if (!child.closeObserved) { - if (phase === 'signal' && signal === 0) return; - throw Object.assign(new Error('private-probe-error'), { code: 'EPERM', errno: 1 }); - } - throw Object.assign(new Error('gone'), { code: 'ESRCH' }); - }); - expect(calls).toEqual(phase === 'probe' ? [0, 0] : [0, 'SIGKILL', 0]); - expect(facts).toMatchObject({ stage: 'completed', signalSent: false, childCloseObserved: true, absenceConfirmed: true, - initialSignalFailure: { stage: phase === 'probe' ? 'probe_before_signal' : 'signal', code: 'EPERM', errno: 1 } }); - expect(JSON.stringify(facts)).not.toContain('private-probe-error'); - }); - } - - test('permission errors and zombies never replace the required child close and actual group absence', async () => { - const facts = { signalSent: false, absenceConfirmed: false }; - const waiting: any = { pid: 12345, closed: new Promise(() => {}), closeObserved: false }; - const denied = () => { throw Object.assign(new Error('denied'), { code: 'EPERM' }); }; - await expect(stopOwnedBrowserGroup(waiting, performance.now() + 10, facts, denied)).rejects.toThrow('operation_timeout'); - expect(facts.absenceConfirmed).toBe(false); - const closed: any = { pid: 12345, closed: Promise.resolve(), closeObserved: true }; - await expect(stopOwnedBrowserGroup(closed, performance.now() + 1000, facts, denied)).rejects.toMatchObject({ code: 'EPERM' }); - expect(facts.absenceConfirmed).toBe(false); - await expect(stopOwnedBrowserGroup(closed, performance.now() + 10, facts, () => {})).rejects.toThrow('owned_process_group_still_live'); - expect(facts.absenceConfirmed).toBe(false); - }); - for (const [error, category] of [ - [new Error('browserType.launchPersistentContext: browser_launch_policy_rejected synthetic-private-value'), 'launch_policy_rejected'], - [new Error('background_browser_ownership_failed'), 'ownership_unconfirmed'], - [new Error('background_browser_startup_page_rejected'), 'startup_page_rejected'], - [new Error('background_browser_render_failed'), 'render_mismatch'], - [Object.assign(new Error('synthetic-private-value'), { name: 'TimeoutError' }), 'operation_timeout'], - [new Error('native_operation_timed_out'), 'operation_timeout'], - [new Error('operation_timeout'), 'operation_timeout'], - [new Error('qualification_budget_exhausted'), 'operation_timeout'], - [new Error('source_process_ownership_unconfirmed'), 'ownership_unconfirmed'], - [new Error('destination_process_ownership_unconfirmed'), 'ownership_unconfirmed'], - [new Error('onboarding_or_external_page'), 'startup_page_rejected'], - [Object.assign(new Error('synthetic-private-value'), { code: 'ENOENT' }), 'executable_unavailable'], - [Object.assign(new Error('synthetic-private-value'), { code: 'EACCES' }), 'permission_denied'], - [{ name: 'ResolveMessage', code: 'ERR_MODULE_NOT_FOUND', message: 'synthetic-private-value' }, 'module_unavailable'], - [Object.assign(new Error('synthetic-private-value'), { code: 'MODULE_NOT_FOUND' }), 'module_unavailable'], - [Object.assign(new Error('synthetic-private-value'), { code: 'ERR_PACKAGE_PATH_NOT_EXPORTED' }), 'module_export_unavailable'], - [Object.assign(new Error('synthetic-private-value'), { code: 'ERR_REQUIRE_ESM' }), 'module_format_error'], - [new RangeError('synthetic-private-value'), 'invalid_runtime_range'], - [new TypeError('synthetic-private-value'), 'runtime_type_error'], - [new Error('dyld[123]: Library not loaded: synthetic-private-value'), 'dynamic_library_error'], - [new Error('code signature invalid: synthetic-private-value'), 'code_signing_error'], - [new Error('ProcessSingleton synthetic-private-value'), 'browser_profile_unavailable'], - [new Error('bootstrap_check_in failed synthetic-private-value'), 'graphics_or_bootstrap_error'], - [new Error('Target page, context or browser has been closed synthetic-private-value'), 'target_closed'], - [new Error('Protocol error: synthetic-private-value'), 'protocol_error'], - [new Error('synthetic-private-value'), 'unclassified_browser_error'], - [{ code: 'synthetic-private-value', message: 'synthetic-private-value' }, 'unclassified_browser_error'], - ] as const) { - test(`browser diagnostics return only the allowlisted ${category} category`, () => { - expect(browserPreflightError(error)).toBe(category); - expect(browserPreflightError(error)).not.toContain('synthetic-private-value'); - }); - } - - test('module-load facts retain only known error identifiers and known dependency filenames', () => { - const snapshot = realpathSync(mkdtempSync(path.join(root, 'module-facts-'))); - const packageDirectory = path.join(snapshot, 'node_modules/playwright'); - mkdirSync(packageDirectory, { recursive: true }); - writeFileSync(path.join(packageDirectory, 'package.json'), '{}', { mode: 0o600 }); - const facts = playwrightModuleLoadFacts(snapshot, { name: 'ResolveMessage', code: 'ERR_MODULE_NOT_FOUND', - message: "Cannot find package 'playwright' imported from /synthetic-private-value/worker.ts" }); - expect(facts.errorType).toBe('ResolveMessage'); - expect(facts.errorCode).toBe('ERR_MODULE_NOT_FOUND'); - expect(facts.requestedModule).toBe('playwright'); - expect(facts.files['playwright/package.json']).toEqual({ exists: true, readable: true, ownedByCurrentUid: true, insideSnapshot: true }); - expect(facts.files['playwright-core/lib/coreBundle.js'].exists).toBe(false); - expect(JSON.stringify(facts)).not.toContain('synthetic-private-value'); - expect(JSON.stringify(facts)).not.toContain(snapshot); - const unknown = playwrightModuleLoadFacts(snapshot, { name: 'synthetic-private-value', code: 'synthetic-private-value', message: "Cannot find package 'synthetic-private-value'" }); - expect(unknown.errorType).toBe('unclassified'); - expect(unknown.errorCode).toBe('unclassified'); - expect(unknown.requestedModule).toBe('unclassified'); - expect(JSON.stringify(unknown)).not.toContain('synthetic-private-value'); - }); - - test('Keychain snapshots preserve exact quoted paths without shell parsing', () => { - expect(parseKeychainPaths(' "/Users/runner/Library/Keychains/login.keychain-db"\n "/tmp/fixture keychain.keychain-db"\n')) - .toEqual(['/Users/runner/Library/Keychains/login.keychain-db', '/tmp/fixture keychain.keychain-db']); - for (const output of ['', 'not-json', '"relative-path"', '42', '"/valid/path"\ninvalid']) { - expect(() => parseKeychainPaths(output)).toThrow(); - } - }); - - test('fresh users can have an empty user search list and no default Keychain', () => { - const calls: string[][] = []; - const snapshot = captureUserKeychains({ HOME: root }, [root], 1000, (args, timeout) => { - calls.push(args); - expect(timeout).toBeGreaterThan(0); - expect(timeout).toBeLessThanOrEqual(1000); - return args[0] === 'list-keychains' ? { status: 0, stdout: '', stderr: '' } - : { status: 1, stdout: '', stderr: 'security: SecKeychainCopyDomainDefault user: A default keychain could not be found.\n' }; - }); - expect(snapshot).toEqual({ search: [], default: [] }); - expect(calls).toEqual([['list-keychains', '-d', 'user'], ['default-keychain', '-d', 'user']]); - }); - - test('computed Keychain timeouts reach real spawnSync as bounded integer milliseconds', () => { - let reads = 0; - const times = [0.125, 0.5, 5.75]; - const clock = spyOn(performance, 'now').mockImplementation(() => times[Math.min(reads++, times.length - 1)]); - const timeouts: number[] = []; - const calls: string[][] = []; - try { - const snapshot = captureUserKeychains({ HOME: root }, [root], 10_000, (args, timeout) => { - const result = spawnSync(process.execPath, ['--no-env-file', '--no-install', '--no-macros', - `--config=${process.platform === 'win32' ? 'NUL' : '/dev/null'}`, '-e', 'process.exit(0)'], { - cwd: root, env: { HOME: root, PATH: path.dirname(process.execPath) }, encoding: 'utf8', timeout, - }); - expect(result.status).toBe(0); - expect(result.error).toBeUndefined(); - timeouts.push(timeout); - calls.push(args); - return result; - }); - expect(snapshot).toEqual({ search: [], default: [] }); - expect(timeouts).toEqual([9999, 9994]); - expect(calls).toEqual([['list-keychains', '-d', 'user'], ['default-keychain', '-d', 'user']]); - } finally { - clock.mockRestore(); - } - }); - - test('an expired or sub-millisecond Keychain budget never becomes an unbounded subprocess', () => { - const clock = spyOn(performance, 'now').mockReturnValue(100); - let commands = 0; - try { - for (const budget of [0.75, 0, -1, NaN, Infinity]) { - expect(() => captureUserKeychains({ HOME: root }, [root], budget, () => { - commands++; - return { status: 0, stdout: '', stderr: '' }; - })).toThrow('user_keychain_probe_timeout'); - } - expect(commands).toBe(0); - } finally { - clock.mockRestore(); - } - }); - - test('permission, securityd, and transport errors are never mistaken for no default Keychain', () => { - for (const result of [ - { status: 1, stdout: '', stderr: 'security: SecKeychainCopyDefault: User interaction is not allowed.' }, - { status: 1, stdout: '', stderr: 'security: SecKeychainCopyDomainDefault system: A default keychain could not be found.' }, - { status: 1, stdout: '', stderr: 'synthetic-private-error' }, - { status: 0, stdout: '', stderr: 'synthetic-private-error' }, - { status: 1, stdout: 'unexpected-data', stderr: 'security: SecKeychainCopyDefault: A default keychain could not be found.' }, - { status: null, stdout: '', stderr: '', error: new Error('synthetic-private-error') }, - ]) expect(() => parseDefaultKeychain(result)).toThrow('user_default_keychain_unavailable'); - expect(parseDefaultKeychain({ status: 0, stdout: '', stderr: '' })).toEqual([]); - expect(parseDefaultKeychain({ status: 1, stdout: '', stderr: 'security: SecKeychainCopyDefault: A default keychain could not be found.' })).toEqual([]); - }); - - test('the snapshot boundary rejects System Keychain fallback and paths outside the owned home', () => { - for (const file of ['/Library/Keychains/System.keychain', '/System/Library/Keychains/SystemRootCertificates.keychain', '/unowned/keychain']) { - expect(() => captureUserKeychains({ HOME: root }, [root], 1000, args => ({ status: 0, - stdout: args[0] === 'list-keychains' ? JSON.stringify(file) : '', stderr: '' }))) - .toThrow('keychain_outside_owned_home_refused'); - } - }); - - test('a fresh Keychain home gains only owned standard directories, not a fabricated preference file', () => { - const home = realpathSync(mkdtempSync(path.join(root, 'keychain-home-'))); - expect(prepareKeychainHome(home)).toEqual({ before: { Library: false, 'Library/Preferences': false, 'Library/Keychains': false }, directoriesReady: true }); - for (const directory of ['Library', 'Library/Preferences', 'Library/Keychains']) { - expect(lstatSync(path.join(home, directory)).uid).toBe(process.getuid!()); - expect(lstatSync(path.join(home, directory)).isDirectory()).toBe(true); - } - const preferences = path.join(home, 'Library/Preferences/com.apple.security.plist'); - expect(existsSync(preferences)).toBe(false); - expect(existsSync(path.join(home, 'Library/Safari'))).toBe(false); - writeFileSync(preferences, 'opaque fixture preferences', { mode: 0o600 }); - expect(prepareKeychainHome(home).before).toEqual({ Library: true, 'Library/Preferences': true, 'Library/Keychains': true }); - expect(readFileSync(preferences, 'utf8')).toBe('opaque fixture preferences'); - }); - - test('home preparation rejects a linked or unowned home without writing through it', () => { - const home = realpathSync(mkdtempSync(path.join(root, 'linked-home-'))); - const elsewhere = realpathSync(mkdtempSync(path.join(root, 'other-home-'))); - symlinkSync(elsewhere, path.join(home, 'Library'), 'dir'); - expect(() => prepareKeychainHome(home)).toThrow('keychain_home_unsafe'); - expect(readdirSync(elsewhere)).toEqual([]); - expect(() => prepareKeychainHome(elsewhere, process.getuid!() + 1)).toThrow('keychain_home_unsafe'); - expect(readdirSync(elsewhere)).toEqual([]); - }); - - for (const mismatch of ['search-empty', 'default-empty', 'search-path', 'default-path', 'search-error', 'default-error', 'read-mismatch', 'read-error']) { - test(`Keychain diagnostics observe the explicit read independently of ${mismatch}`, () => { - const directory = realpathSync(mkdtempSync(path.join(root, 'keychain-facts-'))); - const keychain = path.join(directory, 'fixture.keychain-db'); - const other = path.join(directory, 'other.keychain-db'); - writeFileSync(keychain, 'opaque synthetic keychain', { mode: 0o600 }); - writeFileSync(other, 'other synthetic keychain', { mode: 0o600 }); - const expected = 'synthetic-private-equality-value'; - const calls: string[][] = []; - const facts = observeFixtureKeychain({ HOME: directory }, [directory], keychain, expected, 1000, (args, timeout) => { - expect(Number.isInteger(timeout)).toBe(true); - expect(timeout).toBeGreaterThan(0); - calls.push(args); - if (args[0] === 'list-keychains') return mismatch === 'search-error' - ? { status: 1, stdout: '', stderr: 'synthetic-private-error' } - : { status: 0, stdout: mismatch === 'search-empty' ? '' : JSON.stringify(mismatch === 'search-path' ? other : keychain), stderr: '' }; - if (args[0] === 'default-keychain') return mismatch === 'default-error' - ? { status: 1, stdout: '', stderr: 'synthetic-private-error' } - : mismatch === 'default-empty' - ? { status: 1, stdout: '', stderr: 'security: SecKeychainCopyDomainDefault user: A default keychain could not be found.' } - : { status: 0, stdout: JSON.stringify(mismatch === 'default-path' ? other : keychain), stderr: '' }; - if (mismatch === 'read-error') return { status: 1, stdout: '', stderr: 'synthetic-private-error' }; - return { status: 0, stdout: mismatch === 'read-mismatch' ? 'other synthetic value' : expected + '\n', stderr: '' }; - }); - expect(calls).toEqual([['list-keychains', '-d', 'user'], ['default-keychain', '-d', 'user'], - ['find-generic-password', '-s', 'Gstack Native Probe', '-w', keychain]]); - expect(facts.searchCount).toBe(mismatch === 'search-error' ? null : mismatch === 'search-empty' ? 0 : 1); - expect(facts.searchPathMatches).toBe(!mismatch.startsWith('search-')); - expect(facts.defaultCount).toBe(mismatch === 'default-error' ? null : mismatch === 'default-empty' ? 0 : 1); - expect(facts.defaultPathMatches).toBe(!mismatch.startsWith('default-')); - expect(facts.explicitReadAttempted).toBe(true); - expect(facts.explicitReadSucceeded).toBe(mismatch !== 'read-error'); - expect(facts.explicitReadMatches).toBe(!mismatch.startsWith('read-')); - expect(JSON.stringify(facts)).not.toContain(expected); - expect(JSON.stringify(facts)).not.toContain('synthetic-private-error'); - expect(JSON.stringify(facts)).not.toContain(keychain); - }); - } - - test('Dia Keychain diagnostics distinguish both HOME environments without configuring the shadow home', () => { - const directory = realpathSync(mkdtempSync(path.join(root, 'dual-keychain-'))); - const registered = path.join(directory, 'registered'); - const shadow = path.join(directory, 'shadow'); - mkdirSync(registered); - mkdirSync(shadow); - prepareKeychainHome(registered); - writeFileSync(path.join(registered, 'Library/Preferences/com.apple.security.plist'), 'opaque private fixture preference'); - const keychain = path.join(directory, 'fixture.keychain-db'); - writeFileSync(keychain, 'opaque synthetic keychain', { mode: 0o600 }); - const expected = 'synthetic-private-dual-home-value'; - const environments = { keychainHome: { HOME: registered }, profileHome: { HOME: shadow } }; - const calls: Array<{ home: string; args: string[] }> = []; - const observed = observeDiaKeychainEnvironments(environments, [directory], keychain, expected, 20_000, (env, args, timeout) => { - expect(Number.isInteger(timeout)).toBe(true); - expect(timeout).toBeGreaterThan(0); - expect(timeout).toBeLessThanOrEqual(10_000); - calls.push({ home: env.HOME, args }); - if (args[0] === 'list-keychains') return { status: 0, stdout: env.HOME === registered ? JSON.stringify(keychain) : '', stderr: '' }; - if (args[0] === 'default-keychain') return env.HOME === registered - ? { status: 0, stdout: JSON.stringify(keychain), stderr: '' } - : { status: 1, stdout: '', stderr: 'security: SecKeychainCopyDomainDefault user: A default keychain could not be found.' }; - expect(args.slice(0, 4)).toEqual(['find-generic-password', '-s', 'Dia Safe Storage', '-w']); - return { status: 0, stdout: expected, stderr: '' }; - }); - expect(observed.firstFailure).toEqual({ environment: 'profileHome', check: 'search_path' }); - expect(observed.environments.keychainHome).toMatchObject({ searchCount: 1, searchPathMatches: true, defaultCount: 1, defaultPathMatches: true, - explicitReadMatches: true, lookupReadAttempted: true, lookupReadMatches: true, preferencesDirectoryExists: true, preferencesFileExists: true }); - expect(observed.environments.profileHome).toMatchObject({ searchCount: 0, searchPathMatches: false, defaultCount: 0, defaultPathMatches: false, - explicitReadMatches: true, lookupReadAttempted: false, preferencesDirectoryExists: false, preferencesFileExists: false }); - expect(calls).toHaveLength(7); - expect(calls.filter(call => call.home === shadow)).toHaveLength(3); - expect(calls.some(call => call.args[0] === 'default-keychain' && call.args.includes('-s'))).toBe(false); - expect(existsSync(path.join(shadow, 'Library'))).toBe(false); - const serialized = JSON.stringify(observed); - for (const privateValue of [expected, registered, shadow, keychain, 'opaque private']) expect(serialized).not.toContain(privateValue); - }); - - for (const failure of ['search', 'default', 'explicit_read']) { - test(`Dia diagnostic refuses unqualified lookup when the owned ${failure} proof fails`, () => { - const directory = realpathSync(mkdtempSync(path.join(root, 'guarded-keychain-'))); - const keychain = path.join(directory, 'fixture.keychain-db'); - writeFileSync(keychain, 'opaque synthetic keychain', { mode: 0o600 }); - let implicitCalls = 0; - const result = observeFixtureKeychain({ HOME: directory }, [directory], keychain, 'expected-private-value', 1000, args => { - if (args[0] === 'list-keychains') return { status: 0, stdout: failure === 'search' ? '' : JSON.stringify(keychain), stderr: '' }; - if (args[0] === 'default-keychain') return { status: 0, stdout: failure === 'default' ? '' : JSON.stringify(keychain), stderr: '' }; - if (args.length === 4) implicitCalls++; - return { status: 0, stdout: failure === 'explicit_read' ? 'wrong-private-value' : 'expected-private-value', stderr: '' }; - }, 'Dia Safe Storage'); - expect(result.explicitReadAttempted).toBe(true); - expect(result.lookupReadAttempted).toBe(false); - expect(implicitCalls).toBe(0); - }); - } - - test('both Keychain environments remain observable while the first original validation failure is retained', () => { - const directory = realpathSync(mkdtempSync(path.join(root, 'keychain-failures-'))); - const keychain = path.join(directory, 'fixture.keychain-db'); - writeFileSync(keychain, 'opaque synthetic keychain', { mode: 0o600 }); - const environments = { keychainHome: { HOME: directory }, profileHome: { HOME: directory, MARKER: 'shadow' } }; - for (const keychainSearchFails of [true, false]) { - const homesObserved = new Set>(); - const observed = observeDiaKeychainEnvironments(environments, [directory], keychain, 'expected-private-value', 20_000, (env, args) => { - homesObserved.add(env); - if (args[0] === 'list-keychains') return { status: 0, - stdout: env === environments.profileHome || keychainSearchFails ? '' : JSON.stringify(keychain), stderr: '' }; - if (args[0] === 'default-keychain') return { status: 1, stdout: '', stderr: 'private-default-error' }; - return { status: 0, stdout: 'wrong-private-value', stderr: '' }; - }); - expect(homesObserved.size).toBe(2); - expect(observed.firstFailure).toEqual({ environment: keychainSearchFails ? 'keychainHome' : 'profileHome', check: 'search_path' }); - expect(observed.environments.keychainHome).toMatchObject({ defaultCount: null, explicitReadAttempted: true, explicitReadMatches: false }); - expect(observed.environments.profileHome).toMatchObject({ defaultCount: null, explicitReadAttempted: true, explicitReadMatches: false }); - expect(JSON.stringify(observed)).not.toContain('private-default-error'); - expect(JSON.stringify(observed)).not.toContain('wrong-private-value'); - } - }); - - test('Dia environment validation preserves successful and explicit-read-only outcomes', () => { - const directory = realpathSync(mkdtempSync(path.join(root, 'keychain-outcomes-'))); - const keychain = path.join(directory, 'fixture.keychain-db'); - writeFileSync(keychain, 'opaque synthetic keychain', { mode: 0o600 }); - const environments = { keychainHome: { HOME: directory }, profileHome: { HOME: directory } }; - for (const readMismatch of [false, true]) { - const observed = observeDiaKeychainEnvironments(environments, [directory], keychain, 'expected-private-value', 20_000, (env, args) => { - if (args[0] === 'list-keychains' || args[0] === 'default-keychain') return { status: 0, stdout: JSON.stringify(keychain), stderr: '' }; - return { status: 0, stdout: readMismatch && env === environments.keychainHome ? 'wrong-private-value' : 'expected-private-value', stderr: '' }; - }); - if (readMismatch) expect(observed.firstFailure).toEqual({ environment: 'keychainHome', check: 'explicit_read' }); - else expect(observed.firstFailure).toBeUndefined(); - expect(observed.environments.profileHome).toMatchObject({ searchPathMatches: true, defaultPathMatches: true, explicitReadMatches: true, - lookupReadAttempted: true, lookupReadMatches: true }); - } - }); - - test('an exhausted dual-environment diagnostic budget launches no Keychain commands', () => { - const directory = realpathSync(mkdtempSync(path.join(root, 'keychain-budget-'))); - const keychain = path.join(directory, 'fixture.keychain-db'); - writeFileSync(keychain, 'opaque synthetic keychain', { mode: 0o600 }); - let calls = 0; - const observed = observeDiaKeychainEnvironments({ keychainHome: { HOME: directory }, profileHome: { HOME: directory } }, - [directory], keychain, 'expected-private-value', 0, () => { calls++; throw new Error('must_not_spawn'); }); - expect(calls).toBe(0); - expect(observed.environments.keychainHome).toMatchObject({ searchCount: null, defaultCount: null, explicitReadAttempted: false, lookupReadAttempted: false }); - expect(observed.environments.profileHome).toMatchObject({ searchCount: null, defaultCount: null, explicitReadAttempted: false, lookupReadAttempted: false }); - expect(observed.firstFailure).toEqual({ environment: 'keychainHome', check: 'search_path' }); - }); - - test('an originally absent default is restored by deleting only the created fixture, never by a null default setter', () => { - expect(fixtureKeychainRestoreCommands({ search: [], default: [] }, '/owned/fixture.keychain-db', true)).toEqual([ - ['delete-keychain', '/owned/fixture.keychain-db'], ['list-keychains', '-d', 'user', '-s'], - ]); - expect(fixtureKeychainRestoreCommands({ search: [], default: [] }, '/owned/fixture.keychain-db', false)).toEqual([ - ['list-keychains', '-d', 'user', '-s'], - ]); - }); - - test('an existing default is restored before deleting the fixture, and preexisting fixture references are refused', () => { - const before = { search: ['/owned/prior.keychain-db', '/owned/other.keychain-db'], default: ['/owned/prior.keychain-db'] }; - expect(fixtureKeychainRestoreCommands(before, '/owned/fixture.keychain-db', true)).toEqual([ - ['default-keychain', '-d', 'user', '-s', '/owned/prior.keychain-db'], - ['delete-keychain', '/owned/fixture.keychain-db'], - ['list-keychains', '-d', 'user', '-s', '/owned/prior.keychain-db', '/owned/other.keychain-db'], - ]); - expect(() => fixtureKeychainRestoreCommands(before, '/owned/prior.keychain-db', true)).toThrow('fixture_keychain_not_fresh'); - }); - - test('fresh account cleanup requires the same GUID, UID, private group, and registered home', () => { - const identity = { guid: 'A38AC39B-5960-4F0C-B02F-C32A4F625B33', uid: 23456, gid: 23456, home: '/private/tmp/fixture/home' }; - const record = parseDirectoryRecord(`GeneratedUID: ${identity.guid}\nUniqueID: ${identity.uid}\nPrimaryGroupID: ${identity.gid}\nNFSHomeDirectory: ${identity.home}\n`); - expect(ownsFreshAccount(record, identity)).toBe(true); - for (const key of ['GeneratedUID', 'UniqueID', 'PrimaryGroupID', 'NFSHomeDirectory']) { - expect(ownsFreshAccount({ ...record, [key]: 'different' }, identity)).toBe(false); - } - expect(() => parseDirectoryRecord('UniqueID: 23456\nUniqueID: 501')).toThrow('invalid_directory_record'); - }); - - test('user-domain absence requires an explicit matching-domain response, not an arbitrary command failure', () => { - for (const status of [64, 113]) { - const absent = classifyUserDomain(23456, { status, stdout: '', stderr: 'Bad request.\nCould not find domain for user uid: 23456\n' }); - expect(absent.state).toBe('absent'); - expect(absent.uid).toBe(23456); - } - for (const result of [ - { status: 1, stdout: '', stderr: 'sudo: a password is required' }, - { status: 113, stdout: '', stderr: 'Could not find domain for user uid: 23457' }, - { status: 113, stdout: '', stderr: 'Could not find domain for user gui: 23456' }, - { status: 113, stdout: '', stderr: 'synthetic-private-error' }, - { status: null, stdout: '', stderr: '', error: new Error('synthetic-private-error') }, - ]) expect(classifyUserDomain(23456, result).state).toBe('unavailable'); - expect(() => classifyUserDomain(0, { status: 0, stdout: '', stderr: '' })).toThrow('invalid_fresh_user_domain'); - }); - - test('user-domain inspection records only safe state facts and notices an unexpected GUI domain', () => { - const present = classifyUserDomain(23456, { status: 0, stdout: 'user/23456 = {\n type = user\n synthetic-private-value\n}', stderr: '' }); - expect(present).toMatchObject({ uid: 23456, state: 'present', hasGuiDomain: false, exitCode: 0 }); - expect(JSON.stringify(present)).not.toContain('synthetic-private-value'); - expect(classifyUserDomain(23456, { status: 0, stdout: 'user/23456 = {\n subdomains = { gui/23456 }\n}', stderr: '' }).hasGuiDomain).toBe(true); - expect(classifyUserDomain(23456, { status: 0, stdout: 'user/23456 = {\n session = Aqua\n}', stderr: '' }).hasGuiDomain).toBe(true); - expect(classifyUserDomain(23456, { status: 0, stdout: 'user/501 = { }', stderr: '' }).state).toBe('unavailable'); - }); - - test('domain structure retains counts and creator correlation, never arbitrary labels or environment values', () => { - const stdout = `user/23456 = { -\ttype = user -\thandle = 23456 -\tactive count = 3 -\ton-demand count = 0 -\tservice count = 2 -\tactive service count = 1 -\texternal activation count = 0 -\tin-progress bootstraps = 0 -\tpended requests = 0 -\tcreator = launchctl.4567 -\tcreator euid = 0 -\tenvironment = { -\t\tsynthetic-private-variable => synthetic-private-value -\t\tservice count = 999 -\t} -\tservices = { -\t\t234 0 synthetic-private-service -\t\t0 0 synthetic-private-job -\t} -\tsubdomains = { -\t\tsynthetic-private-child -\t} -\tunmanaged processes = { -\t} -\tendpoints = {} -}`; - const observation = classifyUserDomain(23456, { status: 0, stdout, stderr: '' }, 4567); - expect(observation.structure).toMatchObject({ complete: true, type: 'user', handleMatchesUid: true, creator: 'launchctl', creatorIsProbe: true, - counts: { 'service count': 2, 'active service count': 1, 'creator euid': 0, 'in-progress bootstraps': 0 }, - sectionNonemptyLines: { services: 2, subdomains: 1, 'unmanaged processes': 0, endpoints: 0, jobs: null } }); - expect(JSON.stringify(observation)).not.toContain('synthetic-private'); - expect(JSON.stringify(observation)).not.toContain('4567'); - expect(classifyUserDomain(23456, { status: 0, stdout, stderr: '' }, 4568).structure?.creatorIsProbe).toBe(false); - expect(classifyUserDomain(23456, { status: 0, stdout, stderr: '' }).structure?.creatorIsProbe).toBeNull(); - expect(classifyUserDomain(23456, { status: 0, stdout: stdout.replace('launchctl.4567', 'synthetic-private-creator.4567'), stderr: '' }, 4567).structure?.creator).toBe('other'); - }); - - test('missing, malformed, duplicate, and incomplete domain facts never become empty-baseline evidence', () => { - const minimal = 'user/23456 = {\n\ttype = user\n\thandle = 23456\n}'; - const observation = classifyUserDomain(23456, { status: 0, stdout: minimal, stderr: '' }); - expect(observation.structure?.counts['service count']).toBeNull(); - expect(observation.structure?.sectionNonemptyLines.services).toBeNull(); - expect(observation.structure?.creatorIsProbe).toBeNull(); - for (const stdout of [minimal.slice(0, -1), minimal.replace('\thandle', '\ttype = user\n\thandle'), - minimal.replace('\thandle = 23456', '\tservices = {\n\t\tsynthetic-private-service')]) { - expect(classifyUserDomain(23456, { status: 0, stdout, stderr: '' }).structure?.complete).toBe(false); - } - for (const value of ['-1', 'NaN', '1.5', '9007199254740992', 'synthetic-private-value']) { - const stdout = minimal.replace('\thandle', '\tservice count = ' + value + '\n\thandle'); - expect(classifyUserDomain(23456, { status: 0, stdout, stderr: '' }).structure?.counts['service count']).toBeNull(); - } - }); - - test('known bracketed creator syntax is matched exactly while unsupported spellings remain unknown', () => { - const fixture = (creator: string) => classifyUserDomain(23456, { status: 0, - stdout: `user/23456 = {\n\ttype = user\n\tcreator = ${creator}\n}`, stderr: '' }, 4567); - expect(fixture('launchctl[4567]').structure?.creatorIsProbe).toBe(true); - expect(fixture('launchctl[4568]').structure?.creatorIsProbe).toBe(false); - for (const creator of ['launchctl(4567)', 'launchctl[4567] extra', 'other[4567]', 'launchctl[0]', 'launchctl[4567)']) { - expect(fixture(creator).structure?.creatorIsProbe).toBeNull(); - expect(fixture(creator).structure?.creator).toBe('other'); - } - }); - - test('parent-domain observation extracts only candidate UID membership from complete subdomains', () => { - for (const [header, target, gui] of [ - ['system', 'user/23456', 'gui/23456'], - ['com.apple.xpc.launchd.domain.system', 'com.apple.xpc.launchd.domain.user.23456', 'com.apple.xpc.launchd.user.domain.23456.100007.Aqua'], - ]) { - const stdout = `${header} = {\n\ttype = system\n\tsubdomains = {\n\t\t${target}\n\t\t${gui}\n\t\tpid/15\n\t}\n}`; - expect(classifyParentDomain(23456, { status: 0, stdout, stderr: '' })).toMatchObject({ state: 'present', parseStage: 'parsed', - subdomainCount: 3, matchingUserDomains: 1, matchingGuiDomains: 1, unrecognizedEntries: 0 }); - } - const stdout = `system = { -\ttype = system -\tenvironment = { -\t\tsynthetic-private-name => user/23456 -\t\tsubdomains = { -\t\t\tuser/23456 -\t\t} -\t} -\tsubdomains = { -\t\tuser/234560 -\t\tgui/501 -\t\tpid/123 -\t\tsession/100007 -\t\tcom.apple.xpc.launchd.domain.pid.synthetic-private-process.23456 -\t} -\tservices = { -\t\tsynthetic-private-service-user/23456 -\t} -}`; - const observation = classifyParentDomain(23456, { status: 0, stdout, stderr: '' }); - expect(observation).toMatchObject({ state: 'absent', parseStage: 'parsed', subdomainCount: 5, matchingUserDomains: 0 }); - expect(JSON.stringify(observation)).not.toContain('synthetic-private'); - expect(JSON.stringify(observation)).not.toContain('234560'); - }); - - test('parent-domain absence refuses incomplete, missing, duplicate, nested-only, or unknown subdomain output', () => { - const empty = 'system = {\n\ttype = system\n\tsubdomains = {}\n}'; - expect(classifyParentDomain(23456, { status: 0, stdout: empty, stderr: '' }).state).toBe('absent'); - for (const stdout of [empty.slice(0, -1), empty.replace('system = {', 'user/23456 = {'), - empty.replace('\tsubdomains = {}\n', ''), empty.replace('\tsubdomains = {}', '\tsubdomains = {}\n\tsubdomains = {}'), - empty.replace('type = system', 'type = user'), - empty.replace('\tsubdomains = {}', '\tenvironment = {\n\t\tsubdomains = {}\n\t}'), - empty.replace('subdomains = {}', 'subdomains = {\n\t\tunknown-private-domain\n\t}'), - empty.replace('subdomains = {}', 'subdomains = {\n\t\tuser/23456\n\t\tunknown-private-domain\n\t}')]) { - const observation = classifyParentDomain(23456, { status: 0, stdout, stderr: '' }); - expect(observation.state).toBe('unavailable'); - expect(JSON.stringify(observation)).not.toContain('private-domain'); - } - expect(classifyParentDomain(23456, { status: 1, stdout: empty, stderr: 'synthetic-private-error' }).state).toBe('unavailable'); - expect(classifyParentDomain(23456, { status: 0, stdout: empty, stderr: '', error: new Error('synthetic-private-error') }).state).toBe('unavailable'); - expect(classifyParentDomain(23456, { status: 0, stdout: empty + ' '.repeat(1024 * 1024), stderr: '' }).parseStage).toBe('oversized'); - }); - - test('the registered parent observer queries only the existing system domain under its original bounds', () => { - const env = { HOME: root, PATH: '/usr/bin:/bin' }; - const observation = inspectParentDomain(23456, performance.now() + 10_000, env, - ((command: string, args: string[], options: any) => { - expect(command).toBe('/usr/bin/sudo'); - expect(args).toEqual(['-n', '/bin/launchctl', 'print', 'system']); - expect(options.env).toBe(env); - expect(options.maxBuffer).toBe(1024 * 1024); - expect(Number.isInteger(options.timeout)).toBe(true); - expect(options.timeout).toBeGreaterThan(0); - expect(options.timeout).toBeLessThanOrEqual(3_000); - return { status: 0, stdout: 'system = {\n\ttype = system\n\tsubdomains = {}\n}', stderr: '' }; - }) as typeof spawnSync); - expect(observation.state).toBe('absent'); - const never = (() => { throw new Error('must_not_spawn'); }) as typeof spawnSync; - expect(() => inspectParentDomain(501, performance.now() + 10_000, {}, never)).toThrow('invalid_fresh_user_domain'); - for (const deadline of [0, NaN, Infinity]) expect(() => inspectParentDomain(23456, deadline, {}, never)).toThrow('fresh_launcher_deadline'); - }); - - test('the registered UID observer filters numeric global ps rows without resolving an unregistered account', () => { - const env = { HOME: root, PATH: '/usr/bin:/bin' }; - const observation = inspectUidProcesses(23456, performance.now() + 10_000, env, - ((command: string, args: string[], options: any) => { - expect(command).toBe('/bin/ps'); - expect(args).toEqual(['-axo', 'uid=,pid=,ppid=,state=,ucomm=']); - expect(options.env).toBe(env); - expect(options.maxBuffer).toBe(128 * 1024); - expect(Number.isInteger(options.timeout)).toBe(true); - expect(options.timeout).toBeGreaterThan(0); - expect(options.timeout).toBeLessThanOrEqual(2_000); - return { status: 0, stdout: '501 300 1 S synthetic-private-name\n23456 400 1 S distnoted\n', stderr: '' }; - }) as typeof spawnSync); - expect(observation).toMatchObject({ available: true, count: 1, processes: [{ pid: 400, ppid: 1, state: 'S', basename: 'distnoted' }] }); - expect(JSON.stringify(observation)).not.toContain('synthetic-private'); - expect(inspectUidProcesses(23456, performance.now() + 10_000, {}, (() => ({ status: 0, - stdout: '501 300 1 S synthetic-private-name\n', stderr: '' })) as typeof spawnSync)).toMatchObject({ available: true, count: 0, processes: [] }); - for (const result of [ - { status: 1, stdout: '', stderr: '' }, { status: 0, stdout: '', stderr: '' }, - { status: 0, stdout: 'truncated-private-row', stderr: '' }, - { status: null, stdout: null, stderr: null, error: new Error('synthetic-private-error') }, - ]) expect(inspectUidProcesses(23456, performance.now() + 10_000, {}, (() => result) as unknown as typeof spawnSync)).toEqual({ available: false }); - }); - - test('numeric UID process filtering runs through the real global process table', () => { - const observation = inspectUidProcesses(23456, performance.now() + 10_000, { HOME: root, PATH: '/usr/bin:/bin' }); - expect(observation.available).toBe(true); - expect('count' in observation).toBe(true); - }); - - test('the registered domain probe binds its creator check to the shell exec PID and bounds the query', () => { - const env = { PATH: '/usr/bin:/bin', HOME: root }; - let called = false; - const observation = inspectUserDomain(23456, performance.now() + 10_000, env, ((command: string, args: string[], options: any) => { - called = true; - expect(command).toBe('/usr/bin/sudo'); - expect(args).toEqual(['-n', '/bin/sh', '-c', 'printf "GSTACK_DIA_DOMAIN_PROBE_PID=%s\\n" "$$"; exec /bin/launchctl print "$1"', - 'gstack-dia-domain-probe', 'user/23456']); - expect(options.env).toBe(env); - expect(options.timeout).toBeGreaterThan(0); - expect(options.timeout).toBeLessThanOrEqual(3_000); - expect(Number.isInteger(options.timeout)).toBe(true); - expect(options.maxBuffer).toBe(1024 * 1024); - return { status: 0, stdout: 'GSTACK_DIA_DOMAIN_PROBE_PID=4567\nuser/23456 = {\n\ttype = user\n\tcreator = launchctl.4567\n}', stderr: '' }; - }) as typeof spawnSync); - expect(called).toBe(true); - expect(observation.state).toBe('present'); - expect(observation.structure?.creatorIsProbe).toBe(true); - expect(JSON.stringify(observation)).not.toContain('GSTACK_DIA_DOMAIN_PROBE_PID'); - }); - - test('domain probe failures preserve unknown state instead of manufacturing absence or creator ownership', () => { - for (const result of [ - { status: 0, stdout: 'user/23456 = {\n\ttype = user\n}', stderr: '' }, - { status: 0, stdout: 'GSTACK_DIA_DOMAIN_PROBE_PID=9007199254740992\nuser/23456 = {\n\ttype = user\n}', stderr: '' }, - { status: 113, stdout: '', stderr: 'Could not find domain for user uid: 23456' }, - { status: null, stdout: null, stderr: null, error: new Error('synthetic-private-error') }, - ]) { - const observation = inspectUserDomain(23456, performance.now() + 10_000, {}, (() => result) as unknown as typeof spawnSync); - expect(observation.state).toBe('unavailable'); - expect(observation.structure).toBeUndefined(); - expect(JSON.stringify(observation)).not.toContain('synthetic-private'); - } - expect(inspectUserDomain(23456, performance.now() + 10_000, {}, (() => ({ status: 113, - stdout: 'GSTACK_DIA_DOMAIN_PROBE_PID=4567\n', stderr: 'Could not find domain for user uid: 23456' })) as typeof spawnSync).state).toBe('absent'); - const never = (() => { throw new Error('must_not_spawn'); }) as typeof spawnSync; - expect(() => inspectUserDomain(0, performance.now() + 10_000, {}, never)).toThrow('invalid_fresh_user_domain'); - for (const deadline of [0, NaN, Infinity]) expect(() => inspectUserDomain(23456, deadline, {}, never)).toThrow('fresh_launcher_deadline'); - }); - - test('the domain probe PID protocol survives real shell exec without logging the PID or child output', () => { - const fixture = path.join(root, 'domain-probe.cjs'); - writeFileSync(fixture, 'process.stdout.write("user/23456 = {\\n\\ttype = user\\n\\tcreator = launchctl." + process.pid + "\\n}");'); - const observation = inspectUserDomain(23456, performance.now() + 10_000, { PATH: '/usr/bin:/bin', HOME: root }, - ((_command: string, args: string[], options: any) => spawnSync('/bin/sh', ['-c', - args[3].replace('/bin/launchctl print "$1"', '"$1" "$2"'), args[4], process.execPath, fixture], - { ...options, timeout: 3_000 })) as typeof spawnSync); - expect(observation.state).toBe('present'); - expect(observation.structure?.creatorIsProbe).toBe(true); - expect(observation.structure?.complete).toBe(true); - expect(JSON.stringify(observation)).not.toContain('GSTACK_DIA_DOMAIN_PROBE_PID'); - }); - - test('user-domain teardown is bound to the new account and its pre-creation absence proof', () => { - const account = { guid: 'A38AC39B-5960-4F0C-B02F-C32A4F625B33', uid: 23456, gid: 23456, home: '/private/tmp/dn-fixture/home' }; - const record = { GeneratedUID: account.guid, UniqueID: '23456', PrimaryGroupID: '23456', NFSHomeDirectory: account.home }; - const proof = classifyParentDomain(23456, { status: 0, stdout: 'system = {\n\ttype = system\n\tsubdomains = {}\n}', stderr: '' }); - const current = classifyParentDomain(23456, { status: 0, stdout: 'system = {\n\ttype = system\n\tsubdomains = {\n\t\tuser/23456\n\t}\n}', stderr: '' }); - expect(ownedUserDomainTarget(record, account, proof, current, 501)).toBe('user/23456'); - expect(ownedUserDomainTarget(record, account, proof, proof, 501)).toBeNull(); - for (const key of ['GeneratedUID', 'UniqueID', 'PrimaryGroupID', 'NFSHomeDirectory']) { - expect(() => ownedUserDomainTarget({ ...record, [key]: 'changed' }, account, proof, current, 501)).toThrow('fresh_user_domain_ownership_unconfirmed'); - } - expect(() => ownedUserDomainTarget(record, account, undefined, current, 501)).toThrow('fresh_user_domain_ownership_unconfirmed'); - expect(() => ownedUserDomainTarget(record, account, { ...proof, state: 'present' }, current, 501)).toThrow('fresh_user_domain_ownership_unconfirmed'); - expect(() => ownedUserDomainTarget(record, account, { ...proof, uid: 23457 }, current, 501)).toThrow('fresh_user_domain_ownership_unconfirmed'); - expect(() => ownedUserDomainTarget(record, account, proof, current, 23456)).toThrow('fresh_user_domain_ownership_unconfirmed'); - expect(() => ownedUserDomainTarget(record, account, proof, current, NaN)).toThrow('fresh_user_domain_ownership_unconfirmed'); - for (const changed of [{ ...current, matchingGuiDomains: 1 }, { ...current, uid: 23457 }, { ...current, state: 'unavailable' as const }, - { ...current, duplicateEntries: 1 }, { ...current, matchingUserDomains: 2 }, { ...current, parseStage: 'missing_subdomains' }, - { ...current, unrecognizedEntries: 1 }]) { - expect(() => ownedUserDomainTarget(record, account, proof, changed, 501)).toThrow('fresh_user_domain_ownership_unconfirmed'); - } - }); - - test('duplicated native subdomain entries and equivalent aliases never authorize teardown or absence', () => { - for (const entries of [ - ['user/23456', 'user/23456'], ['user/23456', 'com.apple.xpc.launchd.domain.user.23456'], - ['user/23456', 'gui/23456', 'gui/23456'], ['user/501', 'user/501'], - ['user/23456', 'pid/22', 'com.apple.xpc.launchd.domain.pid.synthetic-private-process.22'], - ]) { - const observation = classifyParentDomain(23456, { status: 0, - stdout: 'system = {\n\ttype = system\n\tsubdomains = {\n' + entries.map(entry => '\t\t' + entry).join('\n') + '\n\t}\n}', stderr: '' }); - expect(observation.duplicateEntries).toBe(1); - expect(observation.parseStage).toBe('duplicate_subdomain'); - expect(observation.state).toBe('unavailable'); - expect(passiveUserDomainState(observation, 23456)).toBe('unavailable'); - } - }); - - test('passive absence and presence require consistent complete facts with no GUI association', () => { - const absent = classifyParentDomain(23456, { status: 0, stdout: 'system = {\n\ttype = system\n\tsubdomains = {}\n}', stderr: '' }); - expect(passiveUserDomainState(absent, 23456)).toBe('absent'); - for (const changed of [undefined, { ...absent, uid: 23457 }, { ...absent, matchingUserDomains: 1 }, - { ...absent, matchingGuiDomains: 1 }, { ...absent, exitCode: 1 }, { ...absent, duplicateEntries: 1 }, - { ...absent, unrecognizedEntries: 1 }, { ...absent, state: 'present' as const }]) { - expect(passiveUserDomainState(changed, 23456)).toBe('unavailable'); - } - const gui = classifyParentDomain(23456, { status: 0, - stdout: 'system = {\n\ttype = system\n\tsubdomains = {\n\t\tuser/23456\n\t\tgui/23456\n\t}\n}', stderr: '' }); - expect(passiveUserDomainState(gui, 23456)).toBe('unavailable'); - const oldTargetObservation = classifyUserDomain(23456, { status: 113, stdout: '', stderr: 'Could not find domain for user uid: 23456' }); - expect(passiveUserDomainState(oldTargetObservation as any, 23456)).toBe('unavailable'); - }); - - test('directory UID inventory retains occupied candidate IDs and refuses malformed or empty listings', () => { - expect([...parseDirectoryIds('root 0\nfixture 20000\nnobody -2\nother fixture 20001 \n')]).toEqual([0, 20000, -2, 20001]); - for (const value of ['', 'malformed', 'root 0\nfixture unknown\n', 'root 0\nfixture 9007199254740992\n']) { - expect(() => parseDirectoryIds(value)).toThrow(); - } - }); - - test('normal qualification never invokes the materializing target-domain diagnostic', () => { - const implementation = runFreshAccountQualification.toString(); - expect(implementation).toContain('inspectParentDomain'); - expect(implementation).toContain('passiveUserDomainState'); - expect(implementation).not.toMatch(/inspectUserDomain|probeUserDomain|classifyUserDomain/); - expect(implementation).not.toMatch(/['"]print['"],\s*['"](?:user|gui)\//); - }); - - test('launchd receives a one-shot fresh-user security session without an Aqua or auto-login workaround', () => { - const account: any = { label: 'ai.gstack.dia.fixture', account: 'gsdiafixture', bun: '/private/tmp/fixture/bin/bun', - snapshot: '/private/tmp/fixture/repo', configFile: '/private/tmp/fixture/account.json', environment: { HOME: '/private/tmp/fixture/home', CI: 'true' } }; - const definition = freshLaunchDefinition(account); - expect(definition.UserName).toBe(account.account); - expect(definition.GroupName).toBe(account.account); - expect(definition.SessionCreate).toBe(true); - expect(definition.RunAtLoad).toBe(true); - expect(definition.KeepAlive).toBe(false); - expect(definition.Umask).toBe(63); - expect(definition.ProgramArguments[0]).toBe(account.bun); - expect(definition.ProgramArguments).toContain('--fresh-worker'); - expect(definition.StandardOutPath).toBe('/dev/null'); - expect(definition.StandardErrorPath).toBe('/dev/null'); - expect(JSON.stringify(definition)).not.toMatch(/Aqua|autoLogin|LoginWindow|GITHUB_TOKEN/); - }); - - test('service cleanup binds the exact system label, executable, user, and private group', () => { - const owner = { label: 'ai.gstack.dia.fixture', bun: '/private/tmp/fixture/bin/bun', account: 'gsdiafixture' }; - const state = `system/${owner.label} = {\n program = ${owner.bun}\n username = ${owner.account}\n group = ${owner.account}\n}`; - expect(ownsLaunchService(state, owner)).toBe(true); - for (const replacement of [state.replace('system/', 'gui/501/'), state.replace(owner.label, 'unrelated'), - state.replace(owner.bun, '/unrelated/bun'), state.replace('username = gsdiafixture', 'username = runner'), - state.replace('group = gsdiafixture', 'group = staff')]) expect(ownsLaunchService(replacement, owner)).toBe(false); - }); - - test('the fresh-account launcher refuses this non-authorized invocation without privileged work', () => { - const launcher = path.resolve(import.meta.dir, '../../.github/scripts/run-dia-native-qualification.ts'); - const result = spawnSync(process.execPath, ['--no-env-file', '--no-install', '--no-macros', `--config=${process.platform === 'win32' ? 'NUL' : '/dev/null'}`, launcher], { - cwd: root, env: { HOME: root, PATH: path.dirname(process.execPath) }, encoding: 'utf8', timeout: 10_000, - }); - expect(result.status).toBe(2); - expect(result.stderr).toBe(''); - expect(JSON.parse(result.stdout).reason).toBe('fresh_account_launcher_preflight_failed'); - }); - - for (const shape of ['normal', 'safe-link', 'traversal', 'absolute', 'escape-link', 'symlink-parent', 'symlink-dotdot', 'hardlink', 'case-collision', 'unicode-collision', 'device']) { - test(`archive preflight classifies ${shape} before extraction`, () => { - const python = Bun.which('python3'); - if (!python) throw new Error('Python 3 is required for archive boundary tests'); - const archive = path.join(root, shape + '.tar'); - const create = spawnSync(python, ['-I', '-c', ` -import io, sys, tarfile -shape, file = sys.argv[1:] -with tarfile.open(file, 'w') as out: - def entry(name, kind=tarfile.REGTYPE, link=''): - item = tarfile.TarInfo(name); item.type = kind; item.linkname = link - if kind == tarfile.REGTYPE: - item.size = 1; out.addfile(item, io.BytesIO(b'x')) - else: out.addfile(item) - if shape == 'normal': entry('src/file.ts') - elif shape == 'safe-link': entry('target'); entry('link', tarfile.SYMTYPE, 'target') - elif shape == 'traversal': entry('../outside') - elif shape == 'absolute': entry('/outside') - elif shape == 'escape-link': entry('link', tarfile.SYMTYPE, '../outside') - elif shape == 'symlink-parent': entry('link', tarfile.SYMTYPE, 'target'); entry('link/child') - elif shape == 'symlink-dotdot': entry('b', tarfile.SYMTYPE, '.'); entry('a/link', tarfile.SYMTYPE, '../b/..') - elif shape == 'hardlink': entry('target'); entry('link', tarfile.LNKTYPE, 'target') - elif shape == 'case-collision': entry('File'); entry('file') - elif shape == 'unicode-collision': entry('Caf' + chr(233)); entry('Cafe' + chr(769)) - elif shape == 'device': entry('device', tarfile.CHRTYPE) -`, shape, archive], { encoding: 'utf8', timeout: 10_000 }); - expect(create.status).toBe(0); - const checked = spawnSync(python, ['-I', '-c', ARCHIVE_CHECK, archive], { encoding: 'utf8', timeout: 10_000 }); - expect(checked.status).toBe(['normal', 'safe-link'].includes(shape) ? 0 : 2); - expect(JSON.parse(checked.stdout).valid).toBe(['normal', 'safe-link'].includes(shape)); - expect(checked.stderr).toBe(''); - }); - } - - test('receipt collection rejects symlinks and an unrelated owner without printing content', () => { - const python = Bun.which('python3'); - if (!python) throw new Error('Python 3 is required for receipt boundary tests'); - const directory = realpathSync(mkdtempSync(path.join(root, 'receipts-'))); - const file = path.join(directory, 'receipt.json'); - writeFileSync(file, JSON.stringify({ status: 'incomplete', reason: 'synthetic_fixture' }), { mode: 0o600 }); - chmodSync(file, 0o600); - const uid = process.getuid!(); - const read = (selected: string, owner: number) => spawnSync(python, ['-I', '-c', PRIVATE_RECEIPT_READ, selected, String(owner), directory], { - encoding: 'utf8', timeout: 10_000, - }); - const valid = read(file, uid); - expect(valid.status).toBe(0); - expect(JSON.parse(valid.stdout).status).toBe('incomplete'); - const wrong = read(file, uid + 1); - expect(wrong.status).toBe(2); - expect(wrong.stdout).toBe(''); - const link = path.join(directory, 'linked.json'); - symlinkSync(file, link); - const linked = read(link, uid); - expect(linked.status).toBe(2); - expect(linked.stdout).toBe(''); - }); - - test('receipt collection rejects linked ancestors and incomplete JSON without disclosing content', () => { - const python = Bun.which('python3'); - if (!python) throw new Error('Python 3 is required for receipt boundary tests'); - const directory = realpathSync(mkdtempSync(path.join(root, 'receipt-ancestors-'))); - const nested = path.join(directory, 'nested'); - mkdirSync(nested, { mode: 0o700 }); - const file = path.join(nested, 'receipt.json'); - writePrivateReceipt(file, { status: 'incomplete' }); - const linked = path.join(directory, 'linked'); - symlinkSync(nested, linked, 'dir'); - const read = (selected: string) => spawnSync(python, ['-I', '-c', PRIVATE_RECEIPT_READ, selected, String(process.getuid!()), directory], { - encoding: 'utf8', timeout: 3_000, - }); - expect(read(file).status).toBe(0); - const rejected = read(path.join(linked, 'receipt.json')); - expect(rejected.status).toBe(2); - expect(rejected.stdout).toBe(''); - writeFileSync(file, '{"synthetic-private-value":'); - const partial = read(file); - expect(partial.status).toBe(2); - expect(partial.stdout).toBe(''); - }); - - test('receipt publication is private, atomic, and refuses unintended overwrites or symlink targets', () => { - const directory = realpathSync(mkdtempSync(path.join(root, 'atomic-receipt-'))); - const file = path.join(directory, 'receipt.json'); - writePrivateReceipt(file, { status: 'incomplete', phase: 'first' }); - expect(lstatSync(file).mode & 0o777).toBe(0o600); - expect(() => writePrivateReceipt(file, { status: 'passed' })).toThrow(); - expect(JSON.parse(readFileSync(file, 'utf8')).phase).toBe('first'); - writePrivateReceipt(file, { status: 'incomplete', phase: 'second' }, true); - expect(JSON.parse(readFileSync(file, 'utf8')).phase).toBe('second'); - const link = path.join(directory, 'linked.json'); - symlinkSync(file, link); - expect(() => writePrivateReceipt(link, { status: 'passed' }, true)).toThrow('unsafe_receipt_replacement'); - expect(JSON.parse(readFileSync(file, 'utf8')).phase).toBe('second'); - expect(readdirSync(directory).some(name => name.startsWith('.dia-receipt-'))).toBe(false); - }); - - test('an atomic owner-checked diagnostic receipt is readable while its producer is still alive', async () => { - const python = Bun.which('python3'); - if (!python) throw new Error('Python 3 is required for receipt boundary tests'); - const directory = realpathSync(mkdtempSync(path.join(root, 'live-receipt-'))); - const file = path.join(directory, 'receipt.json'); - const module = pathToFileURL(path.resolve(import.meta.dir, '../../.github/scripts/qualify-dia-macos.ts')).href; - const child = Bun.spawn([process.execPath, '--no-env-file', '--no-install', '--no-macros', '--config=/dev/null', '-e', ` - const { writePrivateReceipt } = await import(${JSON.stringify(module)}); - writePrivateReceipt(${JSON.stringify(file)}, { status: 'incomplete', reason: 'worker_diagnostic', cleanup: { complete: false } }); - console.log('ready'); - setInterval(() => {}, 1000); - `], { cwd: directory, env: { HOME: directory, PATH: path.dirname(process.execPath) }, stdout: 'pipe', stderr: 'pipe' }); - try { - const reader = child.stdout.getReader(); - expect(new TextDecoder().decode((await reader.read()).value)).toContain('ready'); - reader.releaseLock(); - expect(child.exitCode).toBeNull(); - const result = spawnSync(python, ['-I', '-c', PRIVATE_RECEIPT_READ, file, String(process.getuid!()), directory], { - encoding: 'utf8', timeout: 3_000, - }); - expect(result.status).toBe(0); - expect(JSON.parse(result.stdout)).toEqual({ status: 'incomplete', reason: 'worker_diagnostic', cleanup: { complete: false } }); - expect(child.exitCode).toBeNull(); - } finally { - child.kill(); - await child.exited; - } - }); - - test('UID process diagnostics preserve zombie/service/browser distinctions without argv or arbitrary names', () => { - const facts = uidProcessFacts('20000 301 1 Ss cfprefsd\n20000 302 1 Z bun\n20000 303 301 R Google Chrome for Testing\n20000 304 1 S synthetic-private-value\n501 999 1 S security\n', 20000); - expect(facts).toEqual({ available: true, count: 4, zombies: 1, live: 3, truncated: false, processes: [ - { pid: 301, ppid: 1, state: 'S', basename: 'cfprefsd' }, { pid: 302, ppid: 1, state: 'Z', basename: 'bun' }, - { pid: 303, ppid: 301, state: 'R', basename: 'Google Chrome for Testing' }, { pid: 304, ppid: 1, state: 'S', basename: 'other' }, - ] }); - expect(JSON.stringify(facts)).not.toContain('synthetic-private-value'); - expect(JSON.stringify(facts)).not.toContain('999'); - expect(uidProcessFacts('20000 401 1 S cfprefsd\n', 20000).processes[0].pid).toBe(401); - expect(uidProcessFacts('20000 402 1 Z+ bun\n', 20000)).toMatchObject({ count: 1, zombies: 1, live: 0 }); - expect(() => uidProcessFacts('malformed synthetic-private-value', 20000)).toThrow('invalid_uid_process_snapshot'); - expect(uidProcessFacts(Array.from({ length: 80 }, (_, index) => `20000 ${1000 + index} 1 S bun`).join('\n'), 20000)) - .toMatchObject({ count: 80, truncated: true }); - expect(uidProcessFacts(Array.from({ length: 80 }, (_, index) => `20000 ${1000 + index} 1 S bun`).join('\n'), 20000).processes).toHaveLength(64); - }); - - test('captured passing inner receipts cannot qualify a run with incomplete cleanup', () => { - const cleanup = { serviceStopped: true, userDomainStopped: true, userProcessesStopped: true, accountRemoved: true, groupRemoved: true, stagingRemoved: true }; - expect(freshQualificationPassed(0, 'passed', 'passed', cleanup)).toBe(true); - for (const key of Object.keys(cleanup)) expect(freshQualificationPassed(0, 'passed', 'passed', { ...cleanup, [key]: false })).toBe(false); - expect(freshQualificationPassed(0, 'passed', 'passed', {})).toBe(false); - expect(freshQualificationPassed(2, 'passed', 'passed', cleanup)).toBe(false); - expect(freshQualificationPassed(0, 'incomplete', 'passed', cleanup)).toBe(false); - }); - - test('the registered spawn observer records the actual owned child and closes launch admission', async () => { - const profile = path.join(root, 'profile'); - const childProcess = require('node:child_process'); - const original = childProcess.spawn; - const observer = observeBrowserLaunches(new Map([[process.execPath, profile]])); - const args = ['--no-env-file', '--no-install', '-e', 'process.exit(0)', '--', '--remote-debugging-pipe', '--user-data-dir=' + profile]; - const options = { cwd: root, detached: true, shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'], - env: { PATH: path.dirname(process.execPath), HOME: root, ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}) } }; - try { - const child = childProcess.spawn(process.execPath, args, options); - const code = await new Promise(resolve => child.once('close', resolve)); - expect(code).toBe(0); - expect(observer.children).toHaveLength(1); - expect(observer.children[0].process).toBe(child); - expect(observer.children[0].pid).toBe(child.pid); - observer.stop(); - expect(() => childProcess.spawn(process.execPath, args, options)).toThrow('browser_launch_policy_rejected'); - expect(observer.children).toHaveLength(1); - } finally { - observer.restore(); - } - expect(childProcess.spawn).toBe(original); - }); - - test('the owned spawn stderr observer preserves the consumer stream and removes only its own listeners', async () => { - const childProcess = require('node:child_process'); - const original = childProcess.spawn; - const profile = path.join(root, 'stderr-observer-profile'); - const observer = observeBrowserLaunches(new Map([[process.execPath, profile]])); - const text = 'DevTools remote debugging requires a non-default data directory.\nsynthetic-private-value\n'; - try { - const child = childProcess.spawn(process.execPath, ['--no-env-file', '--no-install', '-e', - `process.stderr.write(${JSON.stringify(text)})`, '--', '--remote-debugging-pipe', '--user-data-dir=' + profile], { - detached: true, shell: false, stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'], env: { HOME: root, PATH: path.dirname(process.execPath) }, - }); - const chunks: Buffer[] = []; - const consumer = (chunk: Buffer) => { chunks.push(chunk); }; - child.stderr.on('data', consumer); - const code = await new Promise(resolve => child.once('close', resolve)); - expect(code).toBe(0); - expect(Buffer.concat(chunks).toString()).toBe(text); - const facts = browserStderrFacts(observer.children); - expect(facts).toHaveLength(1); - expect(facts[0]).toMatchObject({ available: true, bytesSeen: Buffer.byteLength(text), ended: true, - reasonCounts: { default_profile_policy: 1 } }); - expect(JSON.stringify(facts)).not.toContain('synthetic-private'); - observer.restore(); - expect(child.stderr.listeners('data')).toContain(consumer); - expect(childProcess.spawn).toBe(original); - } finally { observer.restore(); } - }); - - test('an owned killed child is joined before proving its process group absent', async () => { - const childProcess = require('node:child_process'); - const profile = path.join(root, 'reaping-profile'); - const observer = observeBrowserLaunches(new Map([[process.execPath, profile]])); - let timer: ReturnType | undefined; - try { - const child = childProcess.spawn(process.execPath, ['--no-env-file', '--no-install', '-e', - 'process.stdout.write("ready\\n"); setInterval(() => {}, 1000)', '--', '--remote-debugging-pipe', '--user-data-dir=' + profile], { - detached: true, shell: false, stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'], env: { HOME: root, PATH: path.dirname(process.execPath) }, - }); - await Promise.race([new Promise(resolve => child.stdout.once('data', resolve)), new Promise((_, reject) => { - timer = setTimeout(() => reject(new Error('fixture_startup_timeout')), 3000); - })]); - clearTimeout(timer); - const owned = observer.children[0]; - expect(owned.closeObserved).toBe(false); - const until = performance.now() + 5_000; - const facts: Record = { signalSent: false, absenceConfirmed: false }; - await stopOwnedBrowserGroup(owned, until, facts); - expect(owned.closeObserved).toBe(true); - expect(facts).toMatchObject({ signalSent: true, childCloseObserved: true, absenceConfirmed: true }); - let absent = false; - while (performance.now() < until) { - try { process.kill(-owned.pid, 0); } - catch (error: any) { if (error.code === 'ESRCH') { absent = true; break; } throw error; } - await Bun.sleep(10); - } - expect(absent).toBe(true); - expect(browserRootFacts(observer.children)[0]).toMatchObject({ closeObserved: true, signal: 'SIGKILL' }); - } finally { - clearTimeout(timer); - for (const owned of observer.children) { - if (owned.closeObserved) continue; - try { process.kill(-owned.pid, 'SIGKILL'); } catch {} - await joinOwnedBrowserClose(owned, performance.now() + 5_000); - } - observer.restore(); - } - }); - - test('the pinned Playwright launch is captured with the observer installed after importing Playwright', async () => { - const { chromium } = await import('playwright'); - expect(require('playwright/package.json').version).toBe('1.62.1'); - const executable = realpathSync(chromium.executablePath()); - const profile = path.join(root, 'playwright-profile'); - const observer = observeBrowserLaunches(new Map([[executable, profile]])); - let context: Awaited> | undefined; - try { - const nativeOptions = nativeDiaLaunchOptions(executable, { - HOME: root, PATH: path.dirname(process.execPath) + ':/usr/bin:/bin:/usr/sbin:/sbin', - ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}), - }); - expect(nativeOptions.chromiumSandbox).toBe(true); - context = await chromium.launchPersistentContext(profile, nativeOptions); - expect(observer.children).toHaveLength(1); - expect(observer.children[0].executable).toBe(executable); - expect(observer.children[0].pid).toBeGreaterThan(1); - expect(browserRootFacts(observer.children)).toEqual([{ pid: observer.children[0].pid, exitCode: null, closeObserved: false, signal: null }]); - expect(browserStartupFacts(context.pages().map(page => page.url()), 'http://127.0.0.1:8123').allowed).toBe(true); - expect(browserStderrFacts(observer.children)[0].available).toBe(true); - expect(browserStderrFacts(observer.children)[0].bytesInspected).toBeLessThanOrEqual(65_536); - expect(observer.attempts).toHaveLength(1); - expect(observer.attempts[0]).toEqual({ admissionOpen: true, argumentsArray: true, pipeFlag: true, profileArgumentCount: 1, - expectedProfile: true, detached: true, shellDisabled: true, stdioCount: 5, extraPipeDescriptors: true, - headlessFlag: true, blankStartupArgument: true, tcpDebuggingFlag: false, mockKeychainFlag: false, - passwordStoreFlag: false, firstRunSuppressed: false, sandboxRequired: process.platform === 'darwin', sandboxDisablingFlag: false }); - expect(JSON.stringify(observer.attempts)).not.toContain(executable); - expect(JSON.stringify(observer.attempts)).not.toContain(profile); - const page = context.pages()[0] ?? await context.newPage(); - await page.setContent('

isolated browser smoke
'); - expect(await page.locator('#fixture').innerText()).toBe('isolated browser smoke'); - await context.close(); - context = undefined; - expect(observer.children[0].process.exitCode !== null || observer.children[0].process.signalCode !== null).toBe(true); - } finally { - observer.stop(); - await context?.close(); - observer.restore(); - } - }, 40_000); - - for (const forbidden of ['--remote-debugging-port=9222', '--use-mock-keychain', '--password-store=basic', '--no-first-run']) { - test(`the actual spawn callback rejects ${forbidden} before process creation`, () => { - const profile = path.join(root, 'profile'); - const childProcess = require('node:child_process'); - const observer = observeBrowserLaunches(new Map([[process.execPath, profile]])); - try { - expect(() => childProcess.spawn(process.execPath, ['--remote-debugging-pipe', '--user-data-dir=' + profile, forbidden], - { detached: true, shell: false, stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'] })).toThrow('browser_launch_policy_rejected'); - expect(observer.children).toHaveLength(0); - } finally { observer.restore(); } - }); - } - - test('the spawn callback rejects an unowned profile, shell expansion, and a shared process group', () => { - const profile = path.join(root, 'profile'); - const childProcess = require('node:child_process'); - const observer = observeBrowserLaunches(new Map([[process.execPath, profile]])); - try { - for (const [selected, detached, shell] of [[path.join(root, 'other'), true, false], [profile, false, false], [profile, true, true]]) { - expect(() => childProcess.spawn(process.execPath, ['--remote-debugging-pipe', '--user-data-dir=' + selected], { detached, shell, stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'] })) - .toThrow('browser_launch_policy_rejected'); - } - expect(() => childProcess.spawn(process.execPath, ['--remote-debugging-pipe', '--user-data-dir=' + profile, '--user-data-dir=' + path.join(root, 'other')], - { detached: true, shell: false, stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'] })).toThrow('browser_launch_policy_rejected'); - expect(() => childProcess.spawn(process.execPath, ['--remote-debugging-pipe', '--user-data-dir=' + profile], - { detached: true, shell: false, stdio: 'inherit' })).toThrow('browser_launch_policy_rejected'); - expect(observer.children).toHaveLength(0); - } finally { observer.restore(); } - }); -}); diff --git a/browse/test/path-security-realpath.test.ts b/browse/test/path-security-realpath.test.ts index aa3b03267..cc7518dd8 100644 --- a/browse/test/path-security-realpath.test.ts +++ b/browse/test/path-security-realpath.test.ts @@ -11,6 +11,7 @@ import { afterAll, beforeAll, describe, expect, test } from 'bun:test'; import * as fs from 'node:fs'; import * as os from 'node:os'; import * as path from 'node:path'; +import { dlopen, FFIType, ptr } from 'bun:ffi'; const VALIDATOR = path.resolve(import.meta.dir, '../src/path-security.ts'); const WIN = process.platform === 'win32'; @@ -43,11 +44,16 @@ function validate(tempDir: string, checks: Array<['output' | 'read', string]>): } function shortPath(dir: string): string { - const result = Bun.spawnSync(['powershell', '-NoProfile', '-NonInteractive', '-Command', - `(New-Object -ComObject Scripting.FileSystemObject).GetFolder($env:GSTACK_LONG_DIR).ShortPath`], { - env: { ...process.env, GSTACK_LONG_DIR: dir }, stdout: 'pipe', stderr: 'pipe', timeout: 30_000, - }); - return result.stdout.toString().trim(); + const kernel = dlopen('kernel32.dll', { GetShortPathNameW: { args: [FFIType.ptr, FFIType.ptr, FFIType.u32], returns: FFIType.u32 } }); + try { + const input = Buffer.from(dir + '\0', 'utf16le'); + const output = Buffer.alloc(65536); + const length = kernel.symbols.GetShortPathNameW(ptr(input), ptr(output), 32768); + if (length === 0 || length >= 32768) throw new Error(`GetShortPathNameW failed for ${dir} (returned ${length})`); + return output.subarray(0, length * 2).toString('utf16le'); + } finally { + kernel.close(); + } } describe('#3104 one realpath for safe dirs and targets', () => { diff --git a/browse/test/process-liveness-windows.test.ts b/browse/test/process-liveness-windows.test.ts index b2f5f7e93..9e00a50e3 100644 --- a/browse/test/process-liveness-windows.test.ts +++ b/browse/test/process-liveness-windows.test.ts @@ -4,7 +4,10 @@ import * as fs from 'fs'; import * as os from 'os'; import * as path from 'path'; import { isProcessAlive } from '../src/error-handling'; -import { spawnTerminalAgent } from '../src/terminal-agent-control'; +import { + isAgentRecordGone, isOurAgent, readAgentStartTime, spawnTerminalAgent, stopAgentByRecord, win32CreationTimeSource, writeAgentRecord, + type AgentRecord, +} from '../src/terminal-agent-control'; // REGRESSION TEST for the Windows terminal-agent leak. // @@ -117,8 +120,10 @@ describe('process liveness probe (Windows terminal-agent leak)', () => { } return originalProbe(command, options); }) as typeof Bun.spawnSync); + const powershellCalls: string[] = []; const windowsProbe = spyOn(childProcess, 'spawnSync').mockImplementation(((command: string, args: string[], options: any) => { if (command === 'powershell.exe') { + powershellCalls.push(args.join(' ')); const owner = args.join(' ').includes(`ProcessId = ${process.pid}'`); return { status: 0, stdout: JSON.stringify(owner ? { CreationDate: 'fixture-owner-start', CommandLine: 'test-owner' } : null), stderr: '' }; } @@ -143,7 +148,14 @@ describe('process liveness probe (Windows terminal-agent leak)', () => { // Owner-PID lifetime tie (#2019): the agent polls this and exits when // its owning browse server dies, so it can't be adopted by PID 1. expect(captured.env.BROWSE_OWNER_PID).toBe(String(process.pid)); - expect(captured.env.BROWSE_OWNER_START_TIME).toBe('fixture-owner-start'); + if (process.platform === 'win32') { + expect(captured.env.BROWSE_OWNER_START_TIME).toMatch(/^\/Date\(\d+\)\/$/); + expect(captured.env.BROWSE_OWNER_START_TIME).toBe(readAgentStartTime(process.pid)); + expect(powershellCalls.filter(call => call.includes(`ProcessId = ${process.pid}'`))).toEqual([]); + expect(powershellCalls.every(call => call.includes("ProcessId = 2147483647'"))).toBe(true); + } else { + expect(captured.env.BROWSE_OWNER_START_TIME).toBe('fixture-owner-start'); + } // Detached background daemon — must not inherit a terminal either. expect(captured.stdio).toEqual(['ignore', 'ignore', 'ignore']); await exited; @@ -174,3 +186,145 @@ describe('process liveness probe (Windows terminal-agent leak)', () => { expect(windowMs).toBeGreaterThanOrEqual(tick * guardMax); }); }); + +describe('win32 terminal-agent identity (GSTA-139)', () => { + const pid = 2147483645; + const gen = 'win32-identity-generation'; + const birth = '/Date(1761600000123)/'; + const ownedCommand = `"C:\\bun\\bun.exe" run terminal-agent.ts --agent-gen=${gen}`; + const record = (startTime = birth): AgentRecord => ({ pid, gen, startTime, startedAt: 0, ownerPid: pid, ownerStartTime: birth }); + type PowerShell = { status: number | null; creationDate?: string; commandLine?: string }; + + function onWin32(scenario: { ffi: string | undefined; powershell: PowerShell }, run: (calls: { powershell: number; signals: unknown[] }) => void): void { + const platform = Object.getOwnPropertyDescriptor(process, 'platform')!; + const calls = { powershell: 0, signals: [] as unknown[] }; + let live = true; + const kill = spyOn(process, 'kill').mockImplementation(((target: number, signal: unknown) => { + expect(target).toBe(pid); + if (!live) throw Object.assign(new Error('gone'), { code: 'ESRCH' }); + if (signal !== 0) { calls.signals.push(signal); live = false; } + return true; + }) as typeof process.kill); + const read = spyOn(win32CreationTimeSource, 'read').mockImplementation((target: number) => (target === pid && live ? scenario.ffi : undefined)); + const probe = spyOn(childProcess, 'spawnSync').mockImplementation(((command: string) => { + expect(command).toBe('powershell.exe'); + calls.powershell++; + const { status, creationDate, commandLine } = scenario.powershell; + return status === 0 + ? { status, stdout: JSON.stringify({ CreationDate: creationDate, CommandLine: commandLine }), stderr: '' } + : { status, stdout: '', stderr: '', error: Object.assign(new Error('spawnSync powershell.exe ETIMEDOUT'), { code: 'ETIMEDOUT' }) }; + }) as typeof childProcess.spawnSync); + Object.defineProperty(process, 'platform', { ...platform, value: 'win32' }); + try { + run(calls); + } finally { + Object.defineProperty(process, 'platform', platform); + probe.mockRestore(); + read.mockRestore(); + kill.mockRestore(); + } + } + + test('the start time is read in-process, so a PowerShell launch killed at its timeout cannot empty it', () => { + onWin32({ ffi: birth, powershell: { status: null } }, calls => { + expect(readAgentStartTime(pid)).toBe(birth); + expect(calls.powershell).toBe(0); + }); + }); + + test('without the in-process reader (Node daemon) the start time falls back to the PowerShell CreationDate', () => { + onWin32({ ffi: undefined, powershell: { status: 0, creationDate: birth, commandLine: ownedCommand } }, calls => { + expect(readAgentStartTime(pid)).toBe(birth); + expect(calls.powershell).toBe(1); + }); + }); + + test('kill-time ownership still requires the generation in the PowerShell command line', () => { + onWin32({ ffi: birth, powershell: { status: 0, creationDate: birth, commandLine: ownedCommand } }, calls => { + expect(isOurAgent(record())).toBe(true); + expect(stopAgentByRecord(record(), 0)).toBe(true); + expect(calls.signals).toEqual(['SIGTERM']); + }); + for (const powershell of [{ status: 0, creationDate: birth, commandLine: 'bun run unrelated.ts' }, { status: null }]) { + onWin32({ ffi: birth, powershell }, calls => { + expect(isOurAgent(record())).toBe(false); + expect(isAgentRecordGone(record())).toBe(false); + expect(stopAgentByRecord(record(), 0)).toBe(false); + expect(calls.signals).toEqual([]); + }); + } + onWin32({ ffi: '/Date(1761600000124)/', powershell: { status: 0, creationDate: birth, commandLine: 'bun run unrelated.ts' } }, calls => { + expect(isAgentRecordGone(record())).toBe(true); + expect(calls.signals).toEqual([]); + }); + }); + + test('a start time that disagrees across readers still identifies the live agent by its generation, so no second agent starts', () => { + const daemonRecorded = '/Date(1761596400123)/'; + onWin32({ ffi: birth, powershell: { status: 0, creationDate: daemonRecorded, commandLine: ownedCommand } }, calls => { + expect(isAgentRecordGone(record(daemonRecorded))).toBe(false); + expect(isOurAgent(record(daemonRecorded))).toBe(true); + expect(stopAgentByRecord(record(daemonRecorded), 0)).toBe(true); + expect(calls.signals).toEqual(['SIGTERM']); + }); + onWin32({ ffi: birth, powershell: { status: null } }, calls => { + expect(isAgentRecordGone(record(daemonRecorded))).toBe(false); + expect(stopAgentByRecord(record(daemonRecorded), 0)).toBe(false); + expect(calls.signals).toEqual([]); + }); + }); + + test('an unreadable start time is unknown: never signalled and never treated as gone', () => { + onWin32({ ffi: undefined, powershell: { status: null } }, calls => { + expect(readAgentStartTime(pid)).toBe(''); + expect(isOurAgent(record())).toBe(false); + expect(isAgentRecordGone(record())).toBe(false); + expect(stopAgentByRecord(record(), 0)).toBe(false); + expect(calls.signals).toEqual([]); + }); + }); + + test.skipIf(process.platform !== 'win32')('the in-process start time equals the CreationDate earlier releases recorded', () => { + const child = Bun.spawn([process.execPath, '-e', 'setInterval(() => {}, 1000)'], { stdio: ['ignore', 'ignore', 'ignore'] }); + try { + for (const target of [process.pid, child.pid]) { + const script = `(Get-CimInstance Win32_Process -Filter 'ProcessId = ${target}' | Select-Object CreationDate | ConvertTo-Json -Compress)`; + const legacy = childProcess.spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { encoding: 'utf8', windowsHide: true, timeout: 60_000 }); + expect(legacy.status).toBe(0); + const recorded = JSON.parse(legacy.stdout).CreationDate; + expect(recorded).toMatch(/^\/Date\(\d+\)\/$/); + expect(win32CreationTimeSource.read(target)).toBe(recorded); + expect(readAgentStartTime(target)).toBe(recorded); + } + } finally { + child.kill(); + } + }, 150_000); + + test.skipIf(process.platform !== 'win32')('a live agent whose identity cannot be read blocks a second agent', () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-unknown-')); + const script = path.join(tmpDir, 'fake-agent.ts'); + fs.writeFileSync(script, '// no-op\n'); + const live = Bun.spawn([process.execPath, '-e', 'setInterval(() => {}, 1000)'], { stdio: ['ignore', 'ignore', 'ignore'] }); + writeAgentRecord(tmpDir, { pid: live.pid, gen, startTime: birth, startedAt: 0, ownerPid: process.pid, ownerStartTime: birth }); + const original = childProcess.spawnSync; + const probe = spyOn(childProcess, 'spawnSync').mockImplementation(((command: string, args: string[], options: any) => ( + command === 'powershell.exe' ? { status: null, stdout: '', stderr: '' } : original(command, args, options) + )) as typeof childProcess.spawnSync); + const read = spyOn(win32CreationTimeSource, 'read').mockImplementation(() => undefined); + const origSpawn = (Bun as any).spawn; + let spawned = 0; + (Bun as any).spawn = () => { spawned++; throw new Error('a second agent must not start'); }; + try { + expect(spawnTerminalAgent({ stateFile: path.join(tmpDir, 'state.json'), serverPort: 12345, ownerPid: process.pid, cwd: tmpDir, scriptPath: script })).toBeNull(); + expect(spawned).toBe(0); + expect(isProcessAlive(live.pid)).toBe(true); + } finally { + (Bun as any).spawn = origSpawn; + read.mockRestore(); + probe.mockRestore(); + live.kill(); + fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5 }); + } + }); +}); diff --git a/captain/templates/CREW.md b/captain/templates/CREW.md index 64a01fc96..e6bdf2806 100644 --- a/captain/templates/CREW.md +++ b/captain/templates/CREW.md @@ -90,8 +90,9 @@ Homes are paths in the gstack checkout the lane checked at session start. 14. **Don't merge `BASE` into a READY PR.** Only on the controller's word after a real-code train conflict (merge, never rebase, free suite, READY again) or as part of the stamp - commit. Home: `docs/captain.md` (Merge trains), `docs/ship-policy.md` (Run a merge - train). + commit. A merge whose product diff is unchanged carries the /ship receipt; a rebase + onto a new tree costs a full /ship. Home: `docs/captain.md` (Merge trains), + `docs/ship-policy.md` (Run a merge train, Carrying a receipt). 15. **CHANGELOG entry under `## [Unreleased]` before READY;** version files stay at `BASE`'s version; the stamp touches only `STAMP_FILES`. Home: `docs/ship-policy.md` diff --git a/captain/templates/brief.md b/captain/templates/brief.md index d185bc0bf..1f6b0decb 100644 --- a/captain/templates/brief.md +++ b/captain/templates/brief.md @@ -14,7 +14,7 @@ Spend cap: 1. Plan (when Plan: required). After the session-start install check, install for autoplan and follow autoplan/DRIVER.md "On Capy" (launch file sourced, GSTACK_AUTOPLAN_CHECKPOINT_DIR - set, run dir under ~/.capy/work). Write the plan with its ## Before → after, + set, run dir under ~/.capy/work). Write the plan with its ## ELI5, ## Before → after, ## Why it matters, ## What caused this work, ## Big decisions and ## Implementation plan sections, then run gstack-autoplan next --out --plan sized to this brief (a one-file fix: --no-ui --no-dx --max-rounds 1 --estimate-usd @@ -25,7 +25,8 @@ Spend cap: (gstack-autoplan answer --out --gate-rev --reply --rec-hash --by agent: --owner-reply ""), incorporate every accepted plan change (revise), finish every reopened phase, and start product edits only when the run - reports APPROVED. Then gstack-approvals import --autoplan --by "". + reports APPROVED (a later gate that asks nothing new prints CARRIED: and needs no second + ask). Then gstack-approvals import --autoplan --by "" (--stack b1,b2 for a stack). New scope you take on part-way goes back to step 1 with its own plan. 3. Ship. CHANGELOG entry under [Unreleased]; GUARD_CHECKS, pregate and /ship at the final head; one unstamped READY block (captain/templates/READY.md) to me; the PR body carries diff --git a/captain/templates/plan-ask.md b/captain/templates/plan-ask.md index fb298017f..854998ffc 100644 --- a/captain/templates/plan-ask.md +++ b/captain/templates/plan-ask.md @@ -7,6 +7,9 @@ shape from an autoplan run; write it by hand for any other plan. ```text Decision needed on : . Reply **rec** to take every recommendation. +## ELI5 +<5-10 plain sentences: what changes, for whom, and what it costs> + ## Before → after diff --git a/capy/skill/gstack/SKILL.md b/capy/skill/gstack/SKILL.md index d0e793395..bb629e753 100644 --- a/capy/skill/gstack/SKILL.md +++ b/capy/skill/gstack/SKILL.md @@ -42,6 +42,8 @@ Run directories and scratch on Capy live under `~/.capy/work/` (`--out ~/. Capy checklist for `/autoplan`: drive `gstack-autoplan`, never a hand adaptation presented as a run. Relay `gstack-gate render /gate.json --all` with `rec` (every recommendation, plan changes included) as the one-word default; answer with `--by agent: --owner-reply ""`. Set `GSTACK_AUTOPLAN_CHECKPOINT_DIR` to a private project-user Drive folder; after machine replacement, `gstack-autoplan resume --out --from ` restores the newest valid checkpoint. +Token caps on /ship: pass a brief's cap as `--token-cap `. /ship reads `cost.tokens` from `tools.thread.get({ thread_id: "this" })` (one execute program returning only that number) into `gstack-ship-budget --reading ` and obeys `verdict=` (`docs/ship-budget.md`). + ## Plan, approve, ship Every Capy thread that uses gstack follows these for new work, under a Captain or on its own. The rule in full is `docs/captain.md`, "Plan before build"; the lane side is section 3 of captain.md in this folder. diff --git a/capy/skill/gstack/captain.md b/capy/skill/gstack/captain.md index d403cbe55..057573665 100644 --- a/capy/skill/gstack/captain.md +++ b/capy/skill/gstack/captain.md @@ -48,6 +48,7 @@ gstack-approvals add --ask "Spend up to \$40 on a paid eval rerun for the ship c gstack-approvals add --outcome standing --ask "Merge #3330 when green" \ --words "yes merge when green" --by "Garry, 2026-10-16 (Captain rule)" --scope "every crew PR, through a train" gstack-approvals import --autoplan --by Garry # after gstack-autoplan answer; idempotent +gstack-approvals import --autoplan --by Garry --stack b1,b2 # a stacked PR set: every branch, or none gstack-approvals render # the ## Approvals section ``` @@ -93,15 +94,15 @@ project can follow it: the plan names (docs, trains, cleanups) included, and carry them through to done with no further ask. Say in one line what it covers. For an autoplan gate, "do it" answers as `rec`; record the words. -For an autoplan run, write parts 1 to 4 as `## Before → after`, `## Why it matters`, -`## What caused this work` and `## Big decisions` sections in the plan. Then, at the gate: +For an autoplan run, open the plan with `## ELI5` (5-10 plain sentences), then write parts 1 to 4 as +`## Before → after`, `## Why it matters`, `## What caused this work` and `## Big decisions` sections. Then, at the gate: ```bash gstack-owner-brief render --captain --out ``` -It prints a header line ("Decision needed … Reply **rec** …"), the four plan sections (each capped, with a -pointer to the plan for the rest), and "What we need from you", which lists every choice `rec` takes, in +It prints a header line ("Decision needed … Reply **rec** …"), the `### ELI5` summary (on a run whose gate +carries `eli5`), the four plan sections (each capped, with a pointer to the plan for the rest), and "What we need from you", which lists every choice `rec` takes, in words, and closes with the "do it" reply, then a `### Cost` section (spent so far, worst case, and the estimate for the phases `rec` can reopen). The last line, "For the relaying agent", carries the run, `gate_rev`, `rec_hash` and the exact `gstack-autoplan answer` command. Relay everything above that line. When the reply comes back: @@ -112,6 +113,11 @@ gstack-autoplan answer --out --gate-rev --reply rec --rec-hash gstack-approvals import --autoplan --by ``` +A later gate that asks nothing new is answered for you with the words you recorded (`CARRIED:`, then `APPROVED:`); +the brief says "Nothing pending. Carried forward", so import and build without a second ask. `CARRY_CHECK:` means +one reviewer from another model family reads the unreviewed delta first (`gstack-autoplan check`). Anything +else prints `CARRY: no ()` and goes to the person as today (`docs/unattended.md#carry-forward`). + If the person answers in words ("split it into two PRs"), map the words to tokens, answer, and confirm in one line what you recorded ("Recorded: split into two PRs; everything else as recommended"). A plan missing a section renders "Not ready for approval" with no reply invitation, and exits 1 (`CAPTAIN_BRIEF_INCOMPLETE`): @@ -142,3 +148,8 @@ Every PR you send READY on, and the READY report itself, has: The READY report attaches the key image (Capy message attachment), so the Captain can show it inline. /ship does all of this when `GSTACK_CAPY=1` (its `capy-pr` section). Outside Capy, the PR body is unchanged. + +A token cap in a brief goes to /ship as `--token-cap `. When /ship stops on it (`STOP: +reason=budget_exhausted`, `status=incomplete`), the lane reports the BUDGET and RECOVER lines and asks the +owner; it never raises the cap itself. The owner's answer runs the RECOVER line with +`--approved-by --words ""`, and `gstack-approvals add` records the same words. diff --git a/docs/OPENCLAW.md b/docs/OPENCLAW.md index 325c8d72d..d376b873a 100644 --- a/docs/OPENCLAW.md +++ b/docs/OPENCLAW.md @@ -181,9 +181,10 @@ The agent should: 4. Verify with a test spawn **Native skills or ACP.** `./setup --host openclaw` (or `./setup` run inside an -OpenClaw session) gives OpenClaw's own agent gstack's skills: one `gstack` -router skill in `$OPENCLAW_STATE_DIR/skills`, rendered with OpenClaw's tool -names and pointing at the installed gstack, so the agent runs gstack's +OpenClaw session) gives OpenClaw's own agent gstack's skills: the five task +skills (review, investigate, qa, ship, plan-eng-review) listed directly and one +`gstack` router skill for the rest in `$OPENCLAW_STATE_DIR/skills`, rendered +with OpenClaw's tool names and pointing at the installed gstack, so the agent runs gstack's workflows and helpers itself. Use ACP when the work should happen in a Claude Code session with the full install (hooks, Claude tool names); use native skills when the OpenClaw agent should do it. Both can be installed together. diff --git a/docs/PROJECT_STRUCTURE.md b/docs/PROJECT_STRUCTURE.md index 4b0e01ca4..6c99766c2 100644 --- a/docs/PROJECT_STRUCTURE.md +++ b/docs/PROJECT_STRUCTURE.md @@ -92,6 +92,7 @@ gstack/ │ ├── test/ # Integration tests │ └── dist/ # Compiled binary ├── agents-digest/ # Committed 2KB instruction-tier rules digest (gstack-AGENTS.md) for rules-reading hosts +├── modules/ # loadouts.json (+ loadouts.schema.json): model rungs, pinned modules and named loadouts; read by scripts/modules.ts, rendered by bin/gstack-modules (docs/loadouts.md) ├── extension/ # Chrome extension (side panel + activity feed + CSS inspector) ├── lib/ # Shared libraries (aside-render.ts = local-HTML rendering, Aside first, engine fallback; design-catalog.ts = the typed design anti-pattern catalog every design skill renders from; design-lint/ = the static and render tiers behind bin/gstack-design-lint, ported from hallmark's sloplint; design-detect-contract.ts = detector sentinel vocabulary; design-md.ts = open DESIGN.md reader/writer; dom-dump-script.ts + generated dom-dump.js = rendered-DOM dump for the detector; review-evidence.ts = review-start receipt binding, computed freshness and shared-code snapshot eligibility; frontend-scope.ts; claude-bin.ts, error-handling.ts, worktree.ts, egress-receipt.ts, context-bill.ts, redact-engine.ts, tracker-guard.ts, version-source.ts, code-intelligence/) │ └── diagram-render/ # Vendored mermaid + excalidraw runtimes, built into one offline bundle the renderer loads diff --git a/docs/TESTING_INTERNALS.md b/docs/TESTING_INTERNALS.md index 549999ec0..13cb03aa8 100644 --- a/docs/TESTING_INTERNALS.md +++ b/docs/TESTING_INTERNALS.md @@ -783,6 +783,14 @@ once, plus cleanup. Each still has 120 seconds of model work. Its 17 workflow judges own their deadline and abort signal, with five seconds for terminal recording inside a ten-second Bun grace; the other 11 retain their existing 120-second Bun timeout. Late responses cannot create records or cache passes. +When a judge's abort signal cancels its request, `callJudge` +(`test/helpers/llm-judge.ts`) prints one `llm-judge-aborted` JSON line to +stderr: elapsed time, wrapper `attempts` and `retryWaitsMs` (429 waits), +`httpRequests` and `httpStatuses` (so SDK retries show), `connectedMs`, +`firstEventMs` and `lastEventMs`, the open `block` type, `thinkingChars` and +`textChars`, `messageId`, `requestId` and the `reason` (at most 200 +characters). It holds counts and ids only, never content, and changes no +request, score or verdict. The ship documentation file reserves 4,920 seconds for four 600-second cases and eight 300-second fault cases, run once, plus cleanup; in CI each case runs as its @@ -967,8 +975,8 @@ with `GSTACK_FREE_RETRY_FLAKY=0`. A stock Ubuntu 24.04 VM differs from a GitHub-hosted runner in three ways that the scripts correct: the login umask is `002` (group-writable directories fail the CSO private-state checks), AppArmor blocks the unprivileged user -namespaces Chromium's sandbox needs, and `clang` and `python3-venv` are absent -(required by the Dia readiness and Python runner tests). +namespaces Chromium's sandbox needs, and `python3-venv` is absent (required by +the Python runner tests). VMs are named `ubirun---`, plus a `-t` TTL suffix (below); `` is `UBI_OWNER` (set it to the thread id on a Capy machine; @@ -1427,7 +1435,13 @@ Free-suite flake rules: every shard child's `GIT_CONFIG_*` pairs as a backstop, so it covers fixtures that inherit the environment, and `bun run scripts/ship-measure.ts free --backend local` measures with that environment; a fixture with its own - replacement env never sees the backstop. + replacement env never sees the backstop. Neither does the receiving side of + a push to a local path: git's local transport drops `GIT_CONFIG_*` from the + `receive-pack` it starts, so every push into a fixture's bare origin still + leaves a detached maintenance run in that origin. A fixture that clones such + an origin passes `--no-local` (`coordinatorClone` in + `test/helpers/ship-queue-fixture.ts`), so the clone reads it through git's + transport instead of copying `objects/` entry by entry. To reproduce a ledger entry, take the shard's exact file list from the CI run's `free-plan` artifact, then rerun it with the flaky retry off on a CI-mirrored VM: @@ -1523,10 +1537,10 @@ on win32, drives a POSIX signal path) leaves it through a the file moved. Native qualification campaigns (Windows cookie extraction, Windows launch -diagnostics, Dia on macOS) run only on dispatch of `native-qualification.yml`: +diagnostics) run only on dispatch of `native-qualification.yml`: ```bash -gh workflow run native-qualification.yml --ref -f mode= +gh workflow run native-qualification.yml --ref -f mode= ``` ### Real-setup install fixture diff --git a/docs/TEST_PORTFOLIO.md b/docs/TEST_PORTFOLIO.md index ef393a88b..78510a41e 100644 --- a/docs/TEST_PORTFOLIO.md +++ b/docs/TEST_PORTFOLIO.md @@ -60,7 +60,7 @@ depends on measured duration or an explicit `QUICK_CORE` entry, not this table. | CLI/API/webhook QA without browser setup | `qa-functional-fixture`, `qa-functional-evidence`, `qa-lazy-sections` | `skill-e2e-qa-functional`: CLI and webhook report sessions | Linux/macOS free; selected PR gate; Windows only where curated | | Report-only preserves local and remote authority | `qa-only-capability`, `qa-functional-observer`, `qa-functional-observer-atomic`, `qa-caller-authority` | Independent report-only sessions with synthetic owned endpoints/auth | Linux kernel observation; free callback controls plus selected PR gate | | Repair reproduces the defect, adds a failing regression and rechecks adjacent behavior | `qa-fix-loop-fixture`, `qa-functional-evidence` | `skill-e2e-qa-functional-fix`: CLI and webhook repair sessions | Free controls plus selected PR gate | -| Review and Ship actually explore | `qa-exploratory-callers`, `qa-caller-report-observer`, `qa-checkpoint-evidence` | `skill-e2e-qa-callers`: actual Review/Ship callers | Free captures plus selected PR gate | +| Review and Ship actually explore | `qa-exploratory-callers`, `qa-caller-report-observer`, `qa-caller-review-plan`, `qa-checkpoint-evidence` | `skill-e2e-qa-callers`: actual Review/Ship callers | Free captures plus selected PR gate | | Smoke expiry preserves required plan checks | `qa-deadline`, `qa-deadline-selection`, `qa-browser-deadline-evidence` | `ship-exploratory-plan-checks` | Free deadline/dispatch controls plus selected PR gate | | Late changes invalidate affected results | `qa-caller-freshness-order`, `qa-deadline-publication-observer`, `shared-libs-revalidation-prompt` | `ship-exploratory-late-input` and the existing late-input documentation handoff | Free stale-input controls plus selected PR gate | | Documentation completes before publication and respects protected files | `docsync-authority`, `docsync-atomic-writes`, `docsync-report-interface`, `docsync-lifecycle-interface` | `skill-e2e-ship-docsync`, `skill-e2e-docsync-spawned` | Free state/permission controls; registered gate/periodic scenarios retain their tiers | diff --git a/docs/captain.md b/docs/captain.md index b81988be2..e955acfb7 100644 --- a/docs/captain.md +++ b/docs/captain.md @@ -138,8 +138,9 @@ this rule shipped cites this section by name. **What the lane sends.** The plan and its gate in plain language a person outside the project can follow: what changes, why now, what the change does, what it costs, the lane's pick, and the recommended one-word reply. `gstack-owner-brief render --captain --out ` -prints that from the plan's `## Before → after`, `## Why it matters`, -`## What caused this work` and `## Big decisions` sections, with the cost lines +prints that from the plan's `## ELI5`, `## Before → after`, `## Why it matters`, +`## What caused this work` and `## Big decisions` sections (also saved as `eli5` in +`gate.json`, so `gstack-gate render` opens with them), with the cost lines (`GATE_SPEND:`, `GATE_REC_COST:`) and a last line for the controller; a plan missing a section exits `CAPTAIN_BRIEF_INCOMPLETE`, so the lane adds the section and renders again ([capy/skill/gstack/captain.md](../capy/skill/gstack/captain.md) § 3 lists them). The lane @@ -156,10 +157,12 @@ controller and been answered into the run every accepted plan change has been incorporated (`revise`), every reopened phase has finished, and the run reports `APPROVED` (`status=complete` after `export`). An answered gate that still prints `PLAN_AMEND_PENDING` or `REOPENED:` is not a completed plan, and an -imported approval row alone is not completion. +imported approval row alone is not completion. A later gate revision that asks nothing new +is answered with the owner's recorded words and says `CARRIED:`; that is the owner's word, +not a new ask ([carry-forward](unattended.md#carry-forward)). -**The record.** `gstack-approvals import --autoplan --by ""` writes the -approval row (date, the ask, the owner's exact words, the lane that answered as relayer, +**The record.** `gstack-approvals import --autoplan --by ""` (with +`--stack ` for a stacked PR set) writes the approval row (date, the ask, the owner's exact words, the lane that answered as relayer, what it covers); `gstack-approvals render` puts it in the report and the PR body. Before training the PR the controller compares that row's words and `gate_rev` with the ask it relayed and the reply it carried back; a row that does not match is not READY (shape A). @@ -231,6 +234,14 @@ a push included. The sequence that works unattended on Capy: 10. After the slot call, the stamp commit keeps the pin's receipt; re-READY with the same receipt, no second /ship. +When the base moves under a reviewed branch, merge it in; never rebase. A merge that +leaves the product diff unchanged carries the receipt with `gstack-ship-receipt carry` +(pregate at HEAD, no review rerun), and a merge whose resolution changed product code +needs a fresh /ship. A rebase carries only onto a tree the receipt already covers with +the same product diff; any other rebase is a full /ship +([ship-policy.md](ship-policy.md#receipt-carry)). A controller never asks a lane to +rebase a reviewed branch. + ## Merge trains gstack's queue tool drives trains when the repository's `.gstack/ship-policy.json` carries diff --git a/docs/capy-install.md b/docs/capy-install.md index 1bed678f9..7de24710e 100644 --- a/docs/capy-install.md +++ b/docs/capy-install.md @@ -155,7 +155,16 @@ and `/proc` start time; elsewhere `ps -o lstart`), because a pid is reused after a reboot or a machine wake. `bin/gstack-upgrade`, and so the session-start self-upgrade, refuses with [UPGRADE_BUSY](troubleshooting.md#upgrade-busy) while a lease held by a live process outside its own chain exists, naming each -holder as `pid

(m )`. The team-mode SessionStart hook +holder as `pid

(m )`. The install-mode self-upgrade also +defers while its own chain holds a live lease under 120 minutes old. An install +run from inside a workflow (/ship's docs step running `install.sh --for +document-release`, #3571) prints `SELF_UPGRADE: skipped (a gstack run in this +session holds a workflow lease on this installation: ... (UPGRADE_BUSY))`, +leaves the checkout where the run started and stays ok with `behind=`. Each +`gstack-skill-start` renews the lease. On Capy the leased pid is the machine's +long-lived `capy-server`, so the deferral ends when the lease turns 120 +minutes old, not when the process exits; `bin/gstack-upgrade` run by hand +moves the checkout sooner. The team-mode SessionStart hook (`bin/gstack-session-update`) honors the same leases: it logs `SKIP leased pid=

/m` to `analytics/session-update.log` and tries again at the next session start, without writing its hourly throttle stamp. A lease whose @@ -274,7 +283,16 @@ keeps the lease. `bin/gstack-lease list` shows `alive|dead|stale`, and honoured, the resolved Bun (`bun_path`, `bun_version`, `bun_rule`, and `bun_install` when this run downloaded it), the resolved Node when the project pins one (`node_path`, `node_version`, `node_rule`), the trailer, the remote - minimum, the launch PATH and the time. Admission refuses a workflow whose + minimum, the launch PATH and the time. An ok run (install or `--check`) at + the same checkout, project, HEAD and Bun as an earlier ok verdict keeps what + that verdict certified, so one machine stays admitted for /ship and its + `--for document-release` docs step (#3561): `required` becomes the union, + pins count as planning-only only when both runs skipped them, and the + verdict's `for` lists every workflow, comma-separated (`for=ship,document-release`; + the installer prints `the install verdict at keeps for= and adds + (for=)`, and the trailer still names this run's workflow). A + failing run, a new HEAD or another Bun replaces the verdict, and so does any + workflow install over a review-voice verdict. Admission refuses a workflow whose running Bun is not the one the verdict recorded ([BUN_RESOLUTION_DRIFT](troubleshooting.md#bun-resolution-drift)), and so do the pregate's lanes and guards, which also refuse an invalid verdict diff --git a/docs/evals/detector-inventory.md b/docs/evals/detector-inventory.md index 4b962f410..a2667434c 100644 --- a/docs/evals/detector-inventory.md +++ b/docs/evals/detector-inventory.md @@ -63,7 +63,7 @@ The plan-ceo-review-plan-mode (:89, :108), plan-devex-review-plan-mode (:181-222 | auq-format-gate | test/skill-e2e-ask-user-question-format-compliance.test.ts:58 | question ~ `options differ in kind` | AUQ tool input | yes | (c) | | auq-format-gate | test/skill-e2e-ask-user-question-format-compliance.test.ts:61, :68 | recommendation substance ≥ 4 | — | — | judge | | plan-tune-inspect | test/skill-e2e-plan-tune.test.ts:167-169, :185 | output names ≥2 of 3 seeded question IDs or aliases | question-log is seeded fixture input | yes (inspection report) | (c) | -| plan-review-report | test/skill-e2e-plan.test.ts:463-491 | plan.md `## GSTACK REVIEW REPORT`, CEO/Eng/Design rows, ends with `NO UNRESOLVED DECISIONS` or a bullet | rows come from the seeded review log; the table is rendered | yes | (c) | +| plan-review-report | test/skill-e2e-plan.test.ts:472-500 | plan.md `## GSTACK REVIEW REPORT`, CEO/Eng/Design rows, ends with `NO UNRESOLVED DECISIONS` or a bullet | rows come from the seeded review log; the table is rendered | yes | (c) | ### test/skill-e2e-design.test.ts (gate cases) @@ -89,7 +89,7 @@ The plan-ceo-review-plan-mode (:89, :108), plan-devex-review-plan-mode (:181-222 |---|---|---|---|---|---| | shared-libs-read-only | test/skill-e2e-shared-libs.test.ts:113-120 | report ~ uncommitted/overlay/raw, tip and branch SHAs, retry-worker/route, no blob link for branch-only file | none (read-only by contract) | yes | (c) | | shared-libs-unsupported-git | test/skill-e2e-shared-libs.test.ts:136, :144 | report ~ unavailable/unsupported/limited; not "no commits/PRs found" | none | yes | (c) | -| shared-libs-review-path-eligibility | test/skill-e2e-shared-libs-paths.test.ts:133-134 | `trace + output` ~ submodule/160000, check-ignore/ignored (output alone satisfies) | Bash command trace (first operand) | no | (b) | +| shared-libs-review-path-eligibility | test/skill-e2e-shared-libs-paths.test.ts:134-135 | `trace + output` ~ submodule/160000, check-ignore/ignored (output alone satisfies) | Bash command trace (first operand) | no | (b) | ### test/skill-e2e-ship-docsync.test.ts, test/skill-e2e-docsync-spawned.test.ts diff --git a/docs/hosts.md b/docs/hosts.md index df863d1ce..8750cbbf1 100644 --- a/docs/hosts.md +++ b/docs/hosts.md @@ -24,6 +24,14 @@ neither does `./setup --local`. **What it writes.** Copies in the harness's own skills folder, never edits to `openclaw.json`, Hermes's `config.yaml` or any context file you did not name. +A context block is opt-in: `gstack-harness register openclaw|hermes|generic +--context ` writes the marked block into that file only, after printing +the file and its scope (`profile` inside the harness's own home, else +`project`). Setup, upgrades and refresh never add one, a block you delete stays +deleted, a second `--context` file keeps the first (the ledger keys blocks by +file), and uninstall restores each file byte for byte. It refuses `SOUL.md`, +and for Hermes a new file that would outrank rules Hermes loads now +(`.hermes.md`/`HERMES.md` load before `AGENTS.md`): `HARNESS_CONTEXT_REFUSED`. Every file goes into a ledger, `$GSTACK_STATE_ROOT/harness/.ledger`, with its sha256. Registering again changes only what changed; a folder or skill name gstack did not write stops it (`HARNESS_UNOWNED_ENTRY`); `gstack-uninstall` @@ -35,10 +43,24 @@ when it is the one gstack wrote; an edited block is left for you. `./setup `gstack-harness status` lists them and runs the harness's own skill list where it has one (`visible to harness: yes`). Errors: [troubleshooting](troubleshooting.md#agent-harnesses-gstack-harness). +**Registered, listed, used.** These are three separate facts, and this page +claims only the first two. *Registered*: gstack's files are in the harness's +skills folder and its ledger (`gstack-harness status`). *Listed*: the harness +puts the skill in the skills section of the model's prompt (`visible to +harness: yes`, from the harness's own skill list). *Used*: in a task that fits, +the model opens the matching skill and runs its first step. Use rates are +pending HARN-5's fixed panel (OpenClaw and Hermes chat mode, five trials per +cell). When they land they are measured under the eval adapter's +`GSTACK_SESSION_KIND=spawned` marker, which auto-decides gstack's questions, so +they say nothing yet about interactive sessions. Two levers aim at use: +each router line opens with the skill's own trigger sentence ("Use when asked +to ..."), and each Hermes description opens with a trigger list of at most 57 +characters, the part of a description Hermes's skills index shows. + | Harness | What gstack registers | Install | Verify | Remove | |---|---|---|---|---| -| OpenClaw | one `gstack` router skill (one description line in every request; its body lists every skill and its path) in `${OPENCLAW_STATE_DIR:-~/.openclaw}/skills/gstack`; `--skills all` registers every skill as its own top-level folder | `./setup --host openclaw`, or `./setup` inside OpenClaw | `openclaw skills list --json` shows `gstack` (source `openclaw-managed`, eligible) | `gstack-harness unregister openclaw` | -| Hermes | every skill, as `gstack-` in one `gstack` category, in `${HERMES_HOME:-~/.hermes}/skills/gstack` (Hermes opens only skills it has indexed) | `./setup --host hermes`, or `./setup` inside Hermes | `hermes skills list` shows the `gstack-*` skills in category `gstack` | `gstack-harness unregister hermes` | +| OpenClaw | default `--skills hybrid`: `gstack-review`, `gstack-investigate`, `gstack-qa`, `gstack-ship` and `gstack-plan-eng-review` as top-level skills plus one `gstack` router skill whose body lists every other skill and its path, in `${OPENCLAW_STATE_DIR:-~/.openclaw}/skills`. With OpenClaw 2026.10.6's 19 eligible bundled skills, hybrid's skills section is 10,290 characters, full format, under its 18,000-character budget; `--skills all` (17,971, compact format, descriptions cut) lists every skill as its own folder, `--skills router` (6,701) only the router | `./setup --host openclaw`, or `./setup` inside OpenClaw | `openclaw skills list --json` shows `gstack` and the five task skills (source `openclaw-managed`, eligible) | `gstack-harness unregister openclaw` | +| Hermes | every skill, as `gstack-` in one `gstack` category, in `${HERMES_HOME:-~/.hermes}/skills/gstack`. Hermes's skills index lists only skills registered as folders, so a router would leave the rest out of the listing (`skill_view` still loads an unlisted skill by name, but nothing tells the model it exists) | `./setup --host hermes`, or `./setup` inside Hermes | `hermes skills list` shows the `gstack-*` skills in category `gstack` | `gstack-harness unregister hermes` | | dots (feder-cr) | the `gstack` router in `/home/dot/skills/gstack`, which the Dot lists every turn | `./setup` on the Dot's computer, or `gstack-harness register dots` | the Dot's Skills page, or `GET /skills` | `gstack-harness unregister dots` | | QM | **not available yet.** QM imports a skill pack by cloning the whole repository and caps it at 32 MiB and 5,000 files; gstack's repository is about 73 MiB, so `gstack-harness register qm --yes` stops before sending anything ([why](troubleshooting.md#harness-qm-pack-too-large)) | meanwhile, paste `gstack-harness register generic --print` into the agent's instructions | ask it for a gstack skill | delete the pasted text | | Muse Code, Grok Build | nothing: both read `~/.claude/skills`, so the Claude install (`./setup`) is what they see, with Claude tool names | `./setup` | `gstack-harness status` runs `muse skills list` / `grok inspect` and reports *discovered (Claude-rendered, unverified)* | `gstack-uninstall` | diff --git a/docs/loadouts.md b/docs/loadouts.md new file mode 100644 index 000000000..f065842d5 --- /dev/null +++ b/docs/loadouts.md @@ -0,0 +1,40 @@ +# Module loadouts + +gstack can render a smaller or larger set of its instructions for a given model. Each toggleable piece is a **module** with an id. A **loadout** is a named set of modules, and `modules/loadouts.json` maps each model **rung** to a loadout. Today every rung loads `full`, which is the same render gstack has always shipped. A loadout changes only when the shared skill eval (GSTA-2) measures a smaller one that matches `full` within its preregistered margin. + +Install-time model detection, which picks a loadout for the model you run, ships with the first loadout that is not `full`. Until then, loadouts are an eval tool: `bin/gstack-modules render` produces any loadout as a byte-exact tree with a lock file. + +## Terms + +| Term | Meaning | +|---|---| +| Module | One of four kinds. `skill:

` is a whole skill. `section:/` is one entry of `/sections/manifest.json`. `overlay:` is one `model-overlays/.md`; excluding a base overlay also removes the base's text from every overlay that inherits it; the inheriting overlay's own text stays. `preamble:` is one piece of the shared preamble (`PREAMBLE_PIECES` in `scripts/resolvers/preamble.ts`). | +| Pinned | A module no loadout can remove where `full` renders it: the start command, plan-mode rules, the question format, completion status, the unattended profile, /ship's review army and adversarial pass, the router and `/gstack-upgrade`. A skill's `preamble-tier` still applies, so a tier-1 skill has no question-format section in any loadout. | +| Rung | How much scaffolding a model gets: `frontier`, `strong`, `mid`, `light`, or `unknown`. Model ids are matched after lowercasing and stripping a `provider/` prefix (`anthropic/claude-haiku-5-5` is `mid`). Rungs are separate from the frontier/smart tiers in `lib/model-catalog.ts`, which choose which model runs a role. | +| Loadout | `{ base, exclude, include, preamble_tier_max, note }`. `full` (include `*`) is always present. An unknown model gets `default.unknown`, which is `full`. | + +## Commands + +```bash +bin/gstack-modules list [--json] [--pinned] # every module id, kind, source, pin, source bytes and sha256 +bin/gstack-modules validate # check modules/loadouts.json against the catalog +bin/gstack-modules render --host claude --loadout full --out-dir ~/arms/control +bin/gstack-modules render --host claude \ + --modules 'full,-section:office-hours/second-opinion,-section:office-hours/visual-design' \ + --out-dir ~/arms/oh-lean +``` + +`render` writes the whole host tree into a staging directory beside `--out-dir`. It checks that no rendered file still points at an excluded module, writes `loadout.lock.json` last (loadout name or `adhoc`, the normalized spec and its sha256, host, model, every excluded id, and the sha256 and byte count of every file), then swaps the result into place. A failure leaves an earlier render at `--out-dir` untouched. Claude section links name `--out-dir`, so point the eval harness at that directory. Pass the same `--model`, `--install-root` and `--plan-mode` the install under test uses, so the arms differ only by the modules. Codex renders default to the host's generic `gpt` overlay, while `./setup` uses `gpt-6-astra`. + +`bun run gen:skill-docs --loadout --out-dir ` and `--modules --out-dir ` apply the same filter to a generation run without the staging, dangling-reference check or lock file; a selection with exclusions and no `--out-dir` is refused with `MODULE_SPEC_INVALID`, because the committed tree is always the `full` render. A non-`full` render adds `` to each SKILL.md header. + +## Building an eval arm + +1. Render the control with `--loadout full` and each arm with `--modules full,-,…`. Every refusal names its code and fix ([troubleshooting](troubleshooting.md#module-loadouts-gstack-modules)). +2. Preregister the lock files' `spec_sha256` and per-file sha256 values with the eval. +3. Excluding a section removes its STOP pointer, its Section-index row and its file. The step becomes `> Not loaded in the loadout: skip . Do not offer it, and treat it as not run.` Skeleton text that belongs to the section, such as office-hours' Phase 3.5 offer, sits inside `{{IF_SECTION:}}…{{/IF_SECTION}}` in the template and goes with it. +4. The autoplan runner (`gstack-autoplan`) reads review methodology from the source tree, not from a rendered loadout, so autoplan-runner arms always measure `full` methodology. + +## Changing a loadout + +Add or edit an entry under `loadouts` and cite the GSTA-2 run (preregistration, margin, per-rung result) in its `note` and in the PR body. A model-specific loadout that wins a preregistered comparison is allowed even if it breaks the expected nesting (light ⊇ mid ⊇ strong). Committed SKILL.md files are always the `full` render, so the parity suite, the SKILL.md size guard, the size ledger and the catalog and context budgets keep measuring `full`. diff --git a/docs/pregate.md b/docs/pregate.md index a42b37831..1e8698852 100644 --- a/docs/pregate.md +++ b/docs/pregate.md @@ -146,7 +146,12 @@ Two stages with separate clocks, both printed: ~2.5 s for `regen` and under 200 ms for each of the others): - `regen`: every registry entry whose inputs or outputs are touched is fresh - (`gstack-regen check` in a scratch worktree). + (`gstack-regen check` in a scratch worktree). A fresh entry with touched + outputs then runs once more with those outputs deleted; the ones the command + recreates byte-identically are the check's `proven` paths, which + `gstack-ship-receipt carry` reads. The verdict comes from the first run: an + output the second run does not recreate, or a second run that fails, is + simply not proven. - `secrets`: `gstack-redact` over the branch's added lines (merge-base to the working tree, untracked files included). HIGH, or MEDIUM in the `secret` category, fails; other MEDIUM findings warn. Cannot be downgraded. @@ -763,11 +768,13 @@ with a timing flake: never raise the bound. ```json { "sealed": { - "paths": ["heldout/**"], + "paths": ["heldout/**", "**/sealed/**"], "transcripts": ["runs/**/transcript*.jsonl"], + "allow_paths": ["**/sealed/*/MANIFEST.json", "**/protected/MANIFEST.json"], "answer_markers": ["SEALED ANSWER:"], "seed_patterns": ["shuffle_seed=\\d+"], - "local_paths": true } } + "local_paths": true, + "case_insensitive": true } } ``` A repo with a `sealed` key gets a configured local check against accidental @@ -787,8 +794,38 @@ gstack-pregate sealed [--range ] [--remote origin] [--base ] [--js in a later commit); `sealed.answer`, `sealed.seed` and `sealed.local_path` (`/home//`, `/Users//`, `C:\Users\\`) check each commit's added lines. Findings print rule, `file[:line]` and commit, never the text. +- **Globs.** `paths`, `transcripts` and `allow_paths` match the whole + repo-relative path from the repository root. `*` and `?` stay inside one + path segment; `**/` spans zero or more directories; a `**` not followed by + `/` matches across directories (`heldout/**` covers every depth under + `heldout/`); `[` and `{` are literal. So `sealed/**` misses `tasks/x/sealed/a.json`: + to guard a `sealed/` directory wherever it sits, write `**/sealed/**`. +- **Case.** Matching is case-sensitive. `case_insensitive: true` folds case + for `paths` and `transcripts` only, so `**/heldout/**` also catches + `HELDOUT/` and `HeldOut/`. Separator and spelling variants (`hold-out/`, + `held_out/`, `heldout-v2/`) are not folded: list each as its own glob. + The effective value is the base branch's OR the pushed one (it only tightens). +- **Exceptions.** `allow_paths` exempts publishable files that sit next to + sealed data (a `MANIFEST.json` of hashes and counts) from `sealed.path` and + `sealed.transcript`, applied after the deny globs and before waivers. They + are read from the destination base branch only: an exception a push adds + takes effect once it lands on the base branch, so a branch can never widen + its own. They never fold case. An entry whose file name contains `**`, or + is only wildcards before its extension (`**`, `sealed/*`, `**/*.json`, + `sealed/**.json`), is refused; a partial wildcard such as `MANIFEST*.json` + is accepted and matches every file it spells, so name the file. An exempt file is checked by the + text rules only, so configure `answer_markers` when you exempt files next to + sealed data. Each exempt path is listed on every push (`exempt + commit (sealed.allow_paths )`) and counted as + `exempt=` on the `SEALED:` line. +- **Version skew.** A gstack older than the release whose CHANGELOG adds + `sealed.allow_paths` refuses `allow_paths` and `case_insensitive` as + unknown keys, so every push and `gstack-pregate run` in the repository + fail on that machine. Raise `min_gstack_version` in + `.gstack/ship-policy.json` to that release before landing either key. - **Policy.** The union of the destination base branch's `sealed` and the - pushed commit's: a push can tighten it, never relax it. A malformed or + pushed commit's: a push can tighten it, never relax it (`allow_paths` come + from the base branch alone, and a pushed deny glob cannot override one). A malformed or unreadable policy refuses. Waivers come only from the base branch's `.gstack/sealed-allow.tsv` (`rulepathshareason`) and are listed on every push. diff --git a/docs/review-policy.md b/docs/review-policy.md index 149abc89b..bafc25869 100644 --- a/docs/review-policy.md +++ b/docs/review-policy.md @@ -128,26 +128,75 @@ applies no edits is its exit too. ## Review depth by diff class -`gstack-review-plan --base ` classifies the diff and prints the reviewers -the next step dispatches (`REVIEW_CLASS:`, `REVIEW_PLAN:`, one `DISPATCH:` per -reviewer with its effort, one `SKIP:` per reviewer left out, `--json`). A mixed -diff takes its most restrictive class; a `gstack-diff-scope` error fails closed -to code, and code with the gate scan unavailable fails closed to gate. +`gstack-review-plan --base ` classifies the diff, picks a **depth** and prints +the reviewers the next step dispatches: `REVIEW_CLASS:`, `REVIEW_DEPTH: +runtime_lines= rules= reasons=<…> codes=<…>`, `GATE_SCAN: tagged=|unavailable +head=`, one `DEPTH_ERROR:` per input that failed closed, one `DISPATCH:` per reviewer +with its effort and a shell-quoted `DIFF_CMD:` (plus `DIFF_EXCLUDE: none` when it +reads everything), one `SKIP:` per reviewer left out, and `--json` with the same fields. +A plan that fails closed to full exits 0; a diff git cannot list exits 1. -| Class | What it is | Pass 1 dispatches | +**Classes** are unchanged. A mixed diff takes its most restrictive class: **docs** +(markdown no agent or gate reads), **tests** (test files and fixtures), **code** +(everything else, including every `SKILL.md` and template, markdown in a skill +directory, `*/sections/**`, `scripts/resolvers/**`, rule docs, checklists and bins) and +**gate** (code plus auth or migration scope, a hunk the gate scan tags, a deleted code +or test path, CI workflows, credential, state-root and the paths below). + +**Runtime lines** are the changed lines of code-class paths, minus outputs the base +commit's `.gstack/generated.json` registers. Docs, tests and release metadata are never +runtime; a `.tmpl` edit plus its regenerated `SKILL.md` counts the template once. + +| Depth | When | Pass 1 dispatches | |---|---|---| -| **docs** | markdown no agent or gate reads: README, CHANGELOG, TODOS, how-to and explanation docs | the parent's core checklist only | -| **tests** | test files and fixtures only | core plus the testing specialist | -| **code** | everything else, including every `SKILL.md` and template, any markdown in a skill directory, `*/sections/**`, `scripts/resolvers/**`, `docs/*-policy.md`, `docs/captain.md`, `docs/unattended.md`, `docs/pregate.md`, checklists, specialists and bins | specialists by scope (as before), the native adversarial pass, the outside voice; the Red Team past 200 lines or after a CRITICAL | -| **gate** | code plus auth or migration scope, a hunk the gate scan tags (an RH rule: a relaxed threshold, a skipped test), a deleted code file, CI workflows, credential or state-root paths | code's set, plus the Red Team always, at full effort, and no hit-rate gating | +| **light**, runtime 0 | docs and tests only, or only registered outputs | the core checklist only; the outside voice when the diff publishes numbers | +| **light**, runtime 1–50 | `SMALL_DIFF_LINES` or fewer runtime lines | core, one **batched** specialist (testing, maintainability and security checklists, the specialists scope selects and the Red Team prompt in one context), the native adversarial pass (kept: backtest inconclusive, GSTA-147 D5) and the outside voice on numbers | +| **standard** | more than 50 runtime lines | the code set with every threshold (specialists at 50, simplification at 100, Red Team at 200) read on runtime lines; specialists leave docs and registered outputs out of their diff, and every specialist but Testing leaves tests out too; adversarial and outside voice read everything | +| **full** | gate class, or any classifier error | the gate set, unchanged: every reviewer on the whole diff, the Red Team always, no hit-rate gating | -**Numbers keep the outside voice.** On a docs or tests diff the outside voice is -skipped unless the diff publishes numeric claims: `gstack-review-plan` scans the -added lines of every path for percentages, money, multipliers, durations, token -or credit counts and score, rate or speed claims (`NUMBERS: yes`), and a -claim always dispatches it. The claims' fingerprint (`fingerprint=`) is passed -back as `--reviewed-numbers`; when a later fix changes a claim, only the -outside voice reruns, on the numbers. +A fixed blocking finding, a CRITICAL or an open blocker raises a light diff to +standard for the next step (`step=standard`): its specialists read at least 50 lines +and the Red Team runs, so a raise never dispatches less than light did. A fix-check +is the same at every depth. + +**Fail closed.** Each of these makes the depth full and is listed in `errors[]` with +the input it could not read, a sanitized cause and the repair: a `gstack-diff-scope` +error, a gate scan that is unavailable, a base registry that cannot be read or is +invalid (`REGEN_REGISTRY_INVALID` or `REGEN_CONTAINMENT` in `codes=`), a numstat git +could not produce, and a binary code-class path (it is never counted as 0 lines). + +**The registry rule.** Only the base commit's registry counts (the merge base's +`origin/` commit for live /ship and the current base ref's commit for the queue: `origin/` in `ready`, `/` in `train build`), and only +entries with a `command`, which pregate's regen check proves for that tree. An entry +added on the branch never excludes anything; `command: null` entries, vendored code +and lockfiles stay runtime. To adopt it, commit an entry like this on the base branch: + +```json +{ + "$schema": "https://github.com/garrytan/gstack/docs/pregate.md#generated-v1", + "entries": [ + { "id": "skill-docs", "command": "bun run gen:skill-docs --host all", "outputs": ["*/SKILL.md", "*/sections/*.md"], "inputs": ["*/SKILL.md.tmpl", "*/sections/*.tmpl"] } + ] +} +``` + +**Gate paths for the machinery itself.** An edit to `lib/review-depth.ts`, +`lib/review-collect.ts`, `bin/gstack-review-plan`, `lib/review-scope.ts`, +`lib/ship-queue*.ts`, `lib/regen.ts`, `.gstack/generated.json`, +`ship/sections/review-army.md.tmpl`, `ship/sections/adversarial.md.tmpl` or +`scripts/resolvers/review-army.ts` is gate class: changing how much review runs gets +the most review. `rules=` (`DEPTH_RULES`) hashes the deciding constants and patterns, +not file bytes, so a comment edit keeps it. + +**`--depth-floor standard|full`** (a /ship prompt flag, passed to every plan run) +raises the depth and never lowers it. + +**Numbers keep the outside voice.** At light depth the outside voice runs only when +the diff publishes numeric claims: `gstack-review-plan` scans the added lines of +prose and data files for percentages, money, multipliers, durations, token or credit +counts and score, rate or speed claims (`NUMBERS: yes`). The claims' fingerprint +(`fingerprint=`) is passed back as `--reviewed-numbers`; when a later fix changes a +claim, only the outside voice reruns, on the numbers. It always reads the whole diff. **The adversarial and outside voices run once per invocation** (Step 11, on the final tree), as the last full-pass plan lists them; after they ran, decision 2 @@ -166,6 +215,15 @@ default. `gstack-config set review_effort_tiers off` (or `--no-tiers`) runs the audits and watchers at the host default too ([model-policy.md](model-policy.md#reasoning-effort)). +### Behavior changes + +- A tests-only diff (runtime 0) no longer dispatches the Testing specialist: the + core checklist and the gate scan review it. +- Light no longer runs a separate Red Team: the batched specialist carries its + prompt. At runtime 0 light runs no adversarial pass either. +- Standard reads thresholds on runtime lines, not the whole diff, so a test-heavy + diff with few runtime lines dispatches fewer specialists. + ## What the receipt records `gstack-review-scope summary --since ` reads this invocation's @@ -190,6 +248,13 @@ specialist stats they record). The summary line appends `fix_checks=`, `dispatches=` and `est_input_tokens=` only when they were recorded, so an old loop prints the old line. +Beside the counters, `write` records `review_depth` (the depth, runtime lines, +rules hash, base and registry commits, and the gate scan bound to the head) and +the queue refuses a receipt below the depth its head needs +([ship-policy.md#ship-receipt](ship-policy.md#ship-receipt)). A stop the owner +accepted after a fix-check edit goes in `review_loop_exception`, never in prose +under `REVIEW_LOOP:`. + The receipt's summary line prints `passes= blocking_found= deferred=`, which is what a scorecard tracks (target: a median of 1 pass per PR). A receipt carried across a base merge or a test-only fix @@ -268,9 +333,10 @@ trailers, appended }`. ## Where this is enforced -- `scripts/resolvers/review-army.ts`: the floor and `NO FINDINGS` in every specialist and Red Team prompt (rendered into `review/sections/review-army.md` and `ship/sections/review-army.md`), and the lead judgment's "On record" line that turns a [ruled class](#rulings-below-the-floor) into a note; in `/ship` every specialist and Red Team prompt it renders carries its diff base as a literal sha the parent writes in (`DIFF_BASE=`: the merge base on pass 1, `RANGE_BASE` from pass 2 on), because a reviewer is its own process and never sees the parent's shell variables; the fan-out batches above. -- `ship/sections/review-army.md` Step 9: passes, `RANGE_BASE`, classify, defer, render, the cap check before any edit, the Step 11 late-defer row, scratch files under `.gstack/tmp/`, the cap decisions; `ship/sections/adversarial.md` Step 11: the outside voice reads the same range and scopes queued fixes the same way. -- `lib/review-depth.ts`, `bin/gstack-review-plan`: the diff class, the transition table, the numeric-claim scan and each role's effort tier (`test/review-depth.test.ts`, `test/review-plan-cli.test.ts`). +- `scripts/resolvers/review-army.ts`: the floor and `NO FINDINGS` in every specialist and Red Team prompt (rendered into `review/sections/review-army.md` and `ship/sections/review-army.md`), and the lead judgment's "On record" line that turns a [ruled class](#rulings-below-the-floor) into a note; in `/ship` every specialist and Red Team prompt it renders carries its diff base as a literal sha the parent writes in (`DIFF_BASE=`: the merge base on pass 1, `RANGE_BASE` from pass 2 on) beside its plan's `DIFF_CMD` excludes, because a reviewer is its own process and never sees the parent's shell variables; the fan-out batches above. +- `ship/sections/review-army.md` Step 9: the plan's `REVIEW_DEPTH`, `GATE_SCAN` and `--depth-floor` on every run, the depth fields of the review-log row, passes, `RANGE_BASE`, classify, defer, render, the cap check before any edit, the Step 11 late-defer row, scratch files under `.gstack/tmp/`, the cap decisions; `ship/sections/adversarial.md` Step 11: the outside voice reads the same range and scopes queued fixes the same way. +- `lib/review-depth.ts`, `bin/gstack-review-plan`: the diff class, the depth (`depthFor`, `DEPTH_RULES`, `depthOfCommitInput`), each dispatch's `exclude` pathspecs and `DIFF_CMD`, the transition table, the numeric-claim scan and each role's effort tier (`test/review-depth.test.ts`, `test/review-plan-cli.test.ts`). +- `lib/review-collect.ts`: `collectCommit` (git objects only, from any checkout) and `collectLive` (the working tree), per-path lines and the base commit's registry (`test/review-collect.test.ts`). - `lib/review-scope.ts`, `bin/gstack-review-scope`: `classify`, `defer`, `render`, `summary` (with `fix_checks`, `dispatches`, `est_input_tokens`); refusals are `REVIEW_SCOPE_INPUT` and `REVIEW_SCOPE_RANGE` ([troubleshooting.md](troubleshooting.md#review-scope-input)). - `lib/ship-policy.ts`: the `review_scope` key and its `ship: review_scope …` consequence line. - `review/checklist.md`: `prereg-with-results` under Gate Integrity and `test-keyboard-count-loop` under Pass 2; `bin/gstack-coauthor-trailers` for the contributor-credit trailers of a port. diff --git a/docs/ship-budget.md b/docs/ship-budget.md new file mode 100644 index 000000000..ef7558364 --- /dev/null +++ b/docs/ship-budget.md @@ -0,0 +1,159 @@ +# /ship token budget and fresh-context handoffs + +`/ship --token-cap 25M` (or `GSTACK_SHIP_TOKEN_CAP=25M`) bounds what one /ship run spends, and +long runs hand their heavy segments to fresh-context children. The helper is +`bin/gstack-ship-budget`; the skill's procedure is `ship/sections/budget-handoff.md`. +There is no default cap: without one, /ship meters usage when it can and prints it, and +nothing else changes. + +## What the cap guarantees + +It is an **admission cap**, not a hard ceiling. Before every step and every dispatch batch, +`check` admits the work only when + + used + open reservations + unknown charges + projection + tail reserve + stop overhead <= cap + +Exactly at the cap is admitted; one token over is not. A parallel review batch is reserved as +one sum before any of it starts. Admitted work can still cost more than its projection, and +gstack cannot stop a host mid-turn from bash, so a run can finish above the cap by the +misprojection of work already admitted. The tail reserve (default 2M, `--reserve `) keeps +room for the receipt steps, and the stop overhead (calibrated) keeps room to stop cleanly. + +## Quickstart + +**Capy.** Read the root counter in one execute program that returns only that number: + +```js +return (await tools.thread.get({ thread_id: "this" })).cost.tokens; +``` + +then + +```bash +gstack-ship-budget start --record --token-cap 25M --reading +gstack-ship-budget check --run --step 6 --next 7 --reading [--prior-reading ] +``` + +The counter rolls up every subagent of the thread, outside voices included; Capy exposes no +per-subagent counter, so other work in the same thread counts too (it only stops earlier). + +**Claude Code.** `gstack-ship-budget start --record --token-cap 25M --session `. Without the +session id, `start --meter claude` prints a nonce: echo it once, then rerun with `--nonce `. +The helper reads the session journal, its subagent journals and the journals of headless +children it launched; you never pass `--reading`. + +**Anywhere else.** `--meter estimate` projects with the calibration and prints `meter=estimate`. +With a cap set and no readable meter, start refuses +([BUDGET_METER_UNAVAILABLE](troubleshooting.md#budget-meter-unavailable)). + +## The BUDGET line + + BUDGET: used= reserved= unknown= admission_cap= tail= unit= meter= epoch= call= next= projected= verdict=continue|delegate|stop + +| Field | Meaning | +|---|---| +| `used` | Metered usage since start (all epochs), or settled estimates under `meter=estimate` | +| `reserved` | Open reservations: admitted steps, started dispatches, and each open child's sub-cap counted as max(sub_cap, child_used), never both | +| `unknown` | Charges the meter cannot see (an external-CLI outside voice on Claude Code), counted at their reservation | +| `admission_cap` | The cap, or `none` | +| `tail` | Tail reserve plus stop overhead, held back from every admission | +| `unit`, `meter`, `epoch` | The meter contract: `capy-tokens` (root counter), `claude-usage-tokens` (journal usage), `estimate-tokens`; a meter change opens a new epoch | +| `call` | The per-call charge: two Capy readings in consecutive calls, or the last Claude Code call's usage | +| `next`, `projected` | What the check was for and its calibrated projection | +| `verdict` | `continue` (exit 0, prints `RESERVATION:` under a cap), `delegate` (exit 0), `stop` (exit 3) | + +Any exit other than 0 means the next step does not start. Exit 2 is a usage or validation +error on stderr with the code, the value and the repair. GSTACK_RESULT appears only on a stop, +an incomplete close and a child's return; /ship's real terminal line stays Step 22's. + +## Dispatches + +Under a cap, `gstack-review-log --start` refuses a dispatch without an unspent, one-shot +reservation ([BUDGET_CHECK_SKIPPED](troubleshooting.md#budget-check-skipped)): + +```bash +gstack-ship-budget check --run --step 9 --next dispatch:specialist,red-team --reading +gstack-review-log --start review --reservation +``` + +Roles are review-depth's: `specialist`, `red-team`, `adversarial-native`, `outside-voice`, +`fix-check`. `--finish ` settles the reservation at the dispatch's completion receipt. +`close` audits after the fact: each review-log row of the run with no reservation gets one +BUDGET_CHECK_SKIPPED line and the run ends status=incomplete for the owner to accept +(`close --approved-by --words ""`); a reservation is never created after the fact. + +## Delegation + +At start, a per-call charge of 100k or more delegates the whole /ship. Before Step 7 and before +Step 12, 150k or more (or an unknown charge) delegates the next segment (7–11.5, 12–22): + +1. `gstack-ship-budget handoff --run --from 12 --to 22 --base origin/ --reading ` writes a + brief (mode 0600, under the run directory) with the pins (HEAD, merge base, working tree, + reviewed tree), the record with its six headings and start tokens, the decisions in scope + with the owner's words, the decision trail, the budget and the return contract. It reserves + the child's sub-cap: min(cap − used − reserved − tail, the segment estimate), or `--sub-cap`. +2. The child is a Capy subagent on the shared machine, or on Claude Code + `gstack-ship-budget launch --in `: a background `claude -p` (resolved through lib/claude-bin.ts) + with explicit permission flags and the return file named. +3. The child runs `verify-handoff` first; a moved pin refuses + ([HANDOFF_PIN_MOVED](troubleshooting.md#handoff-pin-moved)). It admits against its sub-cap + with child_used = reading − reading at handoff, is the only writer of the record, and never + delegates again: a delegate rule stops it. It ends with `return` (at most 40 lines). +4. `gstack-ship-budget reconcile --run --return --reading `; idempotent per handoff hash, + so a duplicate return charges nothing twice. A refused, incomplete or interrupted child + exits 3: regenerate the handoff or stop. + +`--delegate never` turns delegate into stop for hosts without children. + +## Stop and resume + +A stop prints + + STOP: reason=budget_exhausted spent= reserved= unknown= admission_cap= next= projected= + RECOVER: /ship --resume --token-cap + GSTACK_RESULT: skill=ship status=incomplete run= + +Raising the cap is the owner's call; the resume journals who raised it and their words: + +```bash +gstack-ship-budget resume --record --token-cap --approved-by Garry --words "raise it to finish" --reading +``` + +Every command takes `--run` or `--record`; runs are never found by branch or directory, and a +/ship without `--resume` or `--continue` always starts a new run. The ledger and record are +mirrored to a private Drive checkpoint (`GSTACK_SHIP_BUDGET_CHECKPOINT_DIR`, else the +project-user Drive folder on Capy) bound to the run id and their hashes, so after a machine +change `resume --run ` restores both. A corrupt ledger +([BUDGET_LEDGER_INVALID](troubleshooting.md#budget-ledger-invalid)) is rebuilt from the +record's block with `--rebuild-from-record`; open reservations are then charged as unknown. + +## Calibration + +`lib/ship-budget-calibration.json` holds per-meter constants (per call, per dispatch, stop +overhead, calls and dispatches per step) fitted from metered runs: each constant is the +largest observation times 1.5, rounded up to 10,000 tokens. The leave-one-out test +(test/ship-budget-calibration.test.ts) covers the per-call constant only, the one observed +across three runs; per-dispatch has two observations and stop overhead one. Only the Capy +meter has observations; the Claude Code and estimate units are seeded from it until a +Claude-metered /ship completes. + +## Token cap and USD spend cap + +A lane's `--spend-cap` (USD) bounds paid gates and evals through lib/spend-ledger.ts; `--token-cap` +bounds the /ship run's model tokens through its own ledger. They are independent: set both +when a lane runs paid gates inside /ship, and neither converts into the other. + +## Claiming savings + +Savings count completed ships only. Preregister the comparison with `/eval-plan` (arms, bars, +stop rules) before claiming a saving from the cap or from delegation. + +## Result codes + +[BUDGET_CAP_REACHED](troubleshooting.md#budget-cap-reached) · +[BUDGET_READING_MISSING](troubleshooting.md#budget-reading-missing) · +[BUDGET_READING_REJECTED](troubleshooting.md#budget-reading-rejected) · +[BUDGET_METER_UNAVAILABLE](troubleshooting.md#budget-meter-unavailable) · +[BUDGET_LEDGER_INVALID](troubleshooting.md#budget-ledger-invalid) · +[BUDGET_CHECK_SKIPPED](troubleshooting.md#budget-check-skipped) · +[HANDOFF_PIN_MOVED](troubleshooting.md#handoff-pin-moved) diff --git a/docs/ship-policy.md b/docs/ship-policy.md index e2cd9f208..168ccb678 100644 --- a/docs/ship-policy.md +++ b/docs/ship-policy.md @@ -221,8 +221,11 @@ It refuses (`QUEUE_NOT_READY`) when the working tree has tracked edits, HEAD is not the PR's pushed head, CI at that exact head is not green, or the pregate result is not a current pass, and (`QUEUE_RECEIPT_MISSING`, `QUEUE_RECEIPT_STALE`) when the PR body carries no /ship receipt for that -head: /ship runs before every READY ([details](#ship-before-ready)). Send the -block as printed. +head: /ship runs before every READY ([details](#ship-before-ready)). It also +refuses `QUEUE_RECEIPT_DEPTH_RAISED` when the receipt's review depth is below +what the head needs and `QUEUE_RECEIPT_EXCEPTION_INVALID` when an owner +exception the receipt records does not stand ([the ship receipt](#ship-receipt)). +Send the block as printed. **2. Lane behind another PR: gate ahead.** Gate the tree the queue will have once the predecessor lands, while it is still open: @@ -370,12 +373,17 @@ slot. The queue enforces this at every step from the PR body alone: - `ready` refuses with `QUEUE_RECEIPT_MISSING` when the body has no valid receipt and with `QUEUE_RECEIPT_STALE` when the receipt's `head` is not the head being READY'd (or its `pr` is another PR); the informational - `SHIP_RECEIPT:` line still prints. There is no flag around it. + `SHIP_RECEIPT:` line still prints. It refuses `QUEUE_RECEIPT_DEPTH_RAISED` + (with a `REVIEW_DEPTH:` line) when the receipt records a review depth below + what the head needs, and `QUEUE_RECEIPT_EXCEPTION_INVALID` when an owner + exception it records does not stand ([the ship receipt](#ship-receipt)). + There is no flag around it. - `train build` refuses a pin whose PR has no current receipt with the same codes, naming the PR, before anything is written, pushed or dispatched, `--dry-run` included. -- `verify --train` refuses the slot with the same codes before printing - `MERGE_CONDITION`. +- `verify --train` refuses the slot with `QUEUE_RECEIPT_MISSING` or + `QUEUE_RECEIPT_STALE` before printing `MERGE_CONDITION`; it does not + recompute the review depth. **The stamp keeps the pin's receipt.** The slot's stamp commit changes only stamp files (and, from slot 2 on, merges main into the pin), so no /ship runs @@ -478,6 +486,9 @@ its record. Refusals, all before any spend: `QUEUE_TRAIN_UNTRUSTED` (a fork head), `QUEUE_TRAIN_MOVED` (a head moved from its pin), `QUEUE_RECEIPT_MISSING` and `QUEUE_RECEIPT_STALE` (the PR body has no /ship receipt for the pin; see [/ship before READY](#ship-before-ready)), +`QUEUE_RECEIPT_DEPTH_RAISED` and `QUEUE_RECEIPT_EXCEPTION_INVALID` (the +receipt's review depth is below what the pin needs, or an owner exception it +records does not stand; see [the ship receipt](#ship-receipt)), `QUEUE_NOT_READY` (no READY receipt at that head), `QUEUE_TRAIN_CONFLICT` (the printed `QUEUE_TRAIN_CONFLICT: train stopped at # (conflicts: ) after merging #,#; nothing dispatched, no branch pushed; fix: …` line names @@ -777,7 +788,9 @@ written by the pr-body section of `/ship` after the body is composed. The ```` ```gstack-ship-receipt ```` block is the handoff record: identifiers first (`pr`, `head`, `version`, `base`), then the evidence (`gate`, `ci`, -`pregate`, `issues`, `approval`, `docs`, `review_loop`, `carry`), validated +`head_tree`, `product_patch_id`, `gstack_version`, `review_depth`, `pregate`, +`issues`, `approval`, `docs`, `review_loop`, `review_loop_exception`, `carry`), +validated against the `ship-receipt` schema (`gstack-artifact schema ship-receipt`) and read back by `gstack-ship-receipt read`, `result`, `carry` and the queue. @@ -812,6 +825,46 @@ unreadable base policy is `POLICY_SOURCE_UNAVAILABLE`); one (`absent/ over` for a path the tree lacks), exit 1 on any `over`, whose repair is trimming the file, never raising the cap in the same PR. +**`review_depth` and `gstack_version`.** `write` records the gstack that +wrote the receipt and the review depth at the checked-out head +([review-policy.md#review-depth](review-policy.md#review-depth)): +`{ depth, class, runtime_lines, rules, base, registry, gate_scan: { tagged, head }, reasons }`, +computed from git objects for the range against `origin/` +(`gstack-diff-scope --head ` for the scope signals), with the gate +scan run on that head. `--head` must be the checked-out HEAD +(`RECEIPT_INVALID` otherwise), so the record and `head_tree` describe the +tree the review read; tracked edits in the checkout make the scan unavailable, +which records `full`. `gstack-ship-queue ready` and `train build` recompute +the depth the head needs from the same range and scope and print `REVIEW_DEPTH: receipt= required= +runtime_lines= class= reasons=<…> inputs=base@,registry@,gate_scan@`; +a recorded gate scan counts only when its `head` is the full bound commit, +otherwise the scan is unavailable and the head needs `full`. A receipt below the required +depth, or one whose writer records `gstack_version` but no `review_depth`, is +[`QUEUE_RECEIPT_DEPTH_RAISED`](troubleshooting.md#queue-receipt-depth-raised): +the receipt is left unchanged and the fix is /ship on that head. A receipt with +neither field predates depth receipts and is accepted as legacy. A carry +recomputes the depth at the new head, rebinds the gate scan, and refuses when +the new head needs a deeper review than the receipt records (a test change that +skips a test raises the diff to gate class), when `--head` is not the +checked-out HEAD, when the receipt records `gstack_version` without +`review_depth`, or when an owner exception no longer stands, each as +[`RECEIPT_CARRY_REFUSED`](troubleshooting.md#receipt-carry-refused). + +**`review_loop_exception`.** The owner's acceptance of a stop after a +fix-check edit under frozen scope (#3559), from `write --review-loop-exception +`: `{ accepted_by, date, via, reason, fix_check: { head, findings[, files] } }`. +It needs `--review-loop` with `fix_checks` of 1 or more, a `fix_check.head` +that is the receipt head or its ancestor, and, with `--body`, the line +`Review-loop exception: accepted by via : (fix-check at , findings)` +word for word; otherwise +[`REVIEW_LOOP_EXCEPTION_INVALID`](troubleshooting.md#review-loop-exception-invalid) +and nothing is written. The queue checks both owner exceptions the same way +before READY and train build: the record must parse, the body must still +carry its line, and the fix-check head must be the bound head or its ancestor +(after a carry across rewritten history the old fix-check commit is off the +branch, so that check is skipped), or the receipt is +[`QUEUE_RECEIPT_EXCEPTION_INVALID`](troubleshooting.md#queue-receipt-exception-invalid). + **Prose against the receipt.** `gstack-ship-receipt read --pr --check-prose` (or `--body `) compares every counter the body quotes with the receipt's integers under `review_loop`, `gate` and `ci`: `passes=2`, `passes: 2` and @@ -891,6 +944,32 @@ line, and the codes a refusal ends with are ## Carrying a receipt across a base merge or a test-only fix +**Merge main into a reviewed branch; never rebase it.** What happens to the +receipt when the base moves: + +| What changed since /ship | The receipt | +|---|---| +| a merge of the base, product diff unchanged (tests, release metadata, registered outputs the pregate's regen check proved) | carries; no review reruns | +| a merge of the base whose resolution changed product code | a fresh /ship (`RECEIPT_CARRY_PRODUCT_CHANGED`) | +| a rebase or force-push onto a tree the receipt covers, product diff against the new base unchanged | carries (`carry.ancestry: rewritten`) | +| any other rebase or force-push | a fresh /ship (`RECEIPT_CARRY_TREE_MISMATCH`) | +| a stacked PR whose parent landed (squash or merge), retargeted to the base with the base merged in, HEAD's product diff exactly the one reviewed against the parent branch | carries (reason `stack parent landed`) | + +**Stacked PRs (#3570).** A child PR's receipt is written against its parent +branch, so its `base` names that branch and its `product_patch_id` is the +child's own range. After the parent lands, the PR is retargeted to the base, and +/ship's carry check runs with `--base `. When that base differs from the +receipt's, the carry compares the reviewed range (the recorded +`product_patch_id`, or for an older receipt the range against +`origin/` while that branch still resolves) with HEAD's whole product +diff against the base, computed the way `write` records it, so a parent's +release-metadata change that never reached the base counts too. Equal means +the parent fully landed and the child is unchanged, so the receipt carries +and from then on names the base it was carried to. A parent that has not landed, a child edited +since, or a parent that landed with changes the child never merged all leave a +different diff and refuse with `RECEIPT_CARRY_PRODUCT_CHANGED`. An older +receipt whose parent branch is gone refuses with `RECEIPT_CARRY_REFUSED`. + Since the release that added `review_scope`. A `/ship` receipt names the head it reviewed, so a conflict-only merge of the base or a test-only fix used to invalidate it and cost a full re-run on identical product code. @@ -921,11 +1000,22 @@ newer tentative one the stamp moved (a `*_KEY_VERSION` written as the next minor, #3512; a version older than the old one or of another width is a hand edit). A logic change in a stamped source file is product. Lockfiles are product unless the policy names -them. A base merge contributes no product -change of its own. A receipt carried twice keeps the reviewed head as +them. An output of an entry with a `command` in origin/'s +`.gstack/generated.json` is `generated`, not product, only when the +`--pregate` result passed for HEAD lists it under the `regen` check's +`proven` paths (the check deleted the touched output in its scratch worktree +and the command recreated it byte-identically) and that check ran the same +registry, origin/ at the commit the carry reads. A file that matches an +output glob but that the command never writes is not proven. Without that +evidence, or for an entry with no command or one only the branch registers, +the output is product (U1 on gstack-evals paid a +full rerun because a merge changed its generated index's diff). A base merge +contributes no product change of its own. A receipt carried twice keeps the reviewed head as `carry.from` and adds up the merges and paths. The carried receipt records `carry: { from, reason, product_patch_id, changed_paths, merge_commits, -range_diff, covers, reruns }` with the `git range-diff` evidence, prints +range_diff, covers, reruns, ancestry, trees }` (`ancestry` is `linear` +along the receipt's own history, `rewritten` once any hop was a rebase; +`trees` lists the earlier covered trees) with the `git range-diff` evidence, prints `CARRY: carried from to ()` and the `GSTACK_RESULT: skill=ship status=complete` line, and its summary line ends with `carried_from=`. `CARRY: current` means the receipt already names HEAD; @@ -933,10 +1023,25 @@ skill=ship status=complete` line, and its summary line ends with A changed product path, or a product patch-id that differs, is [`RECEIPT_CARRY_PRODUCT_CHANGED`](troubleshooting.md#receipt-carry-product-changed) -(exit 3; the refusal names the paths), and a receipt whose head is not in HEAD's -history (a rebase or force-push) or a working tree with uncommitted changes is -[`RECEIPT_CARRY_REFUSED`](troubleshooting.md#receipt-carry-refused): run `/ship` -on the new head. The queue's `ready`, `train build` and `verify --train` read the +(exit 3; the refusal names the paths), and a working tree with uncommitted +changes is [`RECEIPT_CARRY_REFUSED`](troubleshooting.md#receipt-carry-refused). + +**Rewritten history.** `write` records `head_tree` (the reviewed head's tree) +and `product_patch_id` (its product patch against the base), and every carry +rebinds both to the new head and keeps the earlier trees in `carry.trees`. +When the receipt's head is no longer in HEAD's history, the carry follows only +when HEAD's tree is one of those trees and HEAD's product patch-id against the +current base equals the recorded one; it records `carry.ancestry: rewritten` +and `range_diff: tree-equal`, and needs neither the old commit nor its +history, so a fresh clone carries too. The tree alone is not enough: a stacked +branch rebased onto main after its base closed unmerged keeps its tree while +its diff grows by the base's code, and that is `RECEIPT_CARRY_PRODUCT_CHANGED`. +Any other tree is +[`RECEIPT_CARRY_TREE_MISMATCH`](troubleshooting.md#receipt-carry-tree-mismatch), +which names HEAD's tree and the covered trees. A receipt from before +`head_tree` existed, whose head is not in this clone, is +`RECEIPT_CARRY_REFUSED`: run `/ship` on the new head. A refusal never +rewrites the body. The queue's `ready`, `train build` and `verify --train` read the carried receipt like any other. **Delta /ship: eligibility, then checks, then publication.** `/ship` Step 1 runs @@ -995,7 +1100,7 @@ or the order moved, the result is `QUEUE_STALE` (exit 3) with the exact Stages, each journaled in `.gstack/tmp/restamp-journal.json`: 0. **restamp_command** (only when the policy sets it): the repo's own restamp, see [restamp_command](#restamp-command). -1. **version**: `gstack-version-bump write --version ` in the staging worktree (VERSION, the manifest, npm lockfiles); skipped when `restamp_command` owns the version. +1. **version**: `gstack-version-bump write --version ` in the staging worktree (VERSION, the manifest, npm lockfiles); skipped when `restamp_command` owns the version. The manifest gets the npm-valid three-part form, except when the policy lists it in `stamp_paths` or `stamp_files` and its copy at the base holds four parts (gbrain's convention): then it keeps the full version (`--manifest-form full`) and the stage detail says so. 2. **release_tool**: the policy command, under the contract below. 3. **changelog**: the PR's `[Unreleased]` or old-version section moves to the top under ``, above its predecessor's entry. A duplicate heading the PR introduces (`CHANGELOG_DUPLICATE_HEADING`: the headings are counted against the base's CHANGELOG at `origin/` and at the fork point, so a version the base already heads twice passes as long as the PR adds no further copy) and a top entry that is not `` (`CHANGELOG_TOP_MISMATCH`) are errors; the section being re-headed itself may exist only once. 4. **stamp_paths**: exact `(was X)`, `since: X` and `vX` rewrites, plus every `stamp_patterns` template, within `stamp_paths` and `stamp_files`. A quote around X in the first two forms is part of the form and is kept as written: `since: 'X'`, `since: "X"`, `(was 'X')` and `(was "X")` move like the bare ones (the shape of a quoted source row such as gbrain's `{ since: '0.60.468.0', … }`), an opened quote must close right after X (`since: '1.2.3-beta'` and `since: '1.2.3"` are not the form, in the writer and in the tree receipt alike), and `vX` already accepts a quote before the `v`. Which X moves is decided by provenance. The branch's own tentative stamp (its VERSION when it moved past base) and `--was `, when given, are each rewritten on every line of every stamp file. Beyond that, only lines the branch itself added are read, by their position in the file (`git diff --unified=0` from the fork point), so a base line with the same text, or a CRLF checkout whose diff is LF-normalized, is told apart: a stamp-form mention there of a version newer than the version at the branch's fork point is a tentative stamp and moves (this is what finds a quoted row after a lost slot and a merge of the base, since the base's release is newer than the fork point), and when the branch has no stamp of its own because its VERSION equals the base's and its fork point is the base itself (a branch rebased onto the base after it reached X, or one never stamped) a mention of the base version on a line it added is its stale stamp and moves too, while the same version on a line the base already carries is the base's release and stays. The stage detail names both counts per file (`VERSION equals base X, so X moved only on lines this branch added and stayed on the base's own lines (: N moved, M kept)`), so the stamp commit shows which lines moved and why. A line the base added since the fork point is the base's even when that diff shows it (a merge of the base on the branch, committed or still staged, brings every line the base added since the fork into the diff from the fork point, main's own release keys included): it is left out, the detail says `N line(s) the base added since the fork point are the base's, not this branch's, and stay (: N)`, and a base diff git cannot run refuses the stage (`POLICY_SOURCE_UNAVAILABLE`, `cannot diff .. for the stamp_paths stage`) rather than reading as an empty set that would move the base's lines again. The rule reads line ownership, not meaning: a branch-added line inside `stamp_paths` that means the base's own release in a stamp form (`Requires vX or later` written on a branch forked at X) moves with it, which the `--dry-run` diff and the per-file counts show before anything is written; write such a reference outside a stamp form, or keep that file out of `stamp_paths`. `--was X` is the opposite tool: it rewrites X everywhere, the base's own lines included, and re-heads the CHANGELOG section `## [X]`. Only the repo's own version width counts, so a 3-digit dependency pin in a 4-digit repo is never a candidate. diff --git a/docs/skills.md b/docs/skills.md index fc75dbf44..348777519 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -31,7 +31,7 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples. | [`/document-generate`](#document-generate) | **Technical Writer** | Generate Diataxis docs (tutorial / how-to / reference / explanation) for a feature from code. | | [`/retro`](#retro) | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. | | [`/browse`](#browse) | **QA Engineer** | Give the agent eyes. Drives your Aside browser first — real sessions, real clicks, real screenshots — through deterministic `aside repl` scripts, and falls back to gstack's own Chromium (~100ms per command) when Aside isn't there. | -| [`/setup-browser-cookies`](#setup-browser-cookies) | **Session Manager** | Copy selected cookies from Chrome, Chromium, Brave, Edge, Windows-only Opera and Opera GX, or macOS-only Comet, Arc, and Dia into the fallback browser. Choose your profile and domains; check sign-in separately. Unnecessary on Aside, which already has your sessions. | +| [`/setup-browser-cookies`](#setup-browser-cookies) | **Session Manager** | Copy selected cookies from Chrome, Chromium, Brave, Edge, Windows-only Opera and Opera GX, or macOS-only Comet and Arc into the fallback browser. Choose your profile and domains; check sign-in separately. Unnecessary on Aside, which already has your sessions. | | [`/autoplan`](#autoplan) | **Review Pipeline** | One command, fully reviewed plan. Runs CEO → design → DX → eng review automatically (eng always last, so the shipping gate reviews the final amended plan) with encoded decision principles. Surfaces only taste decisions for your approval. | | [`/plan-devex-review`](#plan-devex-review) | **DX Reviewer** | Plan-stage DX review. TTHW (time-to-hello-world), magical moments, friction points, persona traces, and error messages scored for the agents that read them ([agent-ready errors](agent-ready-errors.md)). Three modes: Expansion, Polish, Triage. | | [`/devex-review`](#devex-review) | **DX Reviewer (live)** | Live developer experience audit. Walks the actual onboarding flow, measures TTHW, catches the docs lies, and triggers CLI errors the way an agent meets them (no terminal, contained, redacted) through `gstack-error-capture`. | @@ -1181,7 +1181,7 @@ This is my **session manager mode** — for the fallback browser. With Aside ope For authenticated testing on gstack's own browser, `/setup-browser-cookies` copies selected cookies from your daily browser. Sites may also need storage or a fresh login, so copying cookies is not proof that the session works. -The picker detects Chrome, Chromium, Brave, Edge, Windows-only Opera and Opera GX, and macOS-only Comet, Arc, and Dia. Choose the browser, account/profile, and domains. Profile labels use the current `Local State` name with a directory discriminator, so renamed profiles and duplicate names are distinguishable. No cookie values are displayed; source/profile labels are still sensitive. +The picker detects Chrome, Chromium, Brave, Edge, Windows-only Opera and Opera GX, and macOS-only Comet and Arc. Choose the browser, account/profile, and domains. Profile labels use the current `Local State` name with a directory discriminator, so renamed profiles and duplicate names are distinguishable. No cookie values are displayed; source/profile labels are still sensitive. ``` You: /setup-browser-cookies diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 1ffa23542..b06d26507 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1566,11 +1566,19 @@ process has exited never blocks, and neither does a stale one: each lease records its process's start identity, so a pid reused after a reboot or a machine wake (GBRA-105's lease named pid 379, which had become dbus-daemon) is reclaimed instead of blocking. The upgrader's own session (the pid chain it -runs under) never counts. +runs under) never counts for `bin/gstack-upgrade` run by hand. A Capy install +in install mode (`bin/gstack-capy-session`) counts it while that lease is under +120 minutes old: an install run from inside a workflow that holds the lease +(/ship's docs step, #3571) prints `SELF_UPGRADE: skipped (a gstack run in this +session holds a workflow lease on this installation: pid

(m +), so the upgrade waits until the lease is 120 minutes old; fix: +/bin/gstack-upgrade once the run ends (UPGRADE_BUSY))` and leaves the +checkout where the run started. Each `gstack-skill-start` renews the lease. **Fix.** Wait for those sessions to finish (`bin/gstack-lease list` shows every lease with its age and `alive|dead|stale`; a holder is named as -`pid

(m )`), then re-run `bin/gstack-upgrade`. +`pid

(m )`), then re-run `bin/gstack-upgrade`. For the +session's own run, run the printed `bin/gstack-upgrade` after the run ends. When you know they are idle, `GSTACK_UPGRADE_FORCE=1 bin/gstack-upgrade` proceeds. At a Capy session start the same refusal appears as `SELF_UPGRADE: skipped (live gstack sessions hold this installation: ...)`, @@ -1729,8 +1737,11 @@ restate them. Rotate the secret if it was real. **Meaning.** The record is kept per branch (one Capy thread ships one branch), and HEAD is detached or the working directory is not a git repository. Exit 3. +From `import --autoplan

--stack ` it means a listed branch exists +neither locally nor on origin; the line names it, and no branch's record was written. -**Fix.** Check out the branch the work ships from, or pass `--branch `. +**Fix.** Check out the branch the work ships from, or pass `--branch `. For +`--stack`, correct or fetch the named branch and import again. ### `gstack-approvals: ... (APPROVAL_RECORD_UNAVAILABLE)` @@ -1769,7 +1780,9 @@ import again. Imports are idempotent, so a retry never records an answer twice. ### `gstack-owner-brief render --captain: ... (CAPTAIN_BRIEF_INCOMPLETE)` **Meaning.** The plan is missing at least one section the brief needs: `## Before → after`, -`## Why it matters`, `## What caused this work`, `## Big decisions`. The brief still prints, +`## Why it matters`, `## What caused this work`, `## Big decisions`, and `## ELI5` (alias +`## In plain words`) on a run whose `gate.json` carries an `eli5` field (gstack 1.91.305 and +later; older runs render as before). The brief still prints, but it opens with "Not ready for approval" and has no reply invitation. Exit 1. **Fix.** Add the named sections to the plan (`gstack-autoplan revise --plan ` if @@ -1810,6 +1823,92 @@ all the command prints `SHOT_PNG: unavailable (...)` and exits 0 instead. **Fix.** Screenshot `shot.html` with your own browser at 880 px wide, or use `text.md`. +## /ship token budget and fresh-context handoffs (gstack-ship-budget) + +The flow, the BUDGET line field by field and the meters are in [ship-budget.md](ship-budget.md). +Exit 2 lines go to stderr; exit 3 lines (a stop) go to stdout with the STOP, RECOVER and +GSTACK_RESULT lines. + + +### `gstack-ship-budget: ... (BUDGET_CAP_REACHED)` + +**Meaning.** The next step or dispatch batch would push used + open reservations + unknown +charges + its projection + the tail and stop reserve past the admission cap, so it did not +start. Exit 3. `gstack-review-log --start` prints the same code (exit 1) for a dispatch +after the run stopped. The cap admits work; it cannot stop a turn already running, so the +overshoot is bounded by the misprojection of work admitted before the stop. + +**Fix.** The run ended status=incomplete with a resumable record. Raising the cap is the +owner's call: run the printed `RECOVER:` line; its resume needs +`--approved-by --words ""`. + + +### `gstack-ship-budget: ... (BUDGET_READING_MISSING)` + +**Meaning.** The run's meter is the Capy root counter, a cap is set, and the command got no +`--reading`. Exit 2. No gstack binary can call Capy's API, so the agent reads it. + +**Fix.** In one execute program return only +`(await tools.thread.get({ thread_id: "this" })).cost.tokens` and pass it as `--reading `. + + +### `gstack-ship-budget: ... (BUDGET_READING_REJECTED)` + +**Meaning.** The reading breaks the run's meter contract: it is lower than the last reading +of the same epoch, `--prior-reading` is above `--reading`, or `--reading` went to a meter that +reads its own source (Claude Code journals, the estimate). Exit 2; nothing changed. + +**Fix.** Pass the counter the run started with (the BUDGET line names meter, unit and epoch). +A different meter opens a new epoch that keeps prior usage: +`gstack-ship-budget resume --run --meter `. + + +### `gstack-ship-budget: ... (BUDGET_METER_UNAVAILABLE)` + +**Meaning.** A cap is set and no meter is readable: no `--reading`, no bound Claude Code +session, no `--meter estimate`; or a `--session`/`--nonce` matched zero or several journals. +The line names what it tried. Exit 2. + +**Fix.** Capy: `--reading `. Claude Code: `--session `, or echo the nonce the line prints +once and rerun with `--nonce `. Elsewhere, with the owner's consent, `--meter estimate`. + + +### `gstack-ship-budget: ... (BUDGET_LEDGER_INVALID)` + +**Meaning.** The ledger (`/ship-runs//budget.json`), the record's +gstack-budget block, a handoff brief's block or a checkpoint is missing, unparseable, from +another schema version, or not bound to the run (identity or sha256 mismatch). The line names +the path, the schema version and the parse location. Exit 2. + +**Fix.** After a machine change, `gstack-ship-budget resume --run ` restores the ledger and +record from the Drive checkpoint. Otherwise rebuild: +`resume --record --rebuild-from-record --reading `; open reservations are charged as unknown. + + +### `gstack-review-log: ... (BUDGET_CHECK_SKIPPED)` / `gstack-ship-budget: ... role= step= started= spend=unknown (BUDGET_CHECK_SKIPPED)` + +**Meaning.** Under a cap, `gstack-review-log --start` got no reservation id, an id from another run +or a step reservation (mismatched), or an id already used (one-shot); it refused before the +dispatch (exit 1, nothing captured). From `close`: a review-log row of this run had no +reservation before it started; one line per dispatch, and the run ends status=incomplete (exit 3). + +**Fix.** Run `gstack-ship-budget check --run --step --next dispatch:` before the +batch and pass the printed id once with `--reservation`. A reservation is never created after the +fact: the owner accepts the unreserved spend with `close --approved-by --words ""` +or the dispatches rerun under reservations. + + +### `gstack-ship-budget: ... (HANDOFF_PIN_MOVED)` + +**Meaning.** `verify-handoff` found the brief no longer matches its tree: HEAD, the merge base +with the base ref, the working-tree fingerprint (`gstack-wtree`) or the reviewed tree moved, or the +brief's sha256 is not the one the parent recorded. Each line names the pin with its expected +and actual value. Main moving alone keeps the merge base and never refuses. Exit 3; the child +wrote its return with status=refused. + +**Fix.** The parent reconciles the refusal and regenerates the handoff at the current tree +(`gstack-ship-budget handoff ...`) or stops. + ## Browser @@ -2388,6 +2487,14 @@ and an E.164 `+14155551234` still report, so the finding means the id stands without a run word (`the id is 40269992077`, `40269992077 failed`) or follows a word that is not one (`see 40323989742`). +Separately, the scanner skips a bare number that is exactly a power of two +from 2^30 through 2^49, one less than such a power, or one of eleven 32-bit +hash and PRNG constants (Knuth's multiplicative hash, the golden-ratio +constant, the glibc and Numerical Recipes LCGs, FNV-1a, MurmurHash2 and 3, the +MT19937 seeder and the largest 32-bit prime; `isNumericConstant` in +`lib/redact-patterns.ts`). Only the exact digits with no separator are exempt: +the same digits with a `+`, spaces, dashes, dots or parentheses still report. + **Fix.** Write the id next to a run word (`run 40269992077`) or as an `/actions/runs/` link. For anything else, rerun with `--confirm ` using the `TOKEN:` line the refusal printed; MEDIUM findings do not block @@ -2428,6 +2535,15 @@ An address only another remote knows still reports. If the hook also printed `existing-email suppression was limited for this push`, it could not read the history in 5 seconds, so known authors may be listed too. +A filename with an `@` in the package@version style is not an address and +never reports: the part after the `@` is a version or tag (one dotless label +or a dotted version, never a domain name) followed by file extensions no +top-level domain uses, or a dotted all-digit version followed by +an extension that doubles as a top-level domain (`looksLikeAtFilename` in +`lib/redact-patterns.ts`). A file named after a real address, an address at an +all-digit domain and an address whose top-level domain doubles as a file +extension still report. + **Fix.** Remove the address, or allow it for this repo: `git config --add gstack.redact.allowEmail
`. If it is your own address, check `git config user.email`. The allowlist only covers `pii.email`; @@ -2900,10 +3016,12 @@ for an older PR, write it once by hand with the same command. ### `RECEIPT_INVALID` **Meaning.** The block exists but does not validate against the `ship-receipt` -schema (`gstack-artifact schema ship-receipt`). +schema (`gstack-artifact schema ship-receipt`). `gstack-ship-receipt write` +also refuses with this code, and writes nothing, when `--head` is not the +checked-out HEAD: the receipt binds the tree the review read. **Fix.** Regenerate it with `gstack-ship-receipt write`; never hand-edit the -block. +block. For the `--head` refusal, check out that commit and write there. ### `EXECUTION_UNKNOWN` @@ -3150,7 +3268,10 @@ cannot be downgraded; every other check id in `warn` is honoured only from the base branch's copy or the user-owned file. For the user-owned file, edit it directly at the path the message names. A user file inside the repository, or reached through a symlink into it, is ignored rather than read (`--explain` -names it). +names it). An unknown `sealed` key that a newer gstack defines (such as +`allow_paths` or `case_insensitive`) means this machine's gstack is older than +the policy: upgrade gstack here, and raise `min_gstack_version` in the +repository's `.gstack/ship-policy.json` before landing such a key. ### `PREGATE_SECRETS` @@ -3656,7 +3777,11 @@ finding: rule, `file[:line]`, commit. They never print the matched text. **Fix.** Remove the output from every published commit before the branch reaches the public repository (a later commit that deletes it still publishes -it). A reviewed false positive gets one line in the base branch's +it). A publishable file kept next to sealed data (a `MANIFEST.json` of hashes +and counts) can be exempted from the path rules with a `sealed.allow_paths` +glob in the base branch's `.gstack/pregate.json`; the text rules still read it +([docs/pregate.md#sealed](pregate.md#sealed)). A reviewed false positive gets +one line in the base branch's `.gstack/sealed-allow.tsv`: `rulepathshareason`. A private destination sets `"visibility": "private"` under `sealed` in the base branch's `.gstack/pregate.json`. Capy's pull-request tool may not run local hooks, so @@ -4434,6 +4559,39 @@ written for the pinned head is the binding one and `verify --train` accepts it. `gstack-ship-queue ready --pr --screen|--no-screen`. A lane never stamps to fix this: the stamp comes only when the slot is called. + +### `QUEUE_RECEIPT_DEPTH_RAISED` + +**Meaning.** `ready` or `train build` recomputed the review depth the head +needs from git (the range against the base ref, `origin/` in `ready` +and `/` in `train build`, the base commit's +generated-output registry, and the receipt's gate scan when it names this +head) and the receipt's `review_depth.depth` is below it, or the receipt comes +from a gstack that records `gstack_version` but carries no `review_depth`. The +`REVIEW_DEPTH:` line prints the receipt's depth, the required depth, runtime +lines, the class, the reasons and the inputs (`base@`, `registry@`, +`gate_scan@` or `missing`). A gate scan recorded for another head counts as +missing, which makes the head need `full`. The receipt is unchanged. + +**Fix.** Run /ship on the head the READY names; it reviews at the depth +`gstack-review-plan` plans for that head and writes a receipt that records it. +Never edit `review_depth` by hand ([review-policy.md](review-policy.md#review-depth)). + + +### `QUEUE_RECEIPT_EXCEPTION_INVALID` + +**Meaning.** The receipt records an owner exception (`docs.exception` or +`review_loop_exception`) that the queue cannot accept: the record does not +parse, a review-loop exception names no fix-check (`review_loop.fix_checks` +is 0 or missing), its `fix_check.head` is neither the bound head nor an +ancestor of it (not checked after a carry across rewritten history), or the PR +body no longer carries the exception's line word for word +(`Documentation exception: …` or `Review-loop exception: …`). + +**Fix.** Restore the line in the PR body exactly as `write` printed it, or run +/ship again and record the owner's acceptance with `--docs` or +`--review-loop-exception` ([ship-policy.md](ship-policy.md#ship-receipt)). + ### `QUEUE_SCREEN_STALE_REF` @@ -4694,29 +4852,78 @@ rebased; /ship's own rule is to merge the base in, never rebase a reviewed head. ### `RECEIPT_CARRY_REFUSED` **Meaning.** `gstack-ship-receipt carry` could not carry the PR's /ship receipt -to HEAD: the PR body has no valid receipt, the receipt's head is not an ancestor -of HEAD (a rebase or force-push dropped it), the working tree has uncommitted -or untracked changes (a carry certifies a commit, never a tree that differs from -it), or git could not compare the two product diffs or read the working tree's -status. The receipt in the body is unchanged and still names the old head, so -`gstack-ship-queue ready` refuses `QUEUE_RECEIPT_STALE`. +to HEAD: the PR body has no valid receipt, the working tree has uncommitted or +untracked changes (a carry certifies a commit, never a tree that differs from +it), the receipt's head left HEAD's history and the receipt records no tree to +compare (a receipt written before `head_tree`, whose head is not in this +clone), the PR was retargeted to the base after its stack parent landed but +the receipt records no `product_patch_id` and `origin/` no longer +resolves, so the reviewed range cannot be recomputed, or git could not +compare the two product diffs or read the working tree's status. It also refuses when an owner exception the receipt records +no longer stands, and, for a receipt from a gstack that records review +depth, when HEAD needs a deeper review than the receipt records, `--head` is +not the checked-out HEAD, or the receipt records `gstack_version` without +`review_depth` ([ship-policy.md](ship-policy.md#ship-receipt)). The receipt in +the body is unchanged and still names the old head, so `gstack-ship-queue +ready` refuses `QUEUE_RECEIPT_STALE`. -**Fix.** Keep the reviewed head in HEAD's history (merge the base in instead of -rebasing), commit or stash every working-tree change, then rerun +**Fix.** Commit or stash every working-tree change, then rerun `gstack-ship-receipt carry --pr ` at the new head. When the history is -already rewritten, run /ship on the new head. +already rewritten and the receipt predates `head_tree`, run /ship on the new +head; next time merge the base in instead of rebasing. For a retargeted stacked +PR whose older receipt lost its parent branch, or a depth or exception +refusal, run /ship on the new head. When `--head` is not the checked-out HEAD, +check it out and carry there. + + +### `REVIEW_LOOP_EXCEPTION_INVALID` + +**Meaning.** `gstack-ship-receipt write --review-loop-exception` refused the +record and wrote nothing: it is not `{ accepted_by, date, via, reason, +fix_check: { head, findings[, files] } }`, `--review-loop` is missing or counts +no fix-check, `fix_check.head` is neither the receipt head nor its ancestor, +or the `--body` file lacks the `Review-loop exception: …` line. + +**Fix.** Record the owner's exact words and the fix-check the stop followed, +pass the `gstack-review-scope summary` file as `--review-loop`, put the printed +line in the PR body, and write again +([ship-policy.md](ship-policy.md#ship-receipt)). + + +### `RECEIPT_CARRY_TREE_MISMATCH` + +**Meaning.** The branch was rebased or force-pushed after /ship, so the +receipt's head is no longer in HEAD's history, and HEAD's tree is not a tree +the receipt covers (its `head_tree` or a tree in `carry.trees`). No review saw +this code. The refusal names HEAD's tree and the covered trees; the body is +unchanged. + +**Fix.** Run /ship on the new head. A rebase carries only onto a reviewed tree +whose product diff against the new base is unchanged; merging the base in +instead keeps every later carry available +([ship-policy.md](ship-policy.md#receipt-carry)). ### `RECEIPT_CARRY_PRODUCT_CHANGED` **Meaning.** Between the receipt's head and HEAD the product diff against the -base changed: at least one path that is neither a test, release metadata nor -part of the base merge has a different patch than the reviewed head had. The -reviewed verdict does not cover HEAD, so the receipt is not carried. The -refusal names the changed product paths. +base changed: at least one path that is neither a test, release metadata, a +registered output the pregate's regen check proved (listed under `proven`, +checked against the same base registry), nor part of the base merge has +a different patch than the reviewed head had. After a rebase it means HEAD has +the reviewed tree but the base moved under it, so the diff a reviewer would see +is not the reviewed one. For a stacked PR retargeted to the base after its +parent landed, it means HEAD's product diff against the base is not the range +reviewed against the parent branch: the parent has not fully landed, or the +branch changed since. The reviewed verdict does not cover HEAD, so the +receipt is not carried. The refusal names the changed product paths, or for a +retargeted stacked PR the parent branch and the base. **Fix.** Run /ship on the new head. The receipt carries only across a -conflict-only base merge, a test-only change or release metadata, which the +conflict-only base merge, a test-only change, release metadata, a registered +output the pregate's regen check proved, a rebase onto a covered tree with +the recorded product diff, or a stacked PR's retarget once its parent fully +landed on the base, which the `carry` object in the carried receipt records with the product patch-id and the range-diff evidence ([unattended.md](unattended.md#the-terminal-line)). @@ -5097,7 +5304,7 @@ The name is not one of openclaw, hermes, dots, generic, qm, muse or grok. For a ### `gstack-harness: Hermes does not support --skills router` (HARNESS_MODE_UNSUPPORTED) -Hermes opens only skills it has indexed, so a router that points at unlisted files would not load. Drop `--skills` to take the harness's default (Hermes: all; OpenClaw, dots and generic: router). +Hermes lists in its skills index only the skills registered as folders in its skills tree, so a router would leave every other gstack skill out of the listing the model chooses from (Hermes's `skill_view` can still load an unlisted skill by name, but nothing tells the model it exists). Drop `--skills` to take the harness's default (Hermes: all; OpenClaw: hybrid; dots and generic: router). OpenClaw takes router, hybrid or all. ### `gstack-harness: refusing to write into : ` (HARNESS_UNSAFE_DESTINATION) @@ -5109,7 +5316,12 @@ The destination is your home folder, the filesystem root, inside the gstack chec gstack only replaces files its ledger says it wrote. A folder or a skill with the same name is yours (or another tool's), and harnesses resolve skills by name, so gstack stops instead of shadowing it. Rename or move that entry, then register again. -The same code stops `register generic --context ` when the file holds a `` or `` line without exactly one partner, or a gstack block someone edited. Delete those marker lines (and the lines between them, once you have kept what you want), then register again. +The same code stops `register --context ` when the file holds a `` or `` line without exactly one partner, or a gstack block someone edited. Delete those marker lines (and the lines between them, once you have kept what you want), then register again. + + +### `gstack-harness: refusing to write the gstack block into : ` (HARNESS_CONTEXT_REFUSED) + +`--context` writes the routing block only into a file you name, and two kinds of file are refused before anything is written. `SOUL.md` (in any letter case) is the harness's identity file (Hermes and OpenClaw both load it every session), and gstack never edits it. For Hermes, a new `.hermes.md`, `HERMES.md`, `AGENTS.override.md`, `AGENTS.md` or `CLAUDE.md` that would outrank a rules file Hermes loads now is refused too: Hermes loads one project context type, first match wins (`.hermes.md`/`HERMES.md`, then the `AGENTS.md` chain, then `CLAUDE.md`, then `.cursorrules`), takes the first name it finds in a folder (`.hermes.md` before `HERMES.md`, `AGENTS.override.md` before `AGENTS.md`), and takes the nearest `.hermes.md`/`HERMES.md` walking up to the git root, so creating it would hide those rules. Name the file Hermes already loads instead (the error names it), or a file in `$HERMES_HOME` for every session. ### `gstack-harness: could not render skills: ...` (HARNESS_RENDER_FAILED) @@ -5141,3 +5353,47 @@ QM's admin API refused or did not answer. gstack lists packs before it creates o QM registration does not work yet. QM's skill-pack import clones the whole repository and reads every file before it picks the skills, and by default it refuses a pack over 32 MiB or 5,000 files. The gstack repository is larger (about 73 MiB in 4,300 files), so gstack checks the size first and sends nothing. When QM itself refuses (a QM with other limits), the pack it created stays in the org without skills: `gstack-harness unregister qm --remote` archives it. Meanwhile, give a QM agent gstack by pasting the output of `gstack-harness register generic --print` into its instructions. + +## Module loadouts (gstack-modules) + +These codes come from `bin/gstack-modules` and `gen-skill-docs --loadout/--modules` (guide: [loadouts.md](loadouts.md)). Each one exits 2 before anything is written, and none falls back to the `full` loadout: an eval arm that silently rendered `full` would measure the control. + + +### `LOADOUTS_INVALID: modules/loadouts.json …` + +**Meaning.** `modules/loadouts.json` is unreadable, or names a module, base loadout, rung or default that does not exist, excludes a pinned module, or maps one model id to two rungs. **Fix.** Correct the named entries, then run `bin/gstack-modules validate` until it prints `LOADOUTS: ok`; `git checkout -- modules/loadouts.json` restores the committed file. + + +### `LOADOUT_UNKNOWN: "" is not a loadout (valid: …)` + +**Meaning.** `--loadout` or the first token of `--modules` names no loadout in `modules/loadouts.json`. **Fix.** Use a name from the `valid:` list (`bin/gstack-modules list` prints them); `full` is always present. + + +### `MODULE_SPEC_INVALID: …` + +**Meaning.** A `--modules` token is not `-` or `+`, both `--loadout` and `--modules` were given, `gen:skill-docs` got a selection with exclusions but no `--out-dir`, or a render flag is missing or malformed. **Fix.** Write the spec as `,-,+` (for example `full,-section:office-hours/second-opinion`) and pass the flags `bin/gstack-modules --help` lists. + + +### `MODULE_UNKNOWN: "" is not a module` + +**Meaning.** The id names no skill, section, overlay or preamble piece. **Fix.** Copy the id from `bin/gstack-modules list`. + + +### `MODULE_PINNED: is pinned and can never be excluded` + +**Meaning.** The spec removes a module the safety contract needs: the start command (`preamble:bash`), plan-mode rules, the question format, completion status, the unattended profile, /ship's review gates, the router or `/gstack-upgrade`. **Fix.** Drop `-` from the spec; `bin/gstack-modules list --pinned` prints every pinned id. + + +### `MODULE_EXCLUSION_UNSAFE: : referenced by :` + +**Meaning.** The rendered tree still points at a module the loadout left out, so an agent following it would read a file that is not there. **Fix.** Exclude the referencing module as well, or wrap the referencing skeleton text in `{{IF_SECTION:}}…{{/IF_SECTION}}` in its template (the text renders unchanged when the section loads). Nothing was published; rerun after the change. + + +### `RENDER_FAILED: gen-skill-docs failed: …` + +**Meaning.** Generation itself failed for this loadout (an unresolved placeholder, an oversized skill, a missing section). **Fix.** Fix the named template or module and rerun. The staging directory was removed and `--out-dir` is unchanged. + + +### `RENDER_DEST_NOT_OWNED: exists and holds no loadout.lock.json` + +**Meaning.** `--out-dir` is a non-empty directory that an earlier `gstack-modules render` did not write, so replacing it could delete someone's files. **Fix.** Pass a new or empty directory, or the directory of an earlier render. diff --git a/docs/unattended.md b/docs/unattended.md index 7418fceb4..905de39cc 100644 --- a/docs/unattended.md +++ b/docs/unattended.md @@ -187,6 +187,15 @@ most 300 words; a subagent brief names the files to read instead of pasting them. Evidence goes in files the report points to. Waits go on operations, never on polling wakes. +### Token caps and fresh-context handoffs + +A parent bounds a /ship run with `--token-cap ` (or `GSTACK_SHIP_TOKEN_CAP`). +It is an admission cap: /ship meters usage, reserves every step and dispatch +batch before it starts, and stops `status=incomplete` with a `RECOVER:` line +instead of starting work that would cross the cap. Long runs hand Steps 7–11.5 +and 12–22 to fresh-context children. The flow, the BUDGET line and the result +codes are in [ship-budget.md](ship-budget.md). + ### The outside voice on Capy Step 11's outside adversarial review prefers the Codex CLI. On a Capy machine @@ -225,9 +234,10 @@ and reruns carry with `--pregate .gstack/tmp/pregate.json`. `CARRY: carried from now names HEAD with a `carry` object holding the `git range-diff` evidence, and `ship-run.json` gains `carried_from` and `carry_reason`; the `review_loop` counters are kept, because the reviewed product diff is unchanged. `CARRY: -current` means nothing moved. `CARRY: refused (RECEIPT_CARRY_PRODUCT_CHANGED)` -or `(RECEIPT_CARRY_REFUSED)` with the refused result line means the product -diff changed or the reviewed head left HEAD's history, so /ship runs again; +current` means nothing moved. `CARRY: refused (RECEIPT_CARRY_PRODUCT_CHANGED)`, +`(RECEIPT_CARRY_TREE_MISMATCH)` or `(RECEIPT_CARRY_REFUSED)` with the refused +result line means the product diff changed, or history was rewritten onto a +tree no review saw, so /ship runs again; `(RECEIPT_GIT_TOO_OLD)` means the machine's git predates 2.39 and cannot run `patch-id --verbatim` ([ship-policy.md](ship-policy.md#receipt-carry)). @@ -494,6 +504,53 @@ by its runner. Result codes: `EXECUTION_UNKNOWN`, `RUN_LOCKED`, decision ids are renamed and journaled); one written by a newer gstack is refused. +### Carry-forward + +A gate revision after the first (`gate_rev` 2 and later, written after a +`revise`) is answered with the owner's recorded words from the revision before +it when nothing new needs their decision. `gstack-autoplan` prints +`CARRIED: gate_rev= <- gate_rev= words="" by= reason=`, +then the usual `APPROVED:` lines, and journals `gate_carried`. The carry needs +all of: the earlier gate approved (`p1a` or `p1b`) with `rec` or "do it" +(not item tokens), no item there left pending, and the owner's words +recorded; that gate was not itself carried; every accepted change incorporated +or settled; the plan file's bytes equal those recorded at the gate or at the +`revise` that took the changes (any later edit refuses, an ELI5-only one +included); no urgent or +outside-plan finding open; and every new gate item one of the cases below. +Anything else prints `CARRY: no ()` (journal `carry_refused`) and the gate +goes to the owner as before. `--no-carry-forward` on the first `next` turns it +off for the run. + +- **"do it".** When the owner's words were "do it" (their words, not a + `captain:` relay of them), a new `auto` item that changes no scope, cost or + direction, whose recommended option changes no plan text, and is no round + or budget grant takes its recommendation. The + decision row gets `carried_under: do it`, the output prints + `CARRIED_UNDER_DO_IT:` per item, and the approval record lists them as + "taken under "do it", not seen by the owner". `rec` carries no new item. +- **Unreviewed post-cap delta.** A "plan changed after cap" item + recommending `a` (accept) is read by one reviewer before it carries. `CARRY_CHECK:` names the attempt and + the prompt (the delta against `plan-at-gate.r.md`, the accepted changes, + the full plan); the run reserves the estimate in `spend.json` and refuses + when it is over `--carry-check-cap ` (default 5) or the run's cap. + Dispatch it to a model family other than the plan reviewers', then + `check --out --attempt --result --model ` + (`--same-family ""` when no other family is available). A High or + Critical finding, or `--unavailable ""`, leaves the gate for the + owner. The verdict is saved as `carry_check` on `gate.json`, on the + decision rows (`carry_check`) and in `/decisions.tsv`. A pending + check is void, its reservation released and the gate left for the owner, + when the owner answers the gate, the plan is revised, a new gate is + written, or the delta changed after dispatch. + +Carried rows keep `answered_by: agent:gstack-autoplan` and name their source +(`carried_gate_from`, `carried_gate_rev`, `carried_answered_by`); +`gstack-approvals import --autoplan` writes the carried gate as its own row, +and `gstack-owner-brief render --captain` opens with "Nothing pending. +Carried forward from gate_rev ", followed by any items taken under "do it" +without being shown to the owner. + ## Owner brief `gstack-owner-brief render --out ` is what the owner sees at the final diff --git a/gstack/llms.txt b/gstack/llms.txt index 16e0fc860..a28e648fb 100644 --- a/gstack/llms.txt +++ b/gstack/llms.txt @@ -103,7 +103,7 @@ Run with `browse [args]`. Full reference: `browse/SKILL.md`. - `click `: Click element - `cookie =`: Set cookie on current page domain - `cookie-import `: Import cookies from JSON file -- `cookie-import-browser [browser] [--domain d] [--profile p] [--all] [--clear-storage] [--verify-auth]`: Copy cookies from chrome, chromium, brave, edge, Windows-only opera, opera-gx, or macOS-only comet, arc, dia. +- `cookie-import-browser [browser] [--domain d] [--profile p] [--all] [--clear-storage] [--verify-auth]`: Copy cookies from chrome, chromium, brave, edge, Windows-only opera, opera-gx, or macOS-only comet or arc. - `dialog-accept [text]`: Auto-accept next alert/confirm/prompt. - `dialog-dismiss`: Auto-dismiss next dialog - `fill `: Fill input diff --git a/hosts/hermes.ts b/hosts/hermes.ts index 520abbba6..18043b6dc 100644 --- a/hosts/hermes.ts +++ b/hosts/hermes.ts @@ -6,11 +6,14 @@ const hermes = defineHost({ tier: 'experimental', capabilities: { toolExecution: true, questions: 'native', planMode: false, delegation: true, browser: true, safetyHooks: 'advisory' }, - // Hermes indexes skills by frontmatter name, first match wins (#2825). + // Hermes indexes skills by frontmatter name, first match wins (#2825). Its + // skills index shows 57 chars of a description and "..." (agent/skill_utils.py + // SKILL_PROMPT_DESC_LIMIT = 60), so each description leads with when to use it. frontmatter: { mode: 'allowlist', keepFields: ['name', 'description'], descriptionLimit: null, + descriptionLead: 57, nameMatchesDirectory: true, }, diff --git a/hosts/openclaw.ts b/hosts/openclaw.ts index 1b1c431e5..ac9961e2f 100644 --- a/hosts/openclaw.ts +++ b/hosts/openclaw.ts @@ -15,8 +15,9 @@ const openclaw = defineHost({ suppressedResolvers: [...CROSS_MODEL_RESOLVERS, ...GBRAIN_RESOLVERS], // ./setup --host openclaw (and setup run inside OpenClaw) registers through - // gstack-harness: one gstack router skill in $OPENCLAW_STATE_DIR/skills, or - // every skill with --skills all. OpenClaw's ACP route (docs/OPENCLAW.md) stays. + // gstack-harness: the task skills plus one gstack router skill for the rest in + // $OPENCLAW_STATE_DIR/skills (hybrid), or --skills router|all. OpenClaw's ACP + // route (docs/OPENCLAW.md) stays. install: { linkingStrategy: 'symlink-generated', registration: 'harness', diff --git a/lib/approval-record.ts b/lib/approval-record.ts index ed8bcf738..38d798682 100644 --- a/lib/approval-record.ts +++ b/lib/approval-record.ts @@ -52,6 +52,11 @@ export type Env = NodeJS.ProcessEnv; const git = (cwd: string, args: string[]) => spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 10_000 }); +/** A branch this checkout knows: a local head or an origin remote-tracking ref. */ +export function branchExists(cwd: string, branch: string): boolean { + return [`refs/heads/${branch}`, `refs/remotes/origin/${branch}`].some(ref => git(cwd, ['rev-parse', '--verify', '--quiet', ref]).status === 0); +} + /** One contained path segment for a branch: readable prefix plus a hash of the exact ref. */ export function branchKey(branch: string): string { const readable = branch.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[.-]+/, '').slice(0, 60) || 'branch'; @@ -226,13 +231,15 @@ export function renderRecord(read: ReadResult, loc: StoreLocation, o: { heading? return [...head, ...lines, '', `Source: gstack-approvals record for ${cell(loc.branch)} (display only; not an approval citation).`, ''].join('\n'); } -interface DecisionLike { id?: string; title?: string; status?: string; chosen?: string | null; recommended?: string | null; gate_rev?: number; answered_at?: string; answered_by?: string; reply?: string; owner_reply?: string; carried_from?: string; label?: string; chosen_text?: string } +interface DecisionLike { id?: string; title?: string; status?: string; chosen?: string | null; recommended?: string | null; gate_rev?: number; answered_at?: string; answered_by?: string; reply?: string; owner_reply?: string; carried_from?: string; label?: string; chosen_text?: string; + carried_gate_from?: string; carried_gate_rev?: number; carried_answered_by?: string; carried_under?: string; carry_check?: string } const stripRef = (t: string) => t.replace(/\s*\[[^\]]*\]\s*$/, '').trim(); /** * Rows for every answered gate in an autoplan run: one row per answer event (gate_rev, time, answerer), covering - * the items it settled. Carried-forward answers were recorded when first given and are skipped. Ids are stable, + * the items it settled. Item answers carried from an earlier revision were recorded when first given and are skipped; + * a whole gate carried forward (lib/autoplan-carry.ts) gets its own row naming the revision its words came from. Ids are stable, * so a rerun (or a retry after an interrupted import) adds nothing twice. */ export function importAutoplan(runDir: string, branch: string, by?: string): ApprovalRow[] | RecordError { @@ -265,10 +272,16 @@ export function importAutoplan(runDir: string, branch: string, by?: string): App const changed = items.filter(r => r.chosen && r.recommended && r.chosen !== r.recommended); const stillPending = rows.filter(r => r.gate_rev === rev && r.status === 'pending'); const answerer = first.answered_by ?? 'unknown'; - const who = answerer === 'human' ? (by ? `${by}, typed at the gate` : 'the owner, typed at the gate') : `${by ?? 'the owner'}, relayed by ${answerer}`; - const scope = `the reviewed plan (sha256 ${planSha}), ${changed.length ? `${changed.length} recommendation(s) changed: ${changed.map(r => stripRef(r.title ?? '')).join('; ')}` : 'every recommendation taken'}`; + const carried = p1?.carried_gate_from ? p1 : undefined; + const relayed = carried?.carried_answered_by && carried.carried_answered_by !== 'human' ? `, relayed by ${carried.carried_answered_by}` : ''; + const who = carried ? `${by ?? 'the owner'} (words from gate_rev ${carried.carried_gate_rev}${relayed}), carried forward by gstack-autoplan` + : answerer === 'human' ? (by ? `${by}, typed at the gate` : 'the owner, typed at the gate') : `${by ?? 'the owner'}, relayed by ${answerer}`; + const unseen = items.filter(r => r.carried_under).map(r => stripRef(r.title ?? '')); + const checked = [...new Set(items.map(r => r.carry_check).filter((c): c is string => !!c))]; + const scope = [`the reviewed plan (sha256 ${planSha}), ${changed.length ? `${changed.length} recommendation(s) changed: ${changed.map(r => stripRef(r.title ?? '')).join('; ')}` : 'every recommendation taken'}`, + unseen.length ? `taken under "do it", not seen by the owner: ${unseen.join('; ')}` : '', checked.length ? `post-cap delta checked by ${checked.join(', ')}` : ''].filter(Boolean).join('; '); const built = buildRow({ - ask: `Approve the plan "${planTitle}" (autoplan run ${runId}, ${items.length + (p1 ? 1 : 0)} decisions)`.slice(0, CAPS.ask), + ask: `Approve the plan "${planTitle}" (autoplan run ${runId}, ${carried ? `gate_rev ${rev} carried forward from gate_rev ${carried.carried_gate_rev}, ` : ''}${items.length + (p1 ? 1 : 0)} decisions)`.slice(0, CAPS.ask), words: first.owner_reply ?? first.reply ?? '(no words recorded)', by: who.slice(0, CAPS.by), scope: scope.slice(0, CAPS.scope), diff --git a/lib/autoplan-carry.ts b/lib/autoplan-carry.ts new file mode 100644 index 000000000..0e6ae18ef --- /dev/null +++ b/lib/autoplan-carry.ts @@ -0,0 +1,252 @@ +/** + * autoplan-carry — carry the owner's last answer to a later gate revision (GSTA-155, + * docs/unattended.md#carry-forward). When a gate_rev N+1 asks nothing the owner has not + * already decided, the runner answers it with the owner's recorded gate_rev N words instead + * of a second round trip, and records that it did (decisions.jsonl `carried_gate_from`, + * journal `gate_carried`, `/decisions.tsv`). It never invents an answer: every + * carried answer is the owner's own earlier words, and every refusal says which condition failed. + * + * A carry needs all of: carry not turned off (`--no-carry-forward`); gate_rev N approved (p1 a or b) + * with the owner's words recorded, and not itself a carry; every change accepted at N + * incorporated or settled; the plan file unchanged since the gate or the revise that took those + * changes, and the reviewed plan equal to it; no open urgent finding; and every new item already + * carried. Two kinds of new item do not block: items a "do it" covers (the owner's words are + * "do it": an auto item that changes no scope, cost or direction and is no round grant), and a + * capped-delta item recommending "accept", which first gets one reviewer on just the delta + * (`CARRY_CHECK:`, answered with `gstack-autoplan check`); a High or Critical finding there + * means no carry, and the gate goes to the owner as before. + */ +import { createHash } from 'node:crypto'; +import * as fs from 'node:fs'; +import * as path from 'node:path'; +import { attemptEstimate } from './autoplan-budget'; +import { lineDiff } from './autoplan-confirm'; +import { answerGate } from './autoplan-gate'; +import { driftLine } from './autoplan-plan-text'; +import { BOUNDARY, RESULT_FORMAT, REVIEWER_TRAILER } from './autoplan-prompts'; +import { parseReviewResult } from './autoplan-reconcile'; +import { FILES, RunError, journal, now, readDecisions, readJournal, readState, writeDecisions, writeState, type RunState } from './autoplan-state'; +import { appendTrailRow } from './decision-trail'; +import { decisionId, parseReply, type GateItem, type GateList } from './gate-list'; +import { readJsonl } from './headless-artifacts'; +import { modelFamily } from './outside-voice-runner'; +import { release, reserve, settle } from './spend-ledger'; + +export const DEFAULT_CARRY_CHECK_CAP_USD = 5; +const HIGH = ['Critical', 'High']; +const DO_IT = /^\s*(?:(?![^:]*\bcaptain\b)[a-z]+(?: [a-z]+){0,2}:\s*)?do it[\s.!]*$/i; +/** The owner's verbatim words are a "do it" (optionally after their name), not a Captain's words or an item token (`p3b: do it`) naming one. */ +export const isDoIt = (words: string | undefined): boolean => !!words && DO_IT.test(words); + +export interface CarryCheck { + attempt: string; prompt: string; result: string; delta_sha256: string; items: string[]; estimate_usd: number; + status: 'dispatched' | 'passed' | 'failed' | 'unavailable'; model?: string; max_severity?: string; findings?: number; at: string; +} +export interface CarryRecord { + gate_rev: number; from_gate_rev?: number; verdict: 'carried' | 'refused' | 'check_pending'; + reason: string; words?: string; under_do_it?: string[]; check?: CarryCheck; lines: string[]; at: string; +} + +const sha256 = (text: string | Buffer) => createHash('sha256').update(text).digest('hex'); +const planFile = (state: RunState) => state.plan_input ?? state.plan_source; +const fileSha = (file: string) => (fs.existsSync(file) ? sha256(fs.readFileSync(file)) : undefined); +export const atGateCopy = (out: string, rev: number) => path.join(out, `plan-at-gate.r${rev}.md`); + +/** What finishGate journals beside gate_written: the plan file's bytes and a copy of the reviewed plan the owner is asked about. */ +export function gateEvidence(state: RunState, rev: number): { source_file_sha256?: string } { + if (fs.existsSync(state.active_plan)) fs.copyFileSync(state.active_plan, atGateCopy(state.out, rev)); + return { source_file_sha256: fileSha(planFile(state)) }; +} + +/** The lines the latest carry decision printed, for the command that wrote this gate revision. */ +export function carryLines(state: RunState): string[] { + const c = state.carry; + return c && c.gate_rev === state.gate_rev ? c.lines : []; +} + +function record(state: RunState, c: Omit): CarryRecord { + const full = { ...c, at: now() }; + state.carry = full; + journal(state.out, { event: c.verdict === 'carried' ? 'gate_carried' : c.verdict === 'check_pending' ? 'carry_check_dispatched' : 'carry_refused', gate_rev: c.gate_rev, from_gate_rev: c.from_gate_rev ?? null, reason: c.reason, ...(c.under_do_it?.length ? { under_do_it: c.under_do_it } : {}), ...(c.check ? { check: c.check.attempt, check_status: c.check.status } : {}) }); + appendTrailRow(path.join(state.out, 'decisions.tsv'), ['gate', c.verdict === 'carried' ? `carried gate_rev ${c.gate_rev} from gate_rev ${c.from_gate_rev}` : c.verdict === 'check_pending' ? `delta check before carrying gate_rev ${c.gate_rev}` : `no carry for gate_rev ${c.gate_rev}`, + c.reason, c.check ? path.basename(c.check.result) : 'decisions.jsonl', c.check?.status ?? c.verdict]); + return full; +} +const refuse = (state: RunState, rev: number, from: number | undefined, reason: string) => record(state, { gate_rev: rev, from_gate_rev: from, verdict: 'refused', reason, lines: [`CARRY: no (${reason})`] }); + +/** Drop a delta check still waiting for its reviewer (the owner answered, the plan was revised, a new gate was written) and release its reservation. */ +export function voidPendingCheck(state: RunState, why: string): string[] { + const c = state.carry; + if (c?.verdict !== 'check_pending' || !c.check) return []; + release(path.join(state.out, FILES.spend), c.check.attempt); + const out = refuse(state, c.gate_rev, c.from_gate_rev, `delta check ${c.check.attempt} void: ${why}`); + out.check = { ...c.check, status: 'unavailable' }; + return out.lines; +} + +/** The reviewed plan's changes since the copy taken when the owner was asked at `rev`, and their hash. */ +function deltaSince(state: RunState, rev: number): { diff: string; sha: string } | undefined { + const before = atGateCopy(state.out, rev); + if (!fs.existsSync(before)) return undefined; + const diff = lineDiff(fs.readFileSync(before, 'utf8'), fs.readFileSync(state.active_plan, 'utf8')).filter(l => l.op !== ' ').map(l => `${l.op} ${l.text}`).join('\n'); + return { diff, sha: sha256(diff) }; +} + +interface Source { id: string; gate_rev: number; words: string; by?: string } +type Plan = { source: Source; doIt: GateItem[]; deltas: GateItem[] } | { reason: string; from?: number }; + +/** Every condition but the delta check; returns why not, or what the carry takes. */ +function assess(state: RunState, prev: GateList, list: GateList): Plan { + const from = prev.gate_rev; + if (state.carry_forward === false) return { reason: 'carry-forward is off for this run (--no-carry-forward)', from }; + const p1 = readDecisions(state.out).find(r => r.gate_rev === from && (r.label ?? '').toLowerCase() === 'p1'); + if (!p1 || p1.status === 'pending' || !p1.answered_at) return { reason: `gate_rev ${from} was not answered`, from }; + const unanswered = readDecisions(state.out).find(r => r.gate_rev === from && r.status === 'pending'); + if (unanswered) return { reason: `gate_rev ${from} left ${unanswered.label ?? unanswered.id} unanswered`, from }; + if (p1.chosen !== 'a' && p1.chosen !== 'b') return { reason: `gate_rev ${from} answer was p1${p1.chosen}, not an approval`, from }; + if (p1.carried_gate_from) return { reason: `gate_rev ${from} was itself carried; the owner answers this one`, from }; + if (parseReply(p1.reply ?? '', prev).mode !== 'rec') return { reason: `gate_rev ${from} was answered with item tokens, not rec or "do it"`, from }; + const words = p1.owner_reply ?? (p1.answered_by === 'human' ? p1.reply : undefined); + if (!words?.trim()) return { reason: `no owner words recorded at gate_rev ${from}`, from }; + const amendments = (state.amendments ?? []).filter(a => a.gate_rev === from); + const open = amendments.find(a => a.status !== 'incorporated' && a.status !== 'settled'); + if (open) return { reason: `accepted change ${open.decision} is ${open.status}`, from }; + const journalRows = readJournal(state.out); + const at = journalRows.map(r => r.event === 'gate_written' && r.gate_rev === from).lastIndexOf(true); + let expected: string | undefined = at >= 0 ? journalRows[at]!.source_file_sha256 : undefined; + for (const r of journalRows.slice(at + 1)) if (r.event === 'plan_revised') expected = r.source_file_sha256; + if (!expected) return { reason: 'no plan evidence recorded for the gate or the revise (a run written before carry-forward)', from }; + if (fileSha(planFile(state)) !== expected) return { reason: `the plan file ${path.basename(planFile(state))} changed after the owner's answer or the revise that took it`, from }; + if (driftLine(state, 'PLAN_SOURCE_CHANGED')) return { reason: 'the reviewed plan differs from the plan file', from }; + const urgent = readJsonl(path.join(state.out, 'findings.jsonl')).rows.find(r => (r.urgent === true || r.outside_plan === true) && !r.settled_by); + if (urgent) return { reason: `urgent finding open: ${String(urgent.title ?? urgent.id)}`, from }; + const doIt: GateItem[] = []; const deltas: GateItem[] = []; + for (const item of list.items) { + if (item.id === 'p1' || item.carried) continue; + const option = item.options.find(o => o.key === item.recommended); + if (item.cap?.kind === 'delta' && !option?.changes_plan && item.recommended === 'a') { deltas.push(item); continue; } + if (isDoIt(words) && item.kind === 'auto' && !item.cap && !option?.changes_plan && !['scope', 'cost', 'direction'].includes(item.changes ?? '')) { doIt.push(item); continue; } + return { reason: `new item ${item.id}: ${item.title}`, from }; + } + return { source: { id: p1.id, gate_rev: from, words, by: p1.answered_by }, doIt, deltas }; +} + +/** Called by finishGate once gate_rev N+1 is written (status gate_pending): carry, set up the delta check, or say why not. */ +export function evaluateCarry(state: RunState, prev: GateList | undefined, list: GateList): CarryRecord | undefined { + voidPendingCheck(state, `gate_rev ${list.gate_rev} was written`); + if (!prev || list.gate_rev < 2) return undefined; + try { + const plan = assess(state, prev, list); + if ('reason' in plan) return refuse(state, list.gate_rev, plan.from, plan.reason); + if (plan.deltas.length) return dispatchCheck(state, prev, list, plan); + return carry(state, list, plan.source, plan.doIt, plan.deltas); + } catch (e: any) { + if (readDecisions(state.out).some(r => r.gate_rev === list.gate_rev && r.answered_at && !r.carried_from)) throw e; + return refuse(state, list.gate_rev, prev.gate_rev, `error: ${e instanceof RunError ? `${e.detail} (${e.code})` : e?.message ?? e}`); + } +} + +function dispatchCheck(state: RunState, prev: GateList, list: GateList, plan: Extract): CarryRecord { + const rev = list.gate_rev; + const cap = state.carry_check_cap_usd ?? DEFAULT_CARRY_CHECK_CAP_USD; + const estimate = attemptEstimate(state, undefined, process.env).usd; + if (estimate > cap) return refuse(state, rev, prev.gate_rev, `delta check estimate ${estimate.toFixed(2)} is over the per-gate cap ${cap.toFixed(2)} (--carry-check-cap)`); + const delta = deltaSince(state, prev.gate_rev); + if (!delta) return refuse(state, rev, prev.gate_rev, `no copy of the plan the owner answered at gate_rev ${prev.gate_rev}`); + const current = fs.readFileSync(state.active_plan, 'utf8'); + const { diff, sha: deltaSha } = delta; + const attempt = `${state.run}-c${rev}`; + const prompt = path.join(state.out, `carry-check-g${rev}-prompt.md`); + const result = path.join(state.out, `carry-check-g${rev}.md`); + try { reserve(path.join(state.out, FILES.spend), attempt, estimate, { cap: state.spend_cap_usd, label: 'carry-check' }); } + catch (e: any) { return refuse(state, rev, prev.gate_rev, `delta check does not fit the run's spend cap: ${e?.message ?? e}`); } + const accepted = (state.amendments ?? []).filter(a => a.gate_rev === prev.gate_rev).map(a => `- ${a.title} -> ${a.text}`).join('\n') || '- (none recorded)'; + fs.writeFileSync(prompt, [BOUNDARY, '', + `You are checking one edit to a reviewed plan before gstack reuses the owner's approval of gate_rev ${prev.gate_rev} for gate_rev ${rev}. The owner accepted these changes:`, accepted, '', + 'The plan was edited after that answer, but the phases that would re-review the edit were at their round cap, so no reviewer has read it. Read the delta and say whether it implements the accepted changes, adds nothing the owner did not accept (scope, cost or direction), and leaves the plan correct. Rate a finding High or Critical only when the edit adds an unaccepted change, contradicts an accepted one, or would make the plan fail a test, break production, or lose data or secrets; anything else is Medium or lower.', '', + `Delta (reviewed plan at gate_rev ${prev.gate_rev} -> now; + added, - removed; SHA-256 ${deltaSha}):`, '```diff', diff, '```', '', + 'The complete current plan follows as context.', '', current, + REVIEWER_TRAILER, RESULT_FORMAT('carry-check', deltaSha, result)].join('\n')); + const check: CarryCheck = { attempt, prompt, result, delta_sha256: deltaSha, items: plan.deltas.map(i => i.id), estimate_usd: estimate, status: 'dispatched', at: now() }; + const family = state.native_model ? `not ${modelFamily(state.native_model)}` : 'differs from the plan reviewers where available'; + return record(state, { gate_rev: rev, from_gate_rev: prev.gate_rev, verdict: 'check_pending', words: plan.source.words, under_do_it: plan.doIt.map(i => i.id), check, + reason: `only an unreviewed post-cap delta is new (${check.items.join(',')}); one reviewer reads it first`, + lines: [`CARRY_CHECK: attempt=${attempt} items=${check.items.join(',')} prompt=${prompt} result=${result} model_family=${family} estimate=${estimate.toFixed(2)} cap=${cap.toFixed(2)}`, + `NEXT: dispatch one reviewer on the prompt, then gstack-autoplan check --out ${state.out} --attempt ${attempt} --result ${result} --model (or --unavailable "" to relay the gate as today)`] }); +} + +function carry(state: RunState, list: GateList, source: Source, doIt: GateItem[], deltas: GateItem[], check?: CarryCheck): CarryRecord { + const rev = list.gate_rev; + const p1 = list.items.find(i => i.id === 'p1')!; + const reply = list.items.map(i => `${i.id}${i.id === 'p1' ? p1.recommended : i.carried?.chosen ?? i.recommended}`).join(' '); + const reason = [doIt.length || deltas.length ? '' : 'no new choice', doIt.length ? `"do it" covers ${doIt.map(i => i.id).join(',')}` : '', deltas.length ? `delta check passed on ${deltas.map(i => i.id).join(',')}` : '', + 'plan unchanged since the accepted changes'].filter(Boolean).join('; '); + const answered = answerGate(state, rev, reply, 'agent:gstack-autoplan', { carry: { from: source.id, gate_rev: source.gate_rev, words: source.words, by: source.by, reason } }); + const marks = new Map>([...doIt.map(i => [decisionId(list.run, rev, i.id), { carried_under: 'do it' }] as const), ...deltas.map(i => [decisionId(list.run, rev, i.id), { carry_check: check?.attempt ?? '' }] as const)]); + if (marks.size) writeDecisions(state.out, readDecisions(state.out).map(r => (marks.has(r.id) ? { ...r, ...marks.get(r.id) } : r))); + const lines = [`CARRIED: gate_rev=${rev} <- gate_rev=${source.gate_rev} words=${JSON.stringify(source.words)} by=${source.by ?? 'unknown'} reason=${reason}`, + ...doIt.map(i => `CARRIED_UNDER_DO_IT: ${i.id} ${i.title} -> ${i.options.find(o => o.key === i.recommended)?.text ?? i.recommended} (the owner has not seen this item)`), + ...answered.lines]; + return record(state, { gate_rev: rev, from_gate_rev: source.gate_rev, verdict: 'carried', reason, words: source.words, under_do_it: doIt.map(i => i.id), ...(check ? { check } : {}), lines }); +} + +export interface CheckOptions { out: string; attempt?: string; result?: string; model?: string; unavailable?: string; sameFamily?: string } + +/** `gstack-autoplan check`: bind the delta reviewer's result (or its absence) and carry, or leave the gate for the owner. */ +export function submitCarryCheck(o: CheckOptions): { state: RunState; lines: string[] } { + const state = readState(path.resolve(o.out)); + const c = state.carry; + if (!c || c.verdict !== 'check_pending' || !c.check || state.status !== 'gate_pending' || c.gate_rev !== state.gate_rev) throw new RunError('PHASE_NOT_AWAITING', `no delta check is pending (run is ${state.status}, gate_rev=${state.gate_rev ?? 'none'})`, 3); + const check = c.check; + if (o.attempt !== check.attempt) throw new RunError('ATTEMPT_MISMATCH', `pass --attempt ${check.attempt}`, 3); + const stale = readDecisions(state.out).some(r => r.gate_rev === c.gate_rev && r.answered_at && !r.carried_from) ? `the owner answered gate_rev ${c.gate_rev}` + : deltaSince(state, c.from_gate_rev ?? 0)?.sha !== check.delta_sha256 ? 'the plan changed after the delta check was dispatched' : undefined; + if (stale) { + const lines = voidPendingCheck(state, stale); + writeState(state); + return { state, lines }; + } + const gateFile = path.join(state.out, 'gate.json'); + const list = JSON.parse(fs.readFileSync(gateFile, 'utf8')) as GateList; + const spend = path.join(state.out, FILES.spend); + let out: CarryRecord; + if (o.unavailable !== undefined) { + release(spend, check.attempt); + list.carry_check = { attempt: check.attempt, model: 'none', verdict: 'unavailable', max_severity: 'none', findings: 0, at: now() }; + fs.writeFileSync(gateFile, JSON.stringify(list, null, 2) + '\n'); + out = refuse(state, c.gate_rev, c.from_gate_rev, `delta check unavailable: ${o.unavailable}`); + out.check = { ...check, status: 'unavailable' }; + } else { + if (!o.result || !o.model) throw new RunError('RESULT_RECEIPT_MISSING', 'check needs --result and --model , or --unavailable ""', 3); + if (!fs.existsSync(o.result)) throw new RunError('RESULT_RECEIPT_MISSING', `result file not found: ${o.result}`); + const family = modelFamily(o.model); + const author = state.native_model ? modelFamily(state.native_model) : undefined; + if (!o.sameFamily && (family === 'unknown' || family === author)) throw new RunError('MODEL_FAMILY_CONFLICT', `${o.model} is ${family === 'unknown' ? 'of no recognized family' : `the plan reviewers' family (${family})`}; use another family, or pass --same-family ""`, 3); + const text = fs.readFileSync(o.result, 'utf8'); + const parsed = parseReviewResult(text, { phase: 'carry-check', sha256: check.delta_sha256 }); + if (!parsed.receipt.ok) throw new RunError('RESULT_RECEIPT_MISSING', parsed.errors[0]!); + if (!parsed.fenceFound || parsed.errors.length) throw new RunError('RESULT_FINDINGS_MISSING', parsed.errors.join('; ')); + fs.writeFileSync(path.join(state.out, `carry-check-g${c.gate_rev}.bound.md`), text, process.platform === 'win32' ? {} : { mode: 0o444 }); + settle(spend, check.attempt, 'unknown'); + const order = ['Informational', 'Low', 'Medium', 'High', 'Critical']; + const max = parsed.findings.map(f => String(f.severity)).reduce((a, b) => (order.indexOf(b) > order.indexOf(a) ? b : a), 'none'); + const blocking = parsed.findings.find(f => HIGH.includes(String(f.severity))); + const done: CarryCheck = { ...check, status: blocking ? 'failed' : 'passed', model: o.model, max_severity: max, findings: parsed.findings.length, at: now() }; + list.carry_check = { attempt: check.attempt, model: o.model + (o.sameFamily ? ` (same family: ${o.sameFamily})` : ''), verdict: blocking ? 'failed' : 'passed', max_severity: max, findings: parsed.findings.length, at: done.at }; + if (blocking) for (const item of list.items) if (check.items.includes(item.id)) (item.flags ??= []).push(`carry check ${o.model}: ${blocking.severity} ${blocking.title}`); + fs.writeFileSync(gateFile, JSON.stringify(list, null, 2) + '\n'); + if (blocking) { + out = refuse(state, c.gate_rev, c.from_gate_rev, `delta check found ${blocking.severity}: ${blocking.title}`); + out.check = done; + } else { + const plan = assess(state, { ...list, gate_rev: c.from_gate_rev! } as GateList, list); + if ('reason' in plan) { out = refuse(state, c.gate_rev, c.from_gate_rev, plan.reason); out.check = done; } + else { + out = carry(state, list, plan.source, plan.doIt, plan.deltas, done); + out.lines.unshift(`CARRY_CHECK: passed attempt=${check.attempt} model=${o.model} findings=${done.findings} highest=${max}`); + } + } + } + writeState(state); + return { state, lines: out.lines }; +} diff --git a/lib/autoplan-gate.ts b/lib/autoplan-gate.ts index 98b381f4f..1488dbc05 100644 --- a/lib/autoplan-gate.ts +++ b/lib/autoplan-gate.ts @@ -24,7 +24,8 @@ import { consensusRecord, reconcile, remedyKey, renderConsensus, SETTLEABLE_CHAN import type { Phase } from './autoplan-prompts'; import { FILES, RunError, journal as journalRow, now, readDecisions, voiceRows, voiceTerminal, writeDecisions, type Amendment, type RunState, type VoiceState } from './autoplan-state'; import { applyCapChoices, pendingDeltas, releaseUndispatched, roundCap, roundOf } from './autoplan-budget'; -import { capyRelayLine } from './captain-brief'; +import { evaluateCarry, gateEvidence, voidPendingCheck } from './autoplan-carry'; +import { buildEli5, capyRelayLine } from './captain-brief'; import { previousReview, reviewRows, settledIds } from './autoplan-confirm'; import { phaseClose } from './autoplan-timing'; import { ANSWERED_BY_RE, applyReply, decisionId, decisionRows, keepDirection, parseReply, pendingHint, recHash, validateGateList, type GateChoice, type GateItem, type GateList, type GateOption, type ParsedReply } from './gate-list'; @@ -237,7 +238,8 @@ export function buildGate(state: RunState, gateRev: number): GateList { } items.push(...capItems(state, { d: () => `d${++d}`, uc: () => `uc${++uc}` })); items.push(planApproval(state, items)); - const list: GateList = { schema_version: 1, run: state.run, gate_rev: gateRev, items, title: '/autoplan final approval gate', rec_rev: 0 }; + const list: GateList = { schema_version: 1, run: state.run, gate_rev: gateRev, items, title: '/autoplan final approval gate', rec_rev: 0, + ...(fs.existsSync(state.active_plan) ? { eli5: buildEli5(fs.readFileSync(state.active_plan, 'utf8'), state.active_plan) } : {}) }; const problems = validateGateList(list); if (problems.length) throw new Error(`gate list invalid: ${problems.join('; ')}`); return list; @@ -285,9 +287,29 @@ export function recommendGate(state: RunState, gateRev: number, itemId: string, ...[capyRelayLine(state.out)].filter((l): l is string => !!l)]; } -/** Every phase closed: write the gate list, decisions, tasks and the exported files; the run ends gate_pending. Unchanged answered proposals carry forward. */ +/** The gate list the owner last answered: gate.json, or its archive (`gate.r[.v].json`) once a reopen moved it. */ +function previousGate(out: string, rev: number): GateList | undefined { + if (rev < 1) return undefined; + const re = new RegExp(`^gate\\.r${rev}(?:\\.v(\\d+))?\\.json$`); + const archived = fs.readdirSync(out).map(f => [f, re.exec(f)] as const).filter(([, m]) => m).sort((a, b) => Number(b[1]![1] ?? 1) - Number(a[1]![1] ?? 1)).map(([f]) => f); + for (const name of ['gate.json', ...archived]) { + const file = path.join(out, name); + if (!fs.existsSync(file)) continue; + const list = JSON.parse(fs.readFileSync(file, 'utf8')) as GateList; + if (list.gate_rev === rev) return list; + } + return undefined; +} + +/** + * Every phase closed: write the gate list, decisions, tasks and the exported files; the run ends gate_pending. Unchanged + * answered proposals carry forward, and a later revision that asks nothing new carries the owner's last answer + * (lib/autoplan-carry.ts; its lines are on `carryLines(state)`). + */ export function finishGate(state: RunState): GateList { const gateRev = (state.gate_rev ?? 0) + 1; + const gateFile = path.join(state.out, 'gate.json'); + const prev = previousGate(state.out, state.gate_rev ?? 0); const list = buildGate(state, gateRev); const kept = readDecisions(state.out).filter(r => r.gate_rev !== gateRev); const answered = new Map(kept.filter(r => r.origin && r.chosen != null && r.status !== 'pending').map(r => [r.origin!, r])); @@ -295,7 +317,7 @@ export function finishGate(state: RunState): GateList { const prev = item.origin ? answered.get(item.origin) : undefined; if (prev && item.options.some(o => o.key === prev.chosen)) item.carried = { from: prev.carried_from ?? prev.id, chosen: prev.chosen!, gate_rev: prev.gate_rev }; } - fs.writeFileSync(path.join(state.out, 'gate.json'), JSON.stringify(list, null, 2) + '\n'); + fs.writeFileSync(gateFile, JSON.stringify(list, null, 2) + '\n'); const rows = decisionRows(list).map(row => { const item = list.items.find(i => decisionId(list.run, gateRev, i.id) === row.id)!; if (!item.carried) return row; @@ -308,7 +330,8 @@ export function finishGate(state: RunState): GateList { state.status = 'gate_pending'; state.gate = { rev: gateRev, items: list.items.length, written_at: now() }; exportRun(state); - journalRow(state.out, { event: 'gate_written', gate_rev: gateRev, items: list.items.length, carried: list.items.filter(i => i.carried).map(i => i.id) }); + journalRow(state.out, { event: 'gate_written', gate_rev: gateRev, items: list.items.length, carried: list.items.filter(i => i.carried).map(i => i.id), ...gateEvidence(state, gateRev) }); + evaluateCarry(state, prev, list); return list; } @@ -321,6 +344,8 @@ export interface AnswerOptions { recHash?: string; /** The owner's verbatim words; required for every `--by agent:` answer. */ ownerReply?: string; + /** A whole-gate carry (lib/autoplan-carry.ts): the earlier p1 decision and the owner's words it reuses. Replaces ownerReply and its re-parse. */ + carry?: { from: string; gate_rev: number; words: string; by?: string; reason: string }; } /** How an accepted plan change is discharged: a packaging/ordering change settles without a plan edit. */ @@ -361,7 +386,7 @@ export function answerGate(state: RunState, gateRev: number, reply: string, answ if (state.status !== 'gate_pending' || !fs.existsSync(gateFile)) throw new RunError('PHASE_NOT_AWAITING', `run is ${state.status}, not gate_pending`, 3); if (answeredBy !== undefined && !ANSWERED_BY_RE.test(answeredBy)) throw new RunError('ANSWER_BY_REQUIRED', `--by ${JSON.stringify(answeredBy)} is neither human nor agent:`, 3); if (answeredBy === undefined && state.session_kind === 'unattended') throw new RunError('ANSWER_BY_REQUIRED', 'an unattended run records who answered; pass --by human or --by agent:', 3); - if (answeredBy?.startsWith('agent:') && o.ownerReply === undefined) throw new RunError('OWNER_REPLY_REQUIRED', `${answeredBy} relayed or decided this reply; pass the owner's words verbatim with --owner-reply "" (or --owner-reply - / --owner-reply-file )`, 3); + if (answeredBy?.startsWith('agent:') && o.ownerReply === undefined && !o.carry) throw new RunError('OWNER_REPLY_REQUIRED', `${answeredBy} relayed or decided this reply; pass the owner's words verbatim with --owner-reply "" (or --owner-reply - / --owner-reply-file )`, 3); const list = JSON.parse(fs.readFileSync(gateFile, 'utf8')) as GateList; const rows = readDecisions(state.out); const prior = Object.fromEntries(rows.filter(r => r.gate_rev === list.gate_rev && r.chosen != null && r.status !== 'pending' && r.label).map(r => [r.label!.toLowerCase(), r.chosen!])); @@ -372,12 +397,13 @@ export function answerGate(state: RunState, gateRev: number, reply: string, answ if (o.recHash !== undefined && o.recHash !== currentHash) throw new RunError('GATE_REC_STALE', `--rec-hash ${o.recHash} was rendered before the recommendations changed; current rec_hash=${currentHash}`, 3); if (parsed.mode === 'rec' && list.rec_rev === undefined && o.recHash === undefined) throw new RunError('GATE_REC_STALE', `this gate was written before \`rec\`/\`all\` took plan changes (gate.json has no rec_rev), so the owner saw a different meaning; render it again (gstack-gate render ${gateFile} --all), relay it, and answer with --rec-hash ${currentHash}, or reply with explicit