@yagni-app/code-staging 0.0.0 → 0.1.0-staging.997.1

package/dist/extension/pipeline/runner.js

@@ -0,0 +1,298 @@
+/**
+ * THIN, IMPURE per-stage spawn-runner — lifted almost verbatim from the pi
+ * subagent example's `runSingleAgent` (index.ts L267-429).
+ *
+ * It writes the grounded persona body to a 0600 temp file, builds the grounded
+ * child argv, spawns ONE pi child, line-buffers the stdout NDJSON, delegates all
+ * parsing to `events.ts`, applies `PER_TASK_OUTPUT_CAP`, wires abort
+ * (SIGTERM then SIGKILL after 5s if the child has not really exited), and cleans
+ * up the temp file.
+ *
+ * v1 spawns `pi` directly (NOT the `yagni-code` launcher) and re-injects
+ * `-e <self> --provider yagni`, inheriting the parent's env (token / base URL /
+ * agent dir). This avoids a yagni-code-cli ↔ pi-extension-yagni circular
+ * dependency — see the blueprint risks.
+ *
+ * ALL impurity sits behind injectable seams (`spawn`, `writePrompt`,
+ * `resolveChild`) so the runner is unit-tested with a fake spawn emitting canned
+ * NDJSON — no real process, no model, no network. The live end-to-end run is
+ * Jack dogfood, not CI.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { finalOutputFrom, foldEvent, newEventAccumulator } from "./events.js";
+import { buildStageInvocation, groundedChildArgv } from "./invocation.js";
+import { personaBody } from "./personas.js";
+import { PER_TASK_OUTPUT_CAP, } from "./types.js";
+/**
+ * Default per-line stdout ceiling (16 MiB). A legitimate NDJSON event — even one
+ * carrying a large tool payload — is far below this; a line beyond it is a
+ * runaway/garbage line, dropped rather than accumulated. Keeps the stdout reader
+ * O(n) and memory-bounded (a single ~GB line previously OOM-crashed `runStage`).
+ */
+export const DEFAULT_MAX_STDOUT_LINE_BYTES = 16 * 1024 * 1024;
+/** Default: write the persona body to a private (0600) temp file. */
+async function defaultWritePrompt(body) {
+    const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "yagni-pipeline-"));
+    const filePath = path.join(dir, "persona.md");
+    await fs.promises.writeFile(filePath, body, { encoding: "utf-8", mode: 0o600 });
+    const cleanup = () => {
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            fs.rmdirSync(dir);
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    return { filePath, cleanup };
+}
+/**
+ * Default child resolution: the parent process IS pi (so `process.argv[1]` is
+ * pi's cli), and our compiled extension entry sits one dir up from this module.
+ */
+function defaultResolveChild() {
+    const piCli = process.argv[1] ?? "pi";
+    const extensionPath = fileURLToPath(new URL("../index.js", import.meta.url));
+    return { piCli, extensionPath };
+}
+const EMPTY_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+/** Truncate to PER_TASK_OUTPUT_CAP bytes, never exceeding the cap. */
+function capOutput(output) {
+    if (Buffer.byteLength(output, "utf8") <= PER_TASK_OUTPUT_CAP)
+        return output;
+    let truncated = output.slice(0, PER_TASK_OUTPUT_CAP);
+    while (Buffer.byteLength(truncated, "utf8") > PER_TASK_OUTPUT_CAP) {
+        truncated = truncated.slice(0, -1);
+    }
+    return truncated;
+}
+/**
+ * Run one grounded child stage and reduce its NDJSON stream into a StageResult.
+ * `ctx.lens` (when set, for a fanned-out review) selects the lens clause in the
+ * persona body and is threaded through the invocation builder.
+ */
+export async function runStage(stage, ctx, deps) {
+    const spawnFn = deps.spawn ?? nodeSpawn;
+    const writePrompt = deps.writePrompt ?? defaultWritePrompt;
+    const resolveChild = deps.resolveChild ?? defaultResolveChild;
+    const personaStage = ctx.lens ? { ...stage, lens: ctx.lens } : stage;
+    // grounded defaults true; only the M6 blind eval lane passes grounded: false.
+    const body = (deps.personaBody ?? personaBody)(personaStage, { grounded: ctx.grounded !== false });
+    const { filePath, cleanup } = await writePrompt(body);
+    const result = {
+        stageId: stage.id,
+        agent: stage.agent,
+        exitCode: 0,
+        finalOutput: "",
+        usage: { ...EMPTY_USAGE },
+        stderr: "",
+        toolCalls: 0,
+        toolErrors: 0,
+    };
+    try {
+        const passthrough = buildStageInvocation(stage, {
+            ticket: ctx.ticket,
+            previous: ctx.previous,
+            promptFilePath: filePath,
+            lens: ctx.lens,
+        });
+        const { piCli, extensionPath } = resolveChild();
+        const argv = groundedChildArgv(passthrough, { piCli, extensionPath });
+        // Fold events into a fixed-size accumulator as they stream — never retain
+        // the full array (that OOMs on a verbose stage; YAG-317 follow-up).
+        const acc = newEventAccumulator();
+        let eventCount = 0;
+        let stderr = "";
+        let wasAborted = false;
+        const maxLineBytes = deps.maxLineBytes ?? DEFAULT_MAX_STDOUT_LINE_BYTES;
+        let overlongLinesDropped = 0;
+        // Env-gated diagnostic (no-op unless YAGNI_PIPELINE_DEBUG_DIR set). Captures
+        // per-stage stream metrics — total bytes, max single NDJSON line, event count,
+        // interim heap — plus the full final output. Used to characterise the plan
+        // `length` truncation and the implement-stage OOM. Safe to leave in.
+        const DEBUG_DIR = process.env.YAGNI_PIPELINE_DEBUG_DIR;
+        const dbgLabel = ctx.lens ? `${stage.id}-${ctx.lens}` : stage.id;
+        let dbgTotalBytes = 0, dbgMaxLineBytes = 0, dbgLineCount = 0, dbgLastLogBytes = 0;
+        const dbgLog = (note) => {
+            if (!DEBUG_DIR)
+                return;
+            try {
+                fs.mkdirSync(DEBUG_DIR, { recursive: true });
+                const m = process.memoryUsage();
+                fs.appendFileSync(path.join(DEBUG_DIR, `${dbgLabel}.stream.log`), `${new Date().toISOString()} ${note} bytes=${dbgTotalBytes} maxLineBytes=${dbgMaxLineBytes} lines=${dbgLineCount} events=${eventCount} heapUsedMB=${Math.round(m.heapUsed / 1048576)} rssMB=${Math.round(m.rss / 1048576)}\n`);
+            }
+            catch { /* ignore */ }
+        };
+        const exitCode = await new Promise((resolve) => {
+            const proc = spawnFn(process.execPath, argv, {
+                cwd: deps.cwd,
+                ...(deps.env ? { env: deps.env } : {}),
+                shell: false,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            let buffer = "";
+            // `overlong` = we are mid-way through a line that already blew the cap; we
+            // discard incoming bytes until its terminating newline, then drop the line.
+            let overlong = false;
+            const processLine = (line) => {
+                if (DEBUG_DIR) {
+                    const b = Buffer.byteLength(line, "utf8");
+                    if (b > dbgMaxLineBytes)
+                        dbgMaxLineBytes = b;
+                    dbgLineCount++;
+                }
+                if (!line.trim())
+                    return;
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                foldEvent(acc, event);
+                eventCount += 1;
+                deps.onEvent?.(event);
+            };
+            // Track real process exit explicitly. `ChildProcess.killed` is set the
+            // instant a signal is *sent*, not when the process exits — so it cannot
+            // gate the SIGKILL escalation (it is already true after SIGTERM). This
+            // flag flips only on the real `close`/`error`, so a child that ignores
+            // SIGTERM still gets force-killed after the grace window.
+            const signal = deps.signal;
+            let closed = false;
+            let killTimer;
+            const onAbort = () => {
+                wasAborted = true;
+                // pid guard: kill() on a child whose spawn FAILED resolves to pid 0 —
+                // the whole process group — and would take the parent down with it.
+                if (proc.pid)
+                    proc.kill("SIGTERM");
+                killTimer = setTimeout(() => {
+                    if (!closed && proc.pid)
+                        proc.kill("SIGKILL");
+                }, 5000);
+                killTimer.unref?.();
+            };
+            const finish = (code) => {
+                closed = true;
+                if (killTimer)
+                    clearTimeout(killTimer);
+                // Detach the abort listener on normal completion so it does not
+                // accumulate on the shared, long-lived pipeline signal across stages.
+                if (signal)
+                    signal.removeEventListener("abort", onAbort);
+                resolve(code);
+            };
+            proc.stdout?.on("data", (data) => {
+                const s = data.toString();
+                if (DEBUG_DIR) {
+                    dbgTotalBytes += Buffer.byteLength(s, "utf8");
+                    if (dbgTotalBytes - dbgLastLogBytes > 20_000_000) {
+                        dbgLastLogBytes = dbgTotalBytes;
+                        dbgLog("stream");
+                    }
+                }
+                // Incremental newline scan — never re-split a growing buffer (that was
+                // O(n²) and OOM-crashed on a runaway single line). `buffer` only ever
+                // holds the current *partial* line, and is capped at maxLineBytes: an
+                // over-cap line is dropped, not accumulated.
+                let start = 0;
+                for (;;) {
+                    const nl = s.indexOf("\n", start);
+                    if (nl === -1) {
+                        if (!overlong) {
+                            buffer += s.slice(start);
+                            if (buffer.length > maxLineBytes) {
+                                overlong = true;
+                                buffer = "";
+                            }
+                        }
+                        break;
+                    }
+                    const seg = s.slice(start, nl);
+                    start = nl + 1;
+                    if (overlong) {
+                        overlong = false;
+                        overlongLinesDropped += 1;
+                        continue;
+                    }
+                    const line = buffer + seg;
+                    buffer = "";
+                    if (line.length > maxLineBytes) {
+                        overlongLinesDropped += 1;
+                        continue;
+                    }
+                    processLine(line);
+                }
+            });
+            proc.stderr?.on("data", (data) => {
+                stderr += data.toString();
+            });
+            proc.on("close", (code) => {
+                if (overlong) {
+                    overlongLinesDropped += 1;
+                    overlong = false;
+                    buffer = "";
+                }
+                else if (buffer.trim())
+                    processLine(buffer);
+                finish(code ?? 0);
+            });
+            proc.on("error", () => finish(1));
+            if (signal) {
+                if (signal.aborted)
+                    onAbort();
+                else
+                    signal.addEventListener("abort", onAbort);
+            }
+        });
+        result.exitCode = exitCode;
+        result.stderr = stderr;
+        result.finalOutput = capOutput(finalOutputFrom(acc));
+        result.usage = acc.usage;
+        // R3-a: tap tool-result counts into stage health. The orchestrator turns
+        // this ratio into a write-stage failure when most edits errored, so a
+        // clean-looking summary can't mask a silent partial implement.
+        result.toolCalls = acc.toolCalls;
+        result.toolErrors = acc.toolErrors;
+        if (acc.stopReason)
+            result.stopReason = acc.stopReason;
+        if (acc.errorMessage)
+            result.errorMessage = acc.errorMessage;
+        if (wasAborted)
+            result.stopReason = "aborted";
+        if (overlongLinesDropped > 0)
+            result.overlongLinesDropped = overlongLinesDropped;
+        if (DEBUG_DIR) {
+            try {
+                fs.mkdirSync(DEBUG_DIR, { recursive: true });
+                const finalOut = finalOutputFrom(acc);
+                fs.writeFileSync(path.join(DEBUG_DIR, `${dbgLabel}.summary.json`), JSON.stringify({
+                    stageId: stage.id, lens: ctx.lens, exitCode,
+                    stopReason: result.stopReason, usage: result.usage,
+                    events_count: eventCount, total_stream_bytes: dbgTotalBytes,
+                    max_line_bytes: dbgMaxLineBytes, line_count: dbgLineCount,
+                    final_output_bytes: Buffer.byteLength(finalOut, "utf8"),
+                    final_output: finalOut,
+                }, null, 2));
+                dbgLog("stage_end");
+            }
+            catch { /* ignore */ }
+        }
+        return result;
+    }
+    finally {
+        cleanup();
+    }
+}
+//# sourceMappingURL=runner.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * Conservative secret redaction for captured command output before it enters
+ * findings, handoffs, or run records (invariant §0.9). The verify gate runs
+ * repo-defined typecheck/test commands whose output can echo connection
+ * strings, tokens, or key material (a failing DB test prints its DATABASE_URL,
+ * a debug line dumps process.env); that text flows into critical findings, the
+ * /go handoff, and the backend run record, so it is scrubbed FIRST.
+ *
+ * This mirrors the backend's `yagniCode/scrubSecrets.ts` pattern set verbatim
+ * (the "existing scrubSecrets path" of spec §3d) — the pipeline cannot import
+ * across packages, so the patterns are duplicated here; keep the two in sync.
+ * Over-redacts rather than under-redacts; pure; never throws.
+ */
+export declare function scrubSecrets(text: string): string;
+//# sourceMappingURL=scrubSecrets.d.ts.map

package/dist/extension/pipeline/scrubSecrets.js

@@ -0,0 +1,32 @@
+/**
+ * Conservative secret redaction for captured command output before it enters
+ * findings, handoffs, or run records (invariant §0.9). The verify gate runs
+ * repo-defined typecheck/test commands whose output can echo connection
+ * strings, tokens, or key material (a failing DB test prints its DATABASE_URL,
+ * a debug line dumps process.env); that text flows into critical findings, the
+ * /go handoff, and the backend run record, so it is scrubbed FIRST.
+ *
+ * This mirrors the backend's `yagniCode/scrubSecrets.ts` pattern set verbatim
+ * (the "existing scrubSecrets path" of spec §3d) — the pipeline cannot import
+ * across packages, so the patterns are duplicated here; keep the two in sync.
+ * Over-redacts rather than under-redacts; pure; never throws.
+ */
+const PATTERNS = [
+    // Credentials embedded in connection-string URLs: scheme://user:password@host
+    // (the password segment has no secret-named key and is usually too short for the
+    // base64 rule, so it would otherwise survive — common in config/env diffs).
+    [/\b([a-z][a-z0-9+.\-]*:\/\/[^\s:@/]+):[^\s:@/]+@/gi, "$1:[REDACTED]@"],
+    // Provider key prefixes (OpenAI, GitHub, Slack, Stripe, AWS access key id, etc.)
+    [/\b(sk-[A-Za-z0-9]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_\-]{20,})\b/g, "[REDACTED]"],
+    // key = "value" / key: value for secret-named keys
+    [/\b([A-Za-z0-9_]*(?:secret|password|passwd|api[_-]?key|token|private[_-]?key|access[_-]?key)[A-Za-z0-9_]*)\b(\s*[:=]\s*)("[^"]+"|'[^']+'|`[^`]+`|[^\s"']+)/gi, "$1$2[REDACTED]"],
+    // Long base64-ish blobs (likely keys/JWTs)
+    [/\b[A-Za-z0-9+/]{40,}={0,2}\b/g, "[REDACTED]"],
+];
+export function scrubSecrets(text) {
+    let out = text;
+    for (const [re, repl] of PATTERNS)
+        out = out.replace(re, repl);
+    return out;
+}
+//# sourceMappingURL=scrubSecrets.js.map

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

@@ -0,0 +1,51 @@
+/**
+ * The declarative v1 stage list as DATA (spec §3 + §7.4) plus a selector.
+ *
+ * This is control-flow-as-data: map(standard) → plan(peak) →
+ * implement(standard) → review(peak, fanned over 3 lenses) → fix(standard).
+ * Routing follows the judgment, not the typing: the strongest `peak` tier on the
+ * steps that decide-what / catch-wrong (Plan, Review); the `standard` tier on the
+ * execution steps (Map, Implement, Fix). The cheaper `efficient` tier stays a
+ * selectable catalog tier but is intentionally not wired into a stage here.
+ *
+ * Peak on judgment is affordable precisely BECAUSE the judgment stages are short
+ * (YAG-380): plan plus the three review lenses is roughly 21c per round on
+ * advanced and 51c on peak, while the token-heavy stages that dominate a run
+ * stay down-tier. Quality of the output is the product, so the strongest model
+ * goes where being wrong is most expensive, not where the tokens are.
+ *
+ * `selectStages(lane)` returns the full list for v1 and is the seam where v2
+ * complexity-lanes plug in without a rewrite.
+ */
+import type { PipelineStage, ReviewLens } from "./types.js";
+/** The three adversarial review angles, fanned out per round (spec §3). */
+export declare const REVIEW_LENSES: ReviewLens[];
+/**
+ * The review lenses the round cannot proceed without (R2 partial-failure
+ * tolerance). When ONE of these is the lens that fails, the round fails honestly
+ * rather than proceeding on a partial review; a non-required lens failing only
+ * degrades the round (the survivors carry it, recorded as `degradedLenses`).
+ * Correctness is load-bearing: a change that might be wrong must never sail
+ * through just because the cheaper lenses passed. Tunable, widen to make another
+ * lens load-bearing.
+ */
+export declare const REQUIRED_LENSES: ReviewLens[];
+export declare const PIPELINE_V1: PipelineStage[];
+/** The single review stage the orchestrator fans out across REVIEW_LENSES. */
+export declare function reviewStage(): PipelineStage;
+/**
+ * Select the stage list for a lane. v1 has exactly one lane ('full'); this is
+ * the identity selector and the extension point for v2 complexity-lanes.
+ */
+export declare function selectStages(_lane?: "full"): PipelineStage[];
+/**
+ * The findings-contract re-ask stage (spec §3e): when a HEALTHY lens returns
+ * non-empty prose with no ```findings fence, the orchestrator re-invokes it
+ * ONCE on the cheap `efficient` tier with this minimal prompt — a pure
+ * format-recovery pass, not a second review. The lens's original output rides
+ * in as `{previous}`. Tools are the minimal REAL list `["read"]`:
+ * `buildStageInvocation` joins `--tools` with a comma, so an empty array would
+ * emit the broken `--tools ""`.
+ */
+export declare function reaskStage(review: PipelineStage): PipelineStage;
+//# sourceMappingURL=stages.d.ts.map

package/dist/extension/pipeline/stages.js

@@ -0,0 +1,113 @@
+/**
+ * The declarative v1 stage list as DATA (spec §3 + §7.4) plus a selector.
+ *
+ * This is control-flow-as-data: map(standard) → plan(peak) →
+ * implement(standard) → review(peak, fanned over 3 lenses) → fix(standard).
+ * Routing follows the judgment, not the typing: the strongest `peak` tier on the
+ * steps that decide-what / catch-wrong (Plan, Review); the `standard` tier on the
+ * execution steps (Map, Implement, Fix). The cheaper `efficient` tier stays a
+ * selectable catalog tier but is intentionally not wired into a stage here.
+ *
+ * Peak on judgment is affordable precisely BECAUSE the judgment stages are short
+ * (YAG-380): plan plus the three review lenses is roughly 21c per round on
+ * advanced and 51c on peak, while the token-heavy stages that dominate a run
+ * stay down-tier. Quality of the output is the product, so the strongest model
+ * goes where being wrong is most expensive, not where the tokens are.
+ *
+ * `selectStages(lane)` returns the full list for v1 and is the seam where v2
+ * complexity-lanes plug in without a rewrite.
+ */
+/** The three adversarial review angles, fanned out per round (spec §3). */
+export const REVIEW_LENSES = ["correctness", "business_fit", "does_it_hold"];
+/**
+ * The review lenses the round cannot proceed without (R2 partial-failure
+ * tolerance). When ONE of these is the lens that fails, the round fails honestly
+ * rather than proceeding on a partial review; a non-required lens failing only
+ * degrades the round (the survivors carry it, recorded as `degradedLenses`).
+ * Correctness is load-bearing: a change that might be wrong must never sail
+ * through just because the cheaper lenses passed. Tunable, widen to make another
+ * lens load-bearing.
+ */
+export const REQUIRED_LENSES = ["correctness"];
+/** Read-only recon + grounding tools shared by scout and reviewer. */
+const READ_TOOLS = ["read", "grep", "find", "ls", "bash"];
+/** Full write tools for the worker stages. */
+const WRITE_TOOLS = ["read", "write", "edit", "bash", "grep", "find", "ls"];
+export const PIPELINE_V1 = [
+    {
+        id: "map",
+        agent: "scout",
+        model: "standard",
+        tools: [...READ_TOOLS, "ask_yagni"],
+        taskTemplate: "Map the codebase for this ticket and return a compressed context brief: " +
+            "where the relevant code lives, the conventions in play, and anything " +
+            "ask_yagni surfaces about how this company wants this done.\n\nTicket: {ticket}",
+    },
+    {
+        id: "plan",
+        agent: "planner",
+        model: "peak",
+        // Read-only recon (read/grep/find/ls) so the planner can actually navigate
+        // instead of flailing on a single `read` and ending mid-exploration; NO bash
+        // (it must not build/run), and ask_yagni for grounding.
+        tools: ["read", "grep", "find", "ls", "ask_yagni"],
+        taskTemplate: "Turn the ticket and the repo map into an ordered, grounded implementation " +
+            "plan. Call ask_yagni before inferring a convention.\n\n" +
+            "Ticket: {ticket}\n\nRepo map:\n{previous}",
+    },
+    {
+        id: "implement",
+        agent: "worker",
+        model: "standard",
+        tools: [...WRITE_TOOLS, "ask_yagni", "record_decision"],
+        taskTemplate: "Implement the plan. Write the code against it, and call record_decision " +
+            "for any product-intent call you are forced to make.\n\nPlan:\n{previous}",
+    },
+    {
+        id: "review",
+        agent: "reviewer",
+        model: "peak",
+        tools: [...READ_TOOLS, "ask_yagni", "review_business_match"],
+        taskTemplate: "Review the implementation adversarially. Diff/summary of the change:\n{previous}",
+    },
+    {
+        id: "fix",
+        agent: "worker",
+        model: "standard",
+        tools: [...WRITE_TOOLS, "ask_yagni"],
+        taskTemplate: "Reconcile ONLY the blocking review findings against the plan. Leave " +
+            "non-blocking findings alone.\n\nBlocking findings:\n{previous}",
+    },
+];
+/** The single review stage the orchestrator fans out across REVIEW_LENSES. */
+export function reviewStage() {
+    const stage = PIPELINE_V1.find((s) => s.id === "review");
+    if (!stage)
+        throw new Error("PIPELINE_V1 is missing the review stage");
+    return stage;
+}
+/**
+ * Select the stage list for a lane. v1 has exactly one lane ('full'); this is
+ * the identity selector and the extension point for v2 complexity-lanes.
+ */
+export function selectStages(_lane = "full") {
+    return PIPELINE_V1;
+}
+/**
+ * The findings-contract re-ask stage (spec §3e): when a HEALTHY lens returns
+ * non-empty prose with no ```findings fence, the orchestrator re-invokes it
+ * ONCE on the cheap `efficient` tier with this minimal prompt — a pure
+ * format-recovery pass, not a second review. The lens's original output rides
+ * in as `{previous}`. Tools are the minimal REAL list `["read"]`:
+ * `buildStageInvocation` joins `--tools` with a comma, so an empty array would
+ * emit the broken `--tools ""`.
+ */
+export function reaskStage(review) {
+    return {
+        ...review,
+        model: "efficient",
+        tools: ["read"],
+        taskTemplate: "Re-emit ONLY the ```findings block for the review you just produced:\n{previous}",
+    };
+}
+//# sourceMappingURL=stages.js.map

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

@@ -0,0 +1,34 @@
+/**
+ * Pre-resolve the /go {ticket} slot to the REAL ticket before planning.
+ *
+ * `/go YAG-234` interpolates the raw arg string into every stage's {ticket}
+ * prompt slot, so without this the scout/planner plan blind on the literal
+ * "YAG-234". This fail-soft helper asks YAGNI to resolve the reference (POST
+ * /api/yagni-code/ask with a structured `ticketRef`), and on a hit returns a
+ * formatted brief carrying the VERBATIM ticket title + description (the
+ * acceptance criteria live inside the body) for the {ticket} slot.
+ *
+ * It is the read-path twin of {@link makeRunSession}'s fetch seam (baseUrl +
+ * injectable getToken + fetchImpl, via resilientFetch). The server resolves the
+ * ticket with a live, workspace-scoped connector READ, never an LLM call, so
+ * this never bills the ask compose path and never risks a model-rewritten body.
+ *
+ * FAIL-SOFT by contract: a non-identifier arg, an unconnected ticket connector,
+ * a miss, or any transport error returns null so /go passes the raw arg through
+ * unchanged (today's honest blind) rather than planning on a wrong body.
+ */
+export interface ResolveTicketBriefOptions {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+    /** Backoff seams threaded into resilientFetch so the retry path is instant under test. */
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+}
+/**
+ * Resolve a /go arg to a verbatim ticket brief, or null to keep the raw arg.
+ * Never throws; a non-identifier arg short-circuits before any network call.
+ */
+export declare function resolveTicketBrief(opts: ResolveTicketBriefOptions, rawArg: string): Promise<string | null>;
+//# sourceMappingURL=ticketResolution.d.ts.map

package/dist/extension/pipeline/ticketResolution.js

@@ -0,0 +1,75 @@
+/**
+ * Pre-resolve the /go {ticket} slot to the REAL ticket before planning.
+ *
+ * `/go YAG-234` interpolates the raw arg string into every stage's {ticket}
+ * prompt slot, so without this the scout/planner plan blind on the literal
+ * "YAG-234". This fail-soft helper asks YAGNI to resolve the reference (POST
+ * /api/yagni-code/ask with a structured `ticketRef`), and on a hit returns a
+ * formatted brief carrying the VERBATIM ticket title + description (the
+ * acceptance criteria live inside the body) for the {ticket} slot.
+ *
+ * It is the read-path twin of {@link makeRunSession}'s fetch seam (baseUrl +
+ * injectable getToken + fetchImpl, via resilientFetch). The server resolves the
+ * ticket with a live, workspace-scoped connector READ, never an LLM call, so
+ * this never bills the ask compose path and never risks a model-rewritten body.
+ *
+ * FAIL-SOFT by contract: a non-identifier arg, an unconnected ticket connector,
+ * a miss, or any transport error returns null so /go passes the raw arg through
+ * unchanged (today's honest blind) rather than planning on a wrong body.
+ */
+import { DEFAULT_FETCH_POLICY, resilientFetch } from "../resilientFetch.js";
+/** A Linear-style identifier ("YAG-234"); only these are worth a resolve attempt. */
+const IDENTIFIER_RE = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
+/** Format the resolved ticket into the verbatim brief injected into {ticket}. */
+function formatBrief(ticket) {
+    const header = `${ticket.identifier}: ${ticket.title}`;
+    const body = (ticket.description ?? "").trim();
+    return body.length > 0 ? `${header}\n\n${body}` : header;
+}
+/**
+ * Resolve a /go arg to a verbatim ticket brief, or null to keep the raw arg.
+ * Never throws; a non-identifier arg short-circuits before any network call.
+ */
+export async function resolveTicketBrief(opts, rawArg) {
+    const ref = rawArg.trim();
+    // Only an identifier-shaped arg is a ticket reference; free-text task
+    // descriptions pass straight through so /go uses them verbatim.
+    if (!IDENTIFIER_RE.test(ref))
+        return null;
+    let res;
+    try {
+        res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/ask`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${opts.getToken() ?? ""}`,
+            },
+            body: JSON.stringify({ ticketRef: ref }),
+        }, {
+            fetchImpl: opts.fetchImpl,
+            policy: DEFAULT_FETCH_POLICY,
+            ...(opts.signal ? { signal: opts.signal } : {}),
+            ...(opts.sleep ? { sleep: opts.sleep } : {}),
+            ...(opts.random ? { random: opts.random } : {}),
+        });
+    }
+    catch {
+        // Unreachable backend after retries: degrade to blind (raw arg).
+        return null;
+    }
+    if (!res.ok)
+        return null;
+    let data;
+    try {
+        data = (await res.json());
+    }
+    catch {
+        return null;
+    }
+    const ticket = data.ticket;
+    if (!ticket || typeof ticket.identifier !== "string" || typeof ticket.title !== "string") {
+        return null;
+    }
+    return formatBrief(ticket);
+}
+//# sourceMappingURL=ticketResolution.js.map