@yagni-app/code 0.3.1 → 0.3.3

package/dist/extension/pipeline/verify.d.ts

@@ -9,9 +9,11 @@
  * the fix stage gets the real errors.
  *
  * `detectVerifyCommands`, `detectVerifyTestCommands`, `parseVerifyFailures`,
- * `classifyTestFailure`, `isFannedOutScript`, `parseChangedPaths` and
- * `resolvePackageDirs` are PURE (unit-tested directly). `makeRunVerify` is the
- * thin impure runner; it shells out (pi's ExtensionContext exposes no exec,
+ * `classifyTestFailure`, `isFannedOutScript`, `parseChangedPaths`,
+ * `resolvePackageDirs` and `resolveClaimDirs` are PURE (unit-tested directly).
+ * `makeRunVerify` (the whole gate) and `makeWorkstreamCheck` (the implement
+ * diamond's per-workstream scoped typecheck, spec decision 6) are the thin impure
+ * runners; they shell out (pi's ExtensionContext exposes no exec,
  * mirroring workspace.ts) and is wrapped with R1's timeout composition
  * (`composeAbortSignal`) so a slow or flaky suite is bounded.
  *
@@ -215,6 +217,22 @@ export declare function classifyTestFailure(output: string, exitCode: number): T
  * throws; always emits at least one finding on a non-zero exit.
  */
 export declare function parseVerifyFailures(output: string, exitCode: number, label: string): Finding[];
+/**
+ * One finding's file as the REPO ROOT sees it.
+ *
+ * The gate is scoped by design: a monorepo package's `typecheck` / `test` runs
+ * IN that package's dir, so its diagnostics come back package-relative
+ * (`src/routes/x.ts`). Everything downstream speaks repo-root-relative paths —
+ * the partition's file claims, the handoff, the fix loop's attribution
+ * (`checker.ts`'s `ownerOf`) — so an un-lifted path can never match the
+ * workstream that owns it and the implicated builder is never re-engaged.
+ *
+ * Lifts a package-relative path onto the command's dir, makes an absolute path
+ * under the repo root relative to it, and leaves anything else (a path outside
+ * the tree, a path already carrying the package prefix) untouched. Idempotent,
+ * so a finding that passes through twice is not double-prefixed.
+ */
+export declare function toRepoRelativePath(file: string, repoRoot: string, commandCwd: string): string;
 /** Result of actually executing the resolved command. */
 export interface VerifyExecResult {
     code: number;
@@ -268,6 +286,71 @@ export interface MakeRunVerifyOpts {
     /** Test-half env override for determinism in tests (default: buildTestEnv() per run). */
     testEnv?: NodeJS.ProcessEnv;
 }
+/**
+ * One workstream as the scoped checker sees it: the name its findings are
+ * attributed to, and the prefix claims the partition gave it.
+ */
+export interface WorkstreamCheckTarget {
+    name: string;
+    files: string[];
+}
+/**
+ * One workstream's scoped typecheck verdict (spec decision 6, first half).
+ * `ran: false` is the honest fail-open: the claims resolved to no package with a
+ * usable build check, so the workstream is UNCHECKED rather than falsely clean.
+ */
+export interface WorkstreamCheckResult {
+    name: string;
+    ran: boolean;
+    ok: boolean;
+    command?: string;
+    reason?: string;
+    findings: Finding[];
+}
+/**
+ * A workstream's claims resolved to package dirs. Claims are PREFIXES and a claim
+ * is very often a directory (`packages/backend/src/routes`), while
+ * {@link resolvePackageDirs} takes the FILE paths git porcelain emits and walks up
+ * from each one's dirname. Appending a probe segment makes a directory claim walk
+ * up from the directory ITSELF, so a claim that IS a package dir resolves to that
+ * package instead of its parent; a claim that is a real file still resolves exactly
+ * as it does for the full gate. Pure (the `readFile` seam keeps it so).
+ */
+export declare function resolveClaimDirs(repoRoot: string, claims: string[], readFile: (path: string) => string): string[];
+export interface MakeWorkstreamCheckOpts {
+    /** Claims → package dirs. Default: {@link resolveClaimDirs} over the real fs. */
+    claimDirs?: (cwd: string, claims: string[]) => string[];
+    /** The build check(s) for those dirs. Default: the same detection the full gate uses. */
+    detect?: (cwd: string, claimDirs: string[]) => VerifyCommand[];
+    exec?: VerifyExec;
+    timeoutMs?: number;
+}
+/**
+ * The per-workstream scoped check the implement diamond runs right after the fan
+ * (spec decision 6): the TYPECHECK half only, run in the package dirs a
+ * workstream's own claims resolve to, so a broken workstream is caught WITH
+ * attribution instead of surfacing later as an anonymous failure of the merged
+ * tree. The test half is deliberately not run here — the repo's tests run ONCE, on
+ * the merged candidate, through {@link makeRunVerify}.
+ *
+ * Three rules keep the attribution honest:
+ *  - a command is kept only when it runs IN one of the workstream's own claim dirs.
+ *    {@link detectVerifyCommands} falls back to the repo-root script when nothing
+ *    scoped qualifies, and a repo-wide typecheck blamed on one workstream is
+ *    exactly the false attribution this check exists to avoid.
+ *  - identical commands are executed ONCE per pass and their result shared, so two
+ *    workstreams inside the same package do not typecheck it twice.
+ *  - a workstream is tagged only with the failures its OWN claims cover. A shared
+ *    package's check can fail on its sibling's files (or on files neither claims):
+ *    tagging every target with the whole output would report a healthy workstream
+ *    broken and defeat the checker's file+line+message dedupe against the full
+ *    verify. Failures outside the target's claims surface ONCE, untagged, so
+ *    {@link attributeFindings} routes them by file or hands them to the synthesizer.
+ *
+ * Fail-open everywhere, like the full gate: an unrunnable check records a reason
+ * and produces no findings.
+ */
+export declare function makeWorkstreamCheck(opts?: MakeWorkstreamCheckOpts): (cwd: string, targets: WorkstreamCheckTarget[], signal?: AbortSignal) => Promise<WorkstreamCheckResult[]>;
 /**
  * Build the runVerify function injected into the orchestrator. It discovers the
  * changed package(s) (scoped to this run's diff via `baselinePaths`), detects a

package/dist/extension/pipeline/verify.js

@@ -9,9 +9,11 @@
  * the fix stage gets the real errors.
  *
  * `detectVerifyCommands`, `detectVerifyTestCommands`, `parseVerifyFailures`,
- * `classifyTestFailure`, `isFannedOutScript`, `parseChangedPaths` and
- * `resolvePackageDirs` are PURE (unit-tested directly). `makeRunVerify` is the
- * thin impure runner; it shells out (pi's ExtensionContext exposes no exec,
+ * `classifyTestFailure`, `isFannedOutScript`, `parseChangedPaths`,
+ * `resolvePackageDirs` and `resolveClaimDirs` are PURE (unit-tested directly).
+ * `makeRunVerify` (the whole gate) and `makeWorkstreamCheck` (the implement
+ * diamond's per-workstream scoped typecheck, spec decision 6) are the thin impure
+ * runners; they shell out (pi's ExtensionContext exposes no exec,
  * mirroring workspace.ts) and is wrapped with R1's timeout composition
  * (`composeAbortSignal`) so a slow or flaky suite is bounded.
  *
@@ -53,6 +55,7 @@ import { readFileSync } from "node:fs";
 // and would break the walk-up termination check.
 import { basename, dirname, join } from "node:path/posix";
 import { killTreeSync, trackChild } from "./childRegistry.js";
+import { claimCovers } from "./fanout.js";
 import { composeAbortSignal } from "./resilience.js";
 import { scrubSecrets } from "./scrubSecrets.js";
 import { snapshotWorkspace } from "./workspace.js";
@@ -544,6 +547,49 @@ export function parseVerifyFailures(output, exitCode, label) {
         },
     ];
 }
+/** Trim a trailing slash and normalise separators for the path math below. */
+const normDir = (p) => p.replace(/\\/g, "/").replace(/\/+$/, "");
+/** Does this look like an absolute path on either platform? */
+const isAbsolutePath = (p) => p.startsWith("/") || /^[A-Za-z]:\//.test(p);
+/**
+ * One finding's file as the REPO ROOT sees it.
+ *
+ * The gate is scoped by design: a monorepo package's `typecheck` / `test` runs
+ * IN that package's dir, so its diagnostics come back package-relative
+ * (`src/routes/x.ts`). Everything downstream speaks repo-root-relative paths —
+ * the partition's file claims, the handoff, the fix loop's attribution
+ * (`checker.ts`'s `ownerOf`) — so an un-lifted path can never match the
+ * workstream that owns it and the implicated builder is never re-engaged.
+ *
+ * Lifts a package-relative path onto the command's dir, makes an absolute path
+ * under the repo root relative to it, and leaves anything else (a path outside
+ * the tree, a path already carrying the package prefix) untouched. Idempotent,
+ * so a finding that passes through twice is not double-prefixed.
+ */
+export function toRepoRelativePath(file, repoRoot, commandCwd) {
+    const raw = file.replace(/\\/g, "/").trim();
+    if (!raw)
+        return file;
+    const root = normDir(repoRoot);
+    if (isAbsolutePath(raw)) {
+        return raw.startsWith(`${root}/`) ? raw.slice(root.length + 1) : raw;
+    }
+    const cleaned = raw.replace(/^\.\/+/, "");
+    const cwd = normDir(commandCwd);
+    if (cwd === root || !cwd.startsWith(`${root}/`))
+        return cleaned;
+    const prefix = cwd.slice(root.length + 1);
+    if (cleaned === prefix || cleaned.startsWith(`${prefix}/`))
+        return cleaned;
+    return `${prefix}/${cleaned}`;
+}
+/** {@link toRepoRelativePath} applied to a finding's location, if it has one. */
+function liftFinding(finding, repoRoot, commandCwd) {
+    if (!finding.file)
+        return finding;
+    const file = toRepoRelativePath(finding.file, repoRoot, commandCwd);
+    return file === finding.file ? finding : { ...finding, file };
+}
 const SAFE_ENV_KEYS = [
     "PATH",
     "HOME",
@@ -644,6 +690,128 @@ export function makeDefaultExec(opts = {}) {
     });
 }
 const defaultExec = makeDefaultExec();
+/**
+ * A workstream's claims resolved to package dirs. Claims are PREFIXES and a claim
+ * is very often a directory (`packages/backend/src/routes`), while
+ * {@link resolvePackageDirs} takes the FILE paths git porcelain emits and walks up
+ * from each one's dirname. Appending a probe segment makes a directory claim walk
+ * up from the directory ITSELF, so a claim that IS a package dir resolves to that
+ * package instead of its parent; a claim that is a real file still resolves exactly
+ * as it does for the full gate. Pure (the `readFile` seam keeps it so).
+ */
+export function resolveClaimDirs(repoRoot, claims, readFile) {
+    const probes = claims
+        .map((c) => c.trim().replace(/^\.\/+/, "").replace(/\/+$/, ""))
+        .filter((c) => c.length > 0 && c !== ".")
+        .map((c) => `${c}/.claim`);
+    return resolvePackageDirs(repoRoot, probes, readFile);
+}
+/** Attribute a scoped finding to the workstream whose claims produced it. */
+function tagFinding(finding, name) {
+    return { ...finding, message: `[${name}] ${finding.message}` };
+}
+/**
+ * The per-workstream scoped check the implement diamond runs right after the fan
+ * (spec decision 6): the TYPECHECK half only, run in the package dirs a
+ * workstream's own claims resolve to, so a broken workstream is caught WITH
+ * attribution instead of surfacing later as an anonymous failure of the merged
+ * tree. The test half is deliberately not run here — the repo's tests run ONCE, on
+ * the merged candidate, through {@link makeRunVerify}.
+ *
+ * Three rules keep the attribution honest:
+ *  - a command is kept only when it runs IN one of the workstream's own claim dirs.
+ *    {@link detectVerifyCommands} falls back to the repo-root script when nothing
+ *    scoped qualifies, and a repo-wide typecheck blamed on one workstream is
+ *    exactly the false attribution this check exists to avoid.
+ *  - identical commands are executed ONCE per pass and their result shared, so two
+ *    workstreams inside the same package do not typecheck it twice.
+ *  - a workstream is tagged only with the failures its OWN claims cover. A shared
+ *    package's check can fail on its sibling's files (or on files neither claims):
+ *    tagging every target with the whole output would report a healthy workstream
+ *    broken and defeat the checker's file+line+message dedupe against the full
+ *    verify. Failures outside the target's claims surface ONCE, untagged, so
+ *    {@link attributeFindings} routes them by file or hands them to the synthesizer.
+ *
+ * Fail-open everywhere, like the full gate: an unrunnable check records a reason
+ * and produces no findings.
+ */
+export function makeWorkstreamCheck(opts = {}) {
+    const claimDirs = opts.claimDirs ?? ((cwd, claims) => resolveClaimDirs(cwd, claims, (p) => readFileSync(p, "utf8")));
+    const detect = opts.detect ?? ((cwd, dirs) => detectVerifyCommands(cwd, { changedDirs: dirs }));
+    const exec = opts.exec ?? defaultExec;
+    const timeoutMs = opts.timeoutMs ?? VERIFY_TIMEOUT_MS;
+    return async function runWorkstreamCheck(cwd, targets, signal) {
+        const runs = new Map();
+        // Failures a target's own claims do not cover are emitted exactly once per
+        // command, untagged, by whichever target reaches the command first.
+        const uncoveredEmitted = new Set();
+        const results = [];
+        for (const target of targets) {
+            const dirs = claimDirs(cwd, target.files);
+            const commands = dirs.length > 0 ? detect(cwd, dirs).filter((c) => dirs.includes(c.cwd)) : [];
+            if (commands.length === 0) {
+                results.push({
+                    name: target.name,
+                    ran: false,
+                    ok: true,
+                    reason: "no scoped build check for its claimed packages",
+                    findings: [],
+                });
+                continue;
+            }
+            const findings = [];
+            const reasons = [];
+            const labels = [];
+            let anyRan = false;
+            for (const command of commands) {
+                const memoKey = `${command.cwd}\u0000${command.argv.join(" ")}`;
+                let run = runs.get(memoKey);
+                if (!run) {
+                    const composed = composeAbortSignal(signal, AbortSignal.timeout(timeoutMs));
+                    try {
+                        const { code, output } = await exec(command.argv, command.cwd, composed);
+                        run = { code, output: scrubSecrets(output) };
+                    }
+                    catch (err) {
+                        run = { error: scrubSecrets(err instanceof Error ? err.message : String(err)) };
+                    }
+                    runs.set(memoKey, run);
+                }
+                if ("error" in run) {
+                    reasons.push(`check (${command.label}) could not run: ${run.error}`);
+                    continue;
+                }
+                if (run.code !== 0) {
+                    const infra = classifyVerifyInfraFailure(run.output, run.code);
+                    if (infra) {
+                        reasons.push(`check (${command.label}) could not run: ${infra}`);
+                        continue;
+                    }
+                }
+                anyRan = true;
+                labels.push(command.label);
+                if (run.code !== 0) {
+                    const parsed = parseVerifyFailures(run.output, run.code, command.label).map((f) => liftFinding(f, cwd, command.cwd));
+                    const covered = parsed.filter((f) => f.file != null && target.files.some((claim) => claimCovers(claim, f.file)));
+                    findings.push(...covered.map((f) => tagFinding(f, target.name)));
+                    if (!uncoveredEmitted.has(memoKey)) {
+                        uncoveredEmitted.add(memoKey);
+                        findings.push(...parsed.filter((f) => !covered.includes(f)));
+                    }
+                }
+            }
+            results.push({
+                name: target.name,
+                ran: anyRan,
+                ok: findings.length === 0,
+                ...(labels.length > 0 ? { command: [...new Set(labels)].join(", ") } : {}),
+                ...(reasons.length > 0 ? { reason: reasons.join("; ") } : {}),
+                findings,
+            });
+        }
+        return results;
+    };
+}
 /**
  * Build the runVerify function injected into the orchestrator. It discovers the
  * changed package(s) (scoped to this run's diff via `baselinePaths`), detects a
@@ -710,8 +878,9 @@ export function makeRunVerify(opts = {}) {
                 }
                 anyRan = true;
                 typecheckLabels.push(command.label);
-                if (code !== 0)
-                    findings.push(...parseVerifyFailures(output, code, command.label));
+                if (code !== 0) {
+                    findings.push(...parseVerifyFailures(output, code, command.label).map((f) => liftFinding(f, cwd, command.cwd)));
+                }
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
@@ -754,7 +923,7 @@ export function makeRunVerify(opts = {}) {
                         testLabels.push(command.label);
                         if (cls.kind === "failures") {
                             const room = Math.max(0, MAX_LOCATED_FINDINGS - testFindingCount);
-                            const take = cls.findings.slice(0, room);
+                            const take = cls.findings.slice(0, room).map((f) => liftFinding(f, cwd, command.cwd));
                             testFindingCount += take.length;
                             findings.push(...take);
                         }

package/dist/extension/subagents.js

@@ -72,6 +72,8 @@ const GENERAL_BODY = `You are a capable software-engineering subagent with a fre
 
 You are grounded in how THIS company works: call ask_yagni before inferring a convention, an ownership rule, or anything organization-specific.
 
+Never fabricate file paths, contents, or findings. If you cannot find something, say so.
+
 Your final message is your report back to the driving agent, which has NOT seen what you read or did. Make it compressed and complete: what you did, what you found, exact file paths and key excerpts, and anything the driver must know before continuing.`;
 const GENERAL_AGENT = {
     name: GENERAL_AGENT_NAME,
@@ -87,6 +89,11 @@ not write code and you do not run commands; you read and report.
 You are grounded in how THIS company works: call ask_yagni before inferring a
 convention, an ownership rule, or anything organization-specific.
 
+Never fabricate file paths, contents, or code. Every path you cite must be
+one you actually read with a tool. If you cannot find something, say "not
+found" — a plausible-sounding invention is worse than no answer because the
+driving agent trusts your report.
+
 Your final message is your report back to the driving agent, which has NOT
 seen what you read. Make it compressed and complete: exact file paths, the
 key excerpts, and a one-paragraph map of how the pieces relate. Say what you
@@ -112,6 +119,9 @@ your final message instead of guessing.
 You are grounded in how THIS company works: call ask_yagni before inferring a
 convention, an ownership rule, or anything organization-specific.
 
+Never fabricate file paths or results. Report what you actually did and what
+you actually found.
+
 Your final message is your report back to the driving agent, which has NOT
 seen what you did. List every file you touched, what changed in each, the
 commands you ran with their outcomes, and anything you deliberately left
@@ -141,6 +151,9 @@ verifiers.
 You are grounded in how THIS company works: call ask_yagni before inferring
 a convention, an ownership rule, or anything organization-specific.
 
+Never fabricate file paths or findings. If you could not verify something,
+say exactly what you tried and why you could not.
+
 Your final message is your verdict back to the driving agent, which has NOT
 seen what you read. Format:
 ## Verdict

package/dist/extension/turnLog.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Client-side turn-lifecycle log — makes a "stuck on Working…" turn legible
+ * without spelunking the raw session `.jsonl`.
+ *
+ * A session write-only WAL, not a buffered in-memory structure: the whole
+ * point is that a turn which STARTS but never ENDS (the silent-freeze failure
+ * this log exists to catch) still leaves a `turn_start` record with no
+ * matching `turn_end`, even if the process is later killed. Each record is a
+ * single sanitized JSON line (no message content, tokens, or tool payloads —
+ * only a timestamp, the session id, a stable event name, and the turn's final
+ * stop reason / error class when it ends). Follows `diagnostics.ts` exactly:
+ * rotating file under `~/.yagni-code/logs/`, fail-soft, hermetic under
+ * `node --test`.
+ */
+export declare function _setTurnLogHomeForTest(dir: string | null): void;
+export declare function turnLogPath(): string;
+export type TurnLifecycleEvent = {
+    kind: "turn_start";
+    sessionId?: string;
+    turnIndex?: number;
+} | {
+    kind: "turn_end";
+    sessionId?: string;
+    turnIndex?: number;
+    /** The fixed stopReason enum from the final assistant message — never a raw error message. */
+    stopReason?: string;
+    /** Time since the matching turn_start, ms. */
+    elapsedMs?: number;
+};
+/**
+ * Append one sanitized lifecycle record. Fail-soft — a logging failure must
+ * never break the turn. `errorClass` is a caller-mapped category, never a
+ * raw error message.
+ */
+export declare function logTurnLifecycle(ev: TurnLifecycleEvent): void;
+/** List existing lifecycle log files (active + rotations), for a report. */
+export declare function listTurnLogFiles(): string[];
+//# sourceMappingURL=turnLog.d.ts.map

package/dist/extension/turnLog.js

@@ -0,0 +1,93 @@
+/**
+ * Client-side turn-lifecycle log — makes a "stuck on Working…" turn legible
+ * without spelunking the raw session `.jsonl`.
+ *
+ * A session write-only WAL, not a buffered in-memory structure: the whole
+ * point is that a turn which STARTS but never ENDS (the silent-freeze failure
+ * this log exists to catch) still leaves a `turn_start` record with no
+ * matching `turn_end`, even if the process is later killed. Each record is a
+ * single sanitized JSON line (no message content, tokens, or tool payloads —
+ * only a timestamp, the session id, a stable event name, and the turn's final
+ * stop reason / error class when it ends). Follows `diagnostics.ts` exactly:
+ * rotating file under `~/.yagni-code/logs/`, fail-soft, hermetic under
+ * `node --test`.
+ */
+import { appendFileSync, mkdirSync, readdirSync, renameSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { codeStateHome } from "./stateHome.js";
+/** Test seam: point the log at a tmpdir (mirrors _setDiagnosticsHomeForTest). */
+let homeOverride = null;
+export function _setTurnLogHomeForTest(dir) {
+    homeOverride = dir;
+}
+function turnLogDir() {
+    return join(codeStateHome(homeOverride), "logs");
+}
+export function turnLogPath() {
+    return join(turnLogDir(), "turn-lifecycle.log");
+}
+const MAX_LOG_BYTES = 256 * 1024;
+const KEEP_ROTATIONS = 2;
+/** Shift turn-lifecycle.log -> .1 -> .2 once the active file passes the cap. */
+function rotateIfNeeded(path) {
+    try {
+        if (!statSync(path).isFile() || statSync(path).size < MAX_LOG_BYTES)
+            return;
+        for (let i = KEEP_ROTATIONS; i >= 1; i--) {
+            const from = i === 1 ? path : `${path}.${i - 1}`;
+            const to = `${path}.${i}`;
+            try {
+                renameSync(from, to);
+            }
+            catch {
+                /* absent source — fine */
+            }
+        }
+    }
+    catch {
+        /* rotation is best-effort */
+    }
+}
+/**
+ * Append one sanitized lifecycle record. Fail-soft — a logging failure must
+ * never break the turn. `errorClass` is a caller-mapped category, never a
+ * raw error message.
+ */
+export function logTurnLifecycle(ev) {
+    try {
+        // Hermetic under `node --test`: never touch the real home dir unless a test
+        // explicitly overrode it (same rule as diagnostics.ts, which prevents the
+        // suite's exit from depending on the CI filesystem).
+        if (process.env.NODE_TEST_CONTEXT && homeOverride === null)
+            return;
+        const line = {
+            ts: new Date().toISOString(),
+            event: ev.kind,
+            ...(ev.sessionId ? { sessionId: ev.sessionId } : {}),
+            ...(ev.turnIndex !== undefined ? { turnIndex: ev.turnIndex } : {}),
+            ...(ev.kind === "turn_end" && ev.stopReason !== undefined ? { stopReason: ev.stopReason } : {}),
+            ...(ev.kind === "turn_end" && ev.elapsedMs !== undefined ? { elapsedMs: ev.elapsedMs } : {}),
+        };
+        const path = turnLogPath();
+        mkdirSync(dirname(path), { recursive: true });
+        rotateIfNeeded(path);
+        appendFileSync(path, JSON.stringify(line) + "\n", "utf8");
+    }
+    catch {
+        /* logging must never throw into the editor */
+    }
+}
+/** List existing lifecycle log files (active + rotations), for a report. */
+export function listTurnLogFiles() {
+    try {
+        const dir = turnLogDir();
+        return readdirSync(dir)
+            .filter((f) => f.startsWith("turn-lifecycle.log"))
+            .sort()
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=turnLog.js.map

package/dist/goHeadless.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `yagni go --headless …` — the scriptable front door to the /go pipeline.
+ *
+ * The pipeline itself lives in the bundled extension (pi-extension-yagni's
+ * `pipeline/headlessGo.ts`). The launcher keeps its usual job: resolve the
+ * active environment's credentials, build the hermetic child environment, point
+ * the pipeline's child resolver at the pinned pi binary, and hand over. As
+ * everywhere else in this package, the extension is reached by FILE PATH and
+ * called through a locally-declared structural type — the two packages stay
+ * independent, and the CLI never takes a build-time dependency on a private
+ * workspace package.
+ *
+ * The mission sandbox invokes exactly this command (`--ticket-file`,
+ * `--plan-file`, optional `--memo-file`, `--run-id`, `--json`), so what Jack
+ * runs locally and what the fleet executes are the same binary and the same
+ * pipeline.
+ */
+/** Mirrors HEADLESS_GO_EXIT in the extension; duplicated to keep the packages independent. */
+export declare const GO_EXIT: {
+    readonly verified: 0;
+    readonly unverified: 1;
+    readonly usage: 2;
+};
+/** The structural slice of the extension's headless entry that we call. */
+interface HeadlessGoModule {
+    runHeadlessGo: (argv: string[], deps: {
+        cwd?: string;
+        env?: NodeJS.ProcessEnv;
+        childEnv?: NodeJS.ProcessEnv;
+    }) => Promise<{
+        exitCode: number;
+    }>;
+}
+export interface GoCommandDeps {
+    /** Import seam for the bundled headless entry (tests inject a fake). */
+    loadHeadless?: () => Promise<HeadlessGoModule>;
+    /** Credential seam; defaults to the active profile on disk. */
+    loadCredentials?: () => Promise<{
+        token?: string;
+        baseUrl: string;
+        name: string;
+        expiresAt?: string;
+        workspaceId?: string;
+    }>;
+    /** Resolve pi's CLI entry (the binary every stage child is spawned with). */
+    piCliPath?: () => string;
+    writeErr?: (line: string) => void;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}
+/**
+ * Build the environment every pipeline stage child inherits: the proxy
+ * credentials (so the `yagni` provider and the grounding tools reach the
+ * backend), the hermetic pi agent dir, and pi's quiet flags. `YAGNI_CALLER` /
+ * `YAGNI_RUN_ID` are NOT set here — the pipeline stamps a per-stage caller onto
+ * every child, and the run id rides the `--run-id` flag.
+ */
+export declare function buildHeadlessChildEnv(opts: {
+    baseEnv: NodeJS.ProcessEnv;
+    token: string;
+    baseUrl: string;
+    profileName: string;
+    expiresAt?: string;
+    workspaceId?: string;
+    cliVersion?: string;
+    sessionId?: string;
+}): NodeJS.ProcessEnv;
+/**
+ * Run `yagni go`. Returns the process exit code: 0 only on a verified
+ * candidate, 1 on any other pipeline outcome, 2 on a usage or credential
+ * problem. Never throws.
+ */
+export declare function goCommand(args: string[], deps?: GoCommandDeps, cliVersion?: string): Promise<number>;
+export {};
+//# sourceMappingURL=goHeadless.d.ts.map