@yagni-app/code 0.1.0 → 0.2.0

package/dist/extension/index.js

@@ -0,0 +1,597 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Text } from "@earendil-works/pi-tui";
+import { DEFAULT_ADVISOR_LIMITS, formatAdvisorSubtotal, makeAdvisorState } from "./advisor.js";
+import { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
+import { registerBoostCommand } from "./boostCommand.js";
+import { makeAskYagniTool } from "./askYagniTool.js";
+import { makeReviewBusinessMatchTool } from "./reviewTool.js";
+import { makeRecordEngineeringContextTool } from "./recordContextTool.js";
+import { makeRecordDecisionTool } from "./recordDecisionTool.js";
+import { makeSuggestNextWorkTool } from "./nextWorkTool.js";
+import { BRAND_NAME, brandSystemPrompt, brandingDisabled, buildMastheadString, YAGNI_IDENTITY_DRIVER } from "./branding.js";
+import { appendClaudeRules, claudeRulesSection } from "./claudeRules.js";
+import { registerCostCommand } from "./costHud.js";
+import { isDebug } from "./diagnostics.js";
+import { droppedSessionRuns, sessionRunIds } from "./sessionRuns.js";
+import { codeStateHome } from "./stateHome.js";
+import { RerouteNotifier } from "./rerouteNotice.js";
+import { isFreshWorkspace, registerTeamSetupCommand, runInitPass as defaultRunInitPass } from "./initPass.js";
+import { isInitDone as defaultIsInitDone, markInitDone as defaultMarkInitDone } from "./initDone.js";
+import { fetchMcpServers as defaultFetchMcpServers, registerMcpCommand, registerMcpTools, } from "./mcpTools.js";
+import { registerGoCommand } from "./pipeline/goCommand.js";
+import { registerGoCompareCommand } from "./pipeline/goCompareCommand.js";
+import { DEFAULT_PERMISSION_POLICY, registerPermissionGate } from "./permission.js";
+import { registerSubagents } from "./subagents.js";
+import { registerTodos } from "./todos.js";
+import { registerDecisionCommands } from "./decisions.js";
+import { makeDecisionCapture } from "./decisionCapture.js";
+import { registerAmbientRecall } from "./recall.js";
+import { resilientFetch } from "./resilientFetch.js";
+import { installUncaughtExceptionMonitor } from "./crashReport.js";
+import { flushSpool as defaultFlushSpool } from "./spool.js";
+import { makeAuthedFetch, makeTokenProvider } from "./tokenProvider.js";
+import { attributionHeaders, fetchCatalog as defaultFetchCatalog, fetchContextBrief as defaultFetchContextBrief, getToken, getTokenExpiresAt as defaultGetTokenExpiresAt, getWorkspaceId as defaultGetWorkspaceId, isDriverCaller, resolveBaseUrl, tokenExpiryNotice, } from "./config.js";
+import { buildYagniProvider } from "./provider.js";
+import { registerChipEditor } from "./chipEditor.js";
+function isEvalMode(env = process.env) {
+    return env.YAGNI_CODE_EVAL_MODE === "1";
+}
+/**
+ * Build GET /api/yagni-code/spend's URL. Pure (no fetch), exported for tests.
+ *
+ * YAG-383: a `/go` run's dispatches bill under its OWN run id
+ * (`llm_usage.session_id` holds the run id, not the driver session id — see
+ * attributionHeaders in config.ts), so `sessionId=` alone misses every run
+ * this session launched. `runIds` (comma-separated) widens the same query to
+ * include them; empty is omitted entirely rather than sent as `runIds=`.
+ */
+export function buildSpendUrl(baseUrl, sessionId, runIds) {
+    const url = `${baseUrl}/api/yagni-code/spend?sessionId=${encodeURIComponent(sessionId)}`;
+    return runIds.length > 0 ? `${url}&runIds=${runIds.join(",")}` : url;
+}
+/**
+ * Build GET /api/yagni-code/spend's URL for ONE `/go` run's own spend
+ * (`?runId=`, the sibling of {@link buildSpendUrl}'s session-wide
+ * `?sessionId=&runIds=`). Pure (no fetch), exported for tests. The backend
+ * route treats `runId` and `sessionId` as aliases into the same lookup (see
+ * routes/yagniCode.ts's `/spend` handler), so this is just the more honest
+ * query param name for "this one run" rather than reusing `buildSpendUrl`
+ * with the run id awkwardly standing in for a session id.
+ */
+export function buildRunSpendUrl(baseUrl, runId) {
+    return `${baseUrl}/api/yagni-code/spend?runId=${encodeURIComponent(runId)}`;
+}
+/**
+ * Validate + narrow a `GET /api/yagni-code/spend` response body before
+ * trusting it as a {@link SpendResponse}. A network response is untyped at
+ * runtime, so this is the ONE shared guard both the session-wide `/cost`
+ * fetch and the per-run `/go` fetch rely on (drift-risk fix: they used to
+ * each carry their own copy of this same check). Pure, exported for tests.
+ * Returns null on anything that doesn't look like the real shape.
+ */
+export function parseSpendResponse(data) {
+    if (!data || typeof data !== "object")
+        return null;
+    const d = data;
+    if (typeof d.totalSellMillicents !== "number" || !Array.isArray(d.rows))
+        return null;
+    return d;
+}
+export async function registerYagni(pi, deps = {}) {
+    const baseUrl = deps.baseUrl ?? resolveBaseUrl();
+    const now = deps.now ?? (() => Date.now());
+    const fetchCatalog = deps.fetchCatalog ?? defaultFetchCatalog;
+    const env = deps.env ?? process.env;
+    const evalMode = isEvalMode(env);
+    // The refreshing TokenProvider replaces the old boot-time token snapshot:
+    // tools read the CURRENT token per call, a proactive unref'd timer rotates
+    // it near expiry, and `authedFetch` gives every tool's 401 path a single
+    // serialized refresh + one retry at THIS one seam (no per-tool copies).
+    const tokenProvider = deps.tokenProvider ??
+        makeTokenProvider({
+            baseUrl,
+            env: deps.env,
+            initialToken: deps.getToken ? deps.getToken() : getToken(deps.env),
+            initialExpiresAt: deps.getTokenExpiresAt
+                ? deps.getTokenExpiresAt()
+                : defaultGetTokenExpiresAt(deps.env),
+            fetchImpl: deps.fetchImpl,
+            now: deps.now,
+        });
+    const getTokenFn = () => tokenProvider.getToken();
+    const authedFetch = makeAuthedFetch(tokenProvider, deps.fetchImpl);
+    const flushSpoolFn = deps.flushSpool ?? defaultFlushSpool;
+    // Crash reporting (docs/superpowers/specs/2026-08-08-crash-reporting-design.md):
+    // observe a fatal crash in pi's process via the behavior-neutral
+    // uncaughtExceptionMonitor hook and deliver through a detached one-shot
+    // sender (a dying process cannot complete its own fetch). Sanitized, fail-
+    // soft, opt-out via YAGNI_DISABLE_CRASH_REPORTS=1; off in eval mode like
+    // every other external side effect.
+    if (!evalMode) {
+        installUncaughtExceptionMonitor({ baseUrl, getToken: getTokenFn, env: deps.env });
+    }
+    const catalog = await fetchCatalog({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+    // YAG-471: the driver's own completions carry attribution headers read from
+    // this process's env (YAGNI_SESSION_ID minted by the launcher; YAGNI_CALLER
+    // defaults to "driver" when unset, i.e. every session that is not a /go
+    // child, a subagent, or an advisor consult).
+    pi.registerProvider("yagni", buildYagniProvider(catalog, baseUrl, attributionHeaders(deps.env)));
+    const toolOpts = { baseUrl, getToken: getTokenFn, fetchImpl: authedFetch };
+    pi.registerTool(makeAskYagniTool(toolOpts));
+    // The peak-tier escalation for Balanced sessions (YAG-380). Registered
+    // UNCONDITIONALLY and gated at execute time on the live session model: pi's
+    // picker can switch the model after activation, so a registration-time tier
+    // check would both leave the tool live after switching away from Balanced and
+    // hide it forever from a session that switched TO Balanced. One state handle
+    // per session, shared with /advise so they draw on the same cap.
+    const advisorState = makeAdvisorState();
+    const askAdvisorTool = makeAskAdvisorTool({ state: advisorState });
+    pi.registerTool(askAdvisorTool);
+    // /advise runs the SAME tool, sharing the state handle, so a manual consult
+    // draws on the same cap rather than opening a side channel around it.
+    registerAdviseCommand(pi, askAdvisorTool);
+    // /boost — the sanctioned session-scoped escalation to Peak (spec §7,
+    // YAG-380 follow-on). Unlike /advise's per-call consult, this flips the
+    // DRIVER's own live model to peak until /boost off or the session ends.
+    // The returned handle threads isBoosted() into /cost below, the same way
+    // advisorState threads into advisorSubtotal.
+    const boostCommand = registerBoostCommand(pi, { env });
+    // The differentiated business-grounded tools (loop bricks): review a change
+    // for business fit, rank the next work by business priority, and record the
+    // engineering rationale back onto the work-item.
+    pi.registerTool(makeReviewBusinessMatchTool(toolOpts));
+    pi.registerTool(makeSuggestNextWorkTool(toolOpts));
+    if (!evalMode) {
+        pi.registerTool(makeRecordEngineeringContextTool(toolOpts));
+        // The capture half of the judgment loop: bank a product-intent decision so
+        // ask_yagni answers the same question next time instead of interrupting a human.
+        pi.registerTool(makeRecordDecisionTool(toolOpts));
+    }
+    // The visible checklist for multi-step work: the todo_write tool, its
+    // above-editor widget, and /todos. Branch-replayed, so forks and resumes
+    // show the list as it stood at that point.
+    registerTodos(pi);
+    // Image paste with [Image #N] chips: replaces the editor on
+    // session_start (TUI mode) so pasting a screenshot drops a chip instead of a
+    // temp path, and registers the input transform that turns chips into image
+    // attachments for the model. No-op outside TUI mode.
+    registerChipEditor(pi);
+    // The general subagent tool: delegate self-contained tasks (optionally in
+    // parallel) to fresh-context agents defined in .claude/agents / .pi/agents,
+    // riding the /go pipeline's child runner. /agents lists what's available.
+    registerSubagents(pi);
+    // Shared fetch timeout for the small, interactive display-path reads below
+    // (/cost's spend + headroom, and Task 8's per-run spend for /go's summary):
+    // 5s, not the 10s other boot/grounding fetches use, because the user is
+    // waiting on a prompt or a run's completion, not backgrounded work.
+    const COST_FETCH_TIMEOUT_MS = 5_000;
+    // The grounded multi-agent pipeline entry point: /go <ticket> runs
+    // map → plan → implement → review → fix, each child grounded by inheritance.
+    registerGoCommand(pi, {
+        // Task 8: /go's end-of-run summary prefers the server-priced per-stage
+        // breakdown for the ONE run that just finished (`?runId=`, aliasing the
+        // spend endpoint's `sessionId` param — see the backend route), over
+        // /cost's session-wide `?sessionId=&runIds=`. Fail-soft like every other
+        // fetch here: goCommand.ts's `resolveCostText` falls back to the local
+        // client estimate on a throw, a non-2xx, or a malformed body.
+        fetchRunSpend: async (runId, signal) => {
+            try {
+                const res = await resilientFetch(buildRunSpendUrl(baseUrl, runId), { method: "GET", headers: { authorization: `Bearer ${getTokenFn() ?? ""}` } }, { fetchImpl: authedFetch, signal, policy: { maxAttempts: 1, backoffBaseMs: 0, backoffMaxMs: 0, timeoutMs: COST_FETCH_TIMEOUT_MS, jitterRatio: 0 } });
+                if (!res.ok)
+                    return null;
+                return parseSpendResponse(await res.json());
+            }
+            catch {
+                return null;
+            }
+        },
+    });
+    // M6 eval (report-only): /go-compare runs a ticket grounded vs blind and reports
+    // the business-fit delta. Never wired to routing.
+    registerGoCompareCommand(pi);
+    // W4 judgment loop: the decisions surface (/decide + /decisions) and the
+    // bless-with-remember capture are the same product-intent write as the record
+    // tools, so both are gated together (skipped in eval mode).
+    const decisionClientOpts = { baseUrl, getToken: getTokenFn, fetchImpl: authedFetch };
+    const decisionCapture = evalMode ? undefined : makeDecisionCapture(decisionClientOpts);
+    if (!evalMode)
+        registerDecisionCommands(pi, decisionClientOpts);
+    // Workspace MCP servers (YAG-446): register one tool per enabled server
+    // tool, executing through the backend proxy, plus the /mcp listing
+    // command. Fail-soft fetch (older backend / un-rescoped token → no MCP
+    // tools); skipped in eval mode like the other external-side-effect tools.
+    const fetchMcp = deps.fetchMcpServers ?? defaultFetchMcpServers;
+    const mcpServers = evalMode
+        ? []
+        : await fetchMcp({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+    const { mutatingToolNames: mcpMutatingTools } = registerMcpTools(pi, mcpServers, { baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+    registerMcpCommand(pi, mcpServers, { baseUrl });
+    // P3 + W4: interactive permission tiers + plan mode via /mode, now with a
+    // session bless store (three-way review-mode select) and a capture hook that
+    // drafts a decision on "don't ask again". Default auto, so still additive.
+    // Mutating MCP tools join write/edit/bash in the gate policy: plan mode
+    // holds them, review mode confirms them.
+    registerPermissionGate(pi, {
+        ...(mcpMutatingTools.length > 0
+            ? {
+                policy: {
+                    planBlockTools: [
+                        ...DEFAULT_PERMISSION_POLICY.planBlockTools,
+                        ...mcpMutatingTools,
+                    ],
+                    reviewConfirmTools: [
+                        ...DEFAULT_PERMISSION_POLICY.reviewConfirmTools,
+                        ...mcpMutatingTools,
+                    ],
+                },
+            }
+            : {}),
+        onBlessRemember: decisionCapture
+            ? (ctx, info) => decisionCapture.captureFromBless(ctx, info)
+            : undefined,
+    });
+    // P2/YAG-383: /cost prefers the server-authoritative session spend (covers
+    // subagents and advisor consults directly, since they bill under this same
+    // session id — PLUS every /go run this session launched, widened in via
+    // runIds because a run's dispatches bill under its OWN run id instead; see
+    // sessionRuns.ts and buildSpendUrl below), plus credit headroom. Both
+    // fetches are fail-soft: a down backend still leaves /cost showing the
+    // local, driver-only accumulator.
+    const yagniSessionId = env.YAGNI_SESSION_ID;
+    // COST_FETCH_TIMEOUT_MS (declared above, shared with /go's fetchRunSpend):
+    // the two fetches below now run concurrently (see costHud.ts's Promise.all)
+    // rather than serially, so it bounds worst-case /cost silence to 5s, not 10-20s.
+    registerCostCommand(pi, {
+        // Advisor consults run in a child process, so they never reach /cost's
+        // turn_end accumulator. Thread the subtotal in explicitly for the local
+        // fallback line; the server-authoritative line already counts advisor
+        // spend as an ordinary caller row.
+        advisorSubtotal: () => formatAdvisorSubtotal(advisorState.read(), DEFAULT_ADVISOR_LIMITS),
+        // YAG-380 follow-on: a boosted session that only chats never produces a
+        // server-side boosted row (see boostCommand.ts's KNOWN-asymmetry
+        // docblock), so /cost needs the live client-side toggle on top of
+        // whatever the server rows show.
+        isBoosted: () => boostCommand.isBoosted(),
+        fetchHeadroom: async (signal) => {
+            try {
+                const res = await resilientFetch(`${baseUrl}/api/yagni-code/credits`, { method: "GET", headers: { authorization: `Bearer ${getTokenFn() ?? ""}` } }, { fetchImpl: authedFetch, signal, policy: { maxAttempts: 1, backoffBaseMs: 0, backoffMaxMs: 0, timeoutMs: COST_FETCH_TIMEOUT_MS, jitterRatio: 0 } });
+                if (!res.ok)
+                    return null;
+                const data = (await res.json());
+                if (typeof data.remaining !== "number")
+                    return null;
+                return { remaining: data.remaining, unit: typeof data.unit === "string" ? data.unit : "credits" };
+            }
+            catch {
+                return null;
+            }
+        },
+        // Skip the fetch entirely when there is no session id to ask about (e.g.
+        // a harness that never set YAGNI_SESSION_ID) rather than issuing a request
+        // guaranteed to 400.
+        fetchSpend: yagniSessionId
+            ? async (signal) => {
+                try {
+                    const res = await resilientFetch(buildSpendUrl(baseUrl, yagniSessionId, sessionRunIds()), { method: "GET", headers: { authorization: `Bearer ${getTokenFn() ?? ""}` } }, { fetchImpl: authedFetch, signal, policy: { maxAttempts: 1, backoffBaseMs: 0, backoffMaxMs: 0, timeoutMs: COST_FETCH_TIMEOUT_MS, jitterRatio: 0 } });
+                    if (!res.ok)
+                        return null;
+                    return parseSpendResponse(await res.json());
+                }
+                catch {
+                    return null;
+                }
+            }
+            : undefined,
+        // Quiet debug signal only (never user-facing): a session-scoped log under
+        // YAGNI_DEBUG, mirroring diagnostics.ts's layer-A verbose mode. No-op when
+        // YAGNI_DEBUG is unset, so a healthy session never touches disk for this.
+        onDivergence: (driverServerUsd, localUsd) => {
+            if (!isDebug(env))
+                return;
+            try {
+                const path = join(codeStateHome(null, env), "logs", "cost-divergence.log");
+                mkdirSync(dirname(path), { recursive: true });
+                const line = { ts: new Date().toISOString(), driverServerUsd, localUsd };
+                appendFileSync(path, JSON.stringify(line) + "\n", "utf8");
+            }
+            catch {
+                /* a diagnostic must never break /cost */
+            }
+        },
+        // Carry-over (/cost re-review): surfaces sessionRuns.ts's dropped-run-id
+        // count as costHud's "Excludes N earlier /go runs." note.
+        droppedSessionRuns,
+    });
+    // YAG-471: surface the backend's vision reroute header as a quiet notice
+    // (see rerouteNotice.ts for the event/header contract). One notifier per
+    // session dedupes on the from->to pair so a long session does not repeat
+    // itself on every image turn.
+    const rerouteNotifier = new RerouteNotifier();
+    pi.on("after_provider_response", (event, ctx) => {
+        try {
+            if (!ctx.hasUI)
+                return;
+            const message = rerouteNotifier.observe(event.headers);
+            if (message)
+                ctx.ui.notify(message, "info");
+        }
+        catch {
+            // A notice must never break a turn.
+        }
+    });
+    // /exit — alias for pi's built-in /quit. Delegates to ctx.shutdown() which
+    // performs graceful TUI teardown (restores terminal state, emits
+    // session_shutdown for other extensions, disposes the runtime host, prints
+    // the resume hint) before calling process.exit(0). When idle (!isStreaming),
+    // pi's shutdownHandler calls this.shutdown() immediately; when streaming, it
+    // defers to agent_end — both correct.
+    pi.registerCommand("exit", {
+        description: "Exit YAGNI Code (alias for /quit).",
+        handler: async (_args, ctx) => {
+            ctx.shutdown();
+        },
+    });
+    // Boot grounded: fetch the company brief once (best-effort — a failure here
+    // must never block the agent), then inject it into the system prompt so the
+    // very first turn already knows how this company and codebase work.
+    const fetchBrief = deps.fetchContextBrief ?? defaultFetchContextBrief;
+    let contextBrief;
+    let briefResult = null;
+    if (!evalMode) {
+        try {
+            briefResult = await fetchBrief({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+            contextBrief = briefResult?.brief?.trim() ? briefResult.brief : undefined;
+        }
+        catch {
+            briefResult = null;
+            contextBrief = undefined;
+        }
+    }
+    // M1 ambient judgment recall: after a `read`, append the recorded judgment for
+    // that path to the tool result (result modification is supported on pi's
+    // `tool_result` event — verified against 0.80.2). No-op when the corpus is thin
+    // (<3 active decisions from /context.counts) or in eval mode.
+    registerAmbientRecall(pi, {
+        baseUrl,
+        getToken: getTokenFn,
+        fetchImpl: authedFetch,
+        decisionsCount: briefResult?.counts?.decisions ?? 0,
+        evalMode,
+    });
+    // ADR-0033: the Team-drafting flow is an explicit command, never a first-run
+    // ceremony. /setup-team drafts the Engineering Team + engineering brief from
+    // the repo and banks the brief as one decision on approval.
+    registerTeamSetupCommand(pi, { baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+    // Onramp Door B (spec §5B/§7, as amended by ADR-0033): on a FRESH workspace
+    // (empty/thin grounding corpus), the first run shows a short welcome + one
+    // next-work offer, with free text first-class — instead of a bare prompt. It
+    // records nothing; Team drafting lives behind /setup-team. We reuse the brief
+    // we just fetched (no double round-trip). Skipped in eval mode.
+    const runInitPassFn = deps.runInitPass ?? defaultRunInitPass;
+    const getWorkspaceIdFn = deps.getWorkspaceId ?? (() => defaultGetWorkspaceId(deps.env));
+    const isInitDoneFn = deps.isInitDone ?? defaultIsInitDone;
+    const markInitDoneFn = deps.markInitDone ?? defaultMarkInitDone;
+    const workspaceId = getWorkspaceIdFn();
+    // F2a — one-time marker (idempotency): the context endpoint never reflects
+    // the welcome (it reads Vision + Goals), so a Vision/Goals-less workspace
+    // looks "fresh" forever and would re-welcome on every launch. A per-workspace
+    // marker short-circuits the pass after its first real run — regardless of
+    // brief emptiness. (Degrades to freshness-only when the workspace id is
+    // unknown.)
+    const alreadyInit = !evalMode && !!workspaceId && isInitDoneFn(workspaceId);
+    // F2b — fail CLOSED: a FAILED context fetch (network / non-2xx / throw) surfaces
+    // as a `null` brief here (fetchContextBrief and the catch above both map failure
+    // to null; a successful-but-empty response is a non-null object). A failed fetch
+    // must NOT be treated as fresh, or a transient outage would spuriously re-seed.
+    // Only a genuinely-empty SUCCESSFUL response (non-null, thin) counts as fresh.
+    const freshWorkspace = !evalMode && !alreadyInit && briefResult !== null && isFreshWorkspace(briefResult);
+    // Claude Code `.claude/rules` compat: the launcher passes the trusted rules
+    // dirs via env; unscoped rules inline, path-scoped rules become read-first
+    // pointers. Computed once per activation (rules are launch-time state, like
+    // pi's own skill discovery); fail-soft to null.
+    const rulesSection = claudeRulesSection(deps.env ?? process.env);
+    // Own the identity + inject live company context (and repo rules) on every
+    // turn. The extension loads identically in every pi process this app spawns —
+    // the interactive driver AND every `/go` stage child, subagent, and advisor
+    // consult — so the delegation-first paragraph (which assumes a `subagent`
+    // tool that only the driver has registered) is gated to the driver's own
+    // identity variant via isDriverCaller's env.YAGNI_CALLER check (config.ts).
+    // Under YAGNI_DISABLE_BRANDING the handler returns nothing, so pi's
+    // assembled prompt passes through byte-exact (no rewrite, no brief
+    // injection, no rules section, no delegation identity).
+    const noBranding = brandingDisabled(env);
+    const identity = isDriverCaller(env) ? YAGNI_IDENTITY_DRIVER : undefined;
+    pi.on("before_agent_start", (event) => noBranding
+        ? undefined
+        : {
+            systemPrompt: appendClaudeRules(brandSystemPrompt(event.systemPrompt, { contextBrief, identity }), rulesSection),
+        });
+    // Two finalized-message guards share this handler (their conditions are
+    // mutually exclusive: YAG-460 takes error-stopped messages, YAG-466 takes
+    // stop/length ones without an errorMessage).
+    //
+    // YAG-460: a context-too-large rejection from the backend proxy gets a
+    // readable message in place of raw JSON (see the branch below for why it
+    // must keep the `request_too_large` marker and must not compact).
+    //
+    // YAG-466 belt-and-braces: a turn that ends "successfully" with zero content
+    // renders as literal silence in the TUI — the Working indicator vanishes and
+    // nothing appears, which reads as a frozen session. The backend now surfaces
+    // its own stalls as errors, so any empty completion that still gets here is
+    // unexplained; rewrite it into a visible error instead of letting it vanish.
+    // Only `stop`/`length` qualify: `aborted` is the user's own Esc (often with an
+    // empty message and no errorMessage — not a failure), and `error` already
+    // renders. The message text deliberately matches neither pi's overflow nor
+    // retryable-error patterns: a deterministic empty response should not burn
+    // auto-retries or trigger compaction — the user decides what to do next.
+    pi.on("message_end", (event, ctx) => {
+        const msg = event.message;
+        if (msg.role !== "assistant")
+            return;
+        // YAG-460: the backend proxy answers an oversized conversation with an
+        // OpenAI-format 413 whose type is `request_too_large`. pi's own overflow
+        // detection matches that marker and runs full recovery — compact, then
+        // auto-retry the failed turn — so this branch must NOT call ctx.compact()
+        // (it would race the built-in recovery and lose the retry). Its only job
+        // is UX: replace the raw `413: {"error":{...}}` JSON with a readable
+        // message and tell the user what is happening. The rewritten text KEEPS
+        // the `request_too_large` marker verbatim: pi's _checkCompaction reads the
+        // post-replacement message, and dropping the marker would defeat the very
+        // recovery this error exists to trigger.
+        if (msg.stopReason === "error" && msg.errorMessage) {
+            const isContextTooLarge = /request_too_large|context_too_large/i.test(msg.errorMessage);
+            if (!isContextTooLarge)
+                return;
+            const explanation = "The conversation context is too large for the model (request_too_large). "
+                + "YAGNI Code is compacting the session and retrying automatically — "
+                + "if it does not recover, run /compact or start a new session.";
+            if (ctx.hasUI) {
+                try {
+                    ctx.ui.notify(explanation, "warning");
+                }
+                catch {
+                    // Surfacing the problem must never break the session itself.
+                }
+            }
+            return { message: { ...msg, errorMessage: explanation } };
+        }
+        if (msg.stopReason !== "stop" && msg.stopReason !== "length")
+            return;
+        if (msg.errorMessage)
+            return;
+        const hasVisibleContent = msg.content.some((c) => (c.type === "text" && c.text.trim().length > 0) ||
+            (c.type === "thinking" && c.thinking.trim().length > 0) ||
+            c.type === "toolCall");
+        if (hasVisibleContent)
+            return;
+        const explanation = `The model returned an empty response (stop reason: ${msg.stopReason}). ` +
+            "This usually means the provider stalled — please try again.";
+        if (ctx.hasUI) {
+            try {
+                ctx.ui.notify(explanation, "warning");
+            }
+            catch {
+                // Surfacing the problem must never break the session itself.
+            }
+        }
+        return { message: { ...msg, stopReason: "error", errorMessage: explanation } };
+    });
+    // Chrome: replace pi's built-in startup header (which shows "pi v<version>"
+    // and a "Pi can explain its own features…" line) with a YAGNI Code masthead,
+    // set the terminal title, and add a footer brand mark. TUI only.
+    pi.on("session_start", async (event, ctx) => {
+        ctx.ui?.setTitle(BRAND_NAME);
+        if (ctx.mode === "tui") {
+            ctx.ui?.setStatus?.("brand", BRAND_NAME);
+            // setHeader replaces the built-in header in place (verified against pi
+            // 0.80.2 setExtensionHeader); the factory returns a simple Text component.
+            ctx.ui?.setHeader?.((_tui, theme) => new Text(buildMastheadString(theme)));
+        }
+        // Best-effort, once at session start: if the token is at or near expiry, say
+        // so via a single notice so a long session does not silently start 401-ing
+        // mid-flight (both completions and grounding tools). The provider's expiry
+        // is preferred over the env snapshot because a proactive/401 refresh may
+        // already have rotated the token by the time the session starts.
+        if (ctx.hasUI) {
+            try {
+                const notice = tokenExpiryNotice(tokenProvider.getExpiresAt(), now());
+                if (notice)
+                    ctx.ui.notify(notice.message, notice.type);
+            }
+            catch {
+                // A notice must never disrupt session start.
+            }
+        }
+        // R4 write half: drain any judgment writes spooled by a previous session
+        // (transport/5xx failures of record_decision / record_engineering_context).
+        // Fire-and-forget and fail-soft — a flush must never delay or break session
+        // start; honest notices (replays, expiry drops) surface when it finishes.
+        if (!evalMode) {
+            void flushSpoolFn({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch })
+                .then((outcome) => {
+                if (!ctx.hasUI)
+                    return;
+                for (const noticeText of outcome.notices)
+                    ctx.ui.notify(noticeText, "info");
+            })
+                .catch(() => { });
+        }
+        // Run the init pass only on a genuine first-run (a fresh startup, not a
+        // reload/resume/fork) of a fresh workspace. Fully fail-soft: it must never
+        // break session start. The pass itself also re-guards on freshness.
+        if (event.reason === "startup" && freshWorkspace) {
+            try {
+                const outcome = await runInitPassFn(pi, ctx, {
+                    baseUrl,
+                    getToken: getTokenFn,
+                    fetchImpl: authedFetch,
+                    brief: briefResult,
+                });
+                // F2a: mark the workspace init-done on any real run (ran === true — thin
+                // or not), so it never re-seeds. A skip (not_fresh / non_interactive) is
+                // ran:false and does NOT mark, leaving the seed for a later real run.
+                if (outcome.ran && workspaceId)
+                    markInitDoneFn(workspaceId);
+            }
+            catch {
+                // The init pass is best-effort; a failure never blocks the session.
+            }
+        }
+    });
+}
+export default async function (pi) {
+    await registerYagni(pi);
+}
+export { makeAskYagniTool } from "./askYagniTool.js";
+export { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
+export { ADVISOR_TIER, DEFAULT_ADVISOR_LIMITS, decideConsult, formatAdvisorSubtotal, makeAdvisorState, } from "./advisor.js";
+export { makeReviewBusinessMatchTool } from "./reviewTool.js";
+export { makeRecordEngineeringContextTool } from "./recordContextTool.js";
+export { makeRecordDecisionTool } from "./recordDecisionTool.js";
+export { makeSuggestNextWorkTool, defaultNextAction } from "./nextWorkTool.js";
+export { recordDecision } from "./recordDecisionTool.js";
+// Onramp Door B (as amended by ADR-0033): the first-run welcome (write-free,
+// free text first-class) + the explicit /setup-team drafting flow.
+export { runInitPass, runTeamSetup, registerTeamSetupCommand, isFreshWorkspace, readRepoIntake, draftEngineering, summarizeDraft, FRESH_BRIEF_MIN_CHARS, } from "./initPass.js";
+// Onramp Door B (F2a): the one-time init-pass idempotency marker.
+export { isInitDone, markInitDone, initDoneMarkerFile, _setInitDoneHomeForTest } from "./initDone.js";
+export { brandSystemPrompt, YAGNI_IDENTITY, YAGNI_IDENTITY_DRIVER, BRAND_NAME } from "./branding.js";
+export { attributionHeaders, isDriverCaller, fetchCatalog, getToken, getWorkspaceId, resolveBaseUrl, sanitizeCallerSegment, } from "./config.js";
+export { buildYagniProvider } from "./provider.js";
+export { registerGoCommand } from "./pipeline/goCommand.js";
+export { runPipeline } from "./pipeline/orchestrator.js";
+// R1: the in-loop resilience HOF a dev can compose with (or replace at) the
+// `runStage` seam, plus its policy type and the default policy.
+export { withResilience, classifyTransient, composeAbortSignal } from "./pipeline/resilience.js";
+export { DEFAULT_RESILIENCE_POLICY } from "./pipeline/types.js";
+// P4: the deterministic verify gate seam (override the command via .yagni-code/verify).
+export { buildVerifyEnv, detectVerifyCommand, makeRunVerify, parseVerifyFailures } from "./pipeline/verify.js";
+// M6: the report-only grounded-vs-blind eval engine.
+export { blindStages, reportOnlyStages, makeGroundedVsBlindEval, formatComparisonReport } from "./pipeline/eval.js";
+export { registerGoCompareCommand } from "./pipeline/goCompareCommand.js";
+// The general subagent tool: Claude Code-format agent discovery + fan-out.
+export { registerSubagents, makeSubagentTool, discoverSubagents, parseAgentMarkdown, buildSubagentStage, formatAgentList, mapModelTier, SUBAGENT_TOOL_NAME, GENERAL_AGENT_NAME, MAX_PARALLEL_SUBAGENTS, DEFAULT_SUBAGENT_TOOLS, } from "./subagents.js";
+// The session todo checklist: todo_write tool, widget renderer, /todos.
+export { registerTodos, makeTodoTool, normalizeTodos, reconstructTodos, renderTodoWidget, formatTodoList, todoSummary, TODO_TOOL_NAME, MAX_TODOS, } from "./todos.js";
+// P3 + W4: the permission gate seam (decideGate is pure; policy injectable) plus
+// the session bless-with-remember capture hook.
+export { decideGate, registerPermissionGate, filterStalePlanContext, DEFAULT_PERMISSION_POLICY, PLAN_CONTEXT_TYPE, PLAN_CONTEXT_MESSAGE, } from "./permission.js";
+// W4 judgment loop: the session bless store (tool + path-prefix, session-only).
+export { makeBlessStore, blessPath } from "./bless.js";
+// W4 judgment loop: the decisions surface (/decide + /decisions) + shared bank.
+export { bankDecision, fetchDecisions, supersedeDecision, parseDecideArgs, formatDecisionsList, shortId, registerDecisionCommands, DEFAULT_LIST_LIMIT, } from "./decisions.js";
+// W4 judgment loop: the debounced, TUI-confirmed decision capture at the gate.
+export { makeDecisionCapture, CAPTURE_DEBOUNCE_MS } from "./decisionCapture.js";
+// M1: ambient judgment recall appended to `read` results (pure cores + fetch).
+export { registerAmbientRecall, fetchRecall, formatRecallBlock, toRepoRelativePath, normalizeRecall, RECALL_TIMEOUT_MS, RECALL_MIN_DECISIONS, } from "./recall.js";
+// P2: the session cost accumulator + /cost command.
+export { makeCostAccumulator, formatCostLine, registerCostCommand } from "./costHud.js";
+// W4 trust plumbing: the refreshing TokenProvider (kills the boot snapshot) and
+// the ONE 401 refresh-then-retry-once fetch seam every tool shares.
+export { makeTokenProvider, makeAuthedFetch, persistRotationToProfile, PROACTIVE_REFRESH_WINDOW_MS, REFRESH_RETRY_MS, } from "./tokenProvider.js";
+// W4 trust plumbing: the durable write-spool for the judgment-capture tools
+// (idempotencyKey-replayed; server-side dedup makes flush safe).
+export { appendToSpool, loadSpool, flushSpool, sendOrSpool, spoolFile, MAX_SPOOL_AGE_MS, _setSpoolHomeForTest, } from "./spool.js";
+export { crashReportsDisabled, installUncaughtExceptionMonitor, makeCrashReporter, reportFatalCrash, sanitizeCrashError, sanitizeCrashText, } from "./crashReport.js";
+//# sourceMappingURL=index.js.map

package/dist/extension/initDone.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The CLI init-pass idempotency marker (Onramp Door B, spec §5B/§7).
+ *
+ * The init pass writes only to `yagni_code_decisions`, but freshness is computed
+ * from `GET /api/yagni-code/context` — which reads only Vision + active Goals.
+ * A workspace with neither (the common case for a fresh CLI-only user) therefore
+ * looks "fresh" on EVERY launch, so without a marker the init pass would re-run
+ * and accumulate duplicate decisions each time.
+ *
+ * The fix is a one-time, per-workspace marker file, dropped after the first real
+ * run. It lives in the same `~/.yagni-code` home as the run journal
+ * ({@link checkpoint.ts}), is keyed on a truncated SHA-256 of the workspace id so
+ * the filename is path-safe and reveals no identity, and holds only a timestamp
+ * (never a token or any PII). Every operation is fail-soft: a missing marker
+ * simply means "not yet run", and a write failure never breaks session start.
+ */
+export declare function _setInitDoneHomeForTest(dir: string | null): void;
+/**
+ * The marker path for a workspace. The id is hashed (SHA-256, first 16 hex chars)
+ * so an arbitrary/opaque workspace id is path-safe and the raw id never lands in
+ * a filename.
+ */
+export declare function initDoneMarkerFile(workspaceId: string): string;
+/** Has the init pass already run once for this workspace? Fail-soft → false. */
+export declare function isInitDone(workspaceId: string): boolean;
+/** Record that the init pass has run once for this workspace. Fail-soft (never throws). */
+export declare function markInitDone(workspaceId: string): void;
+//# sourceMappingURL=initDone.d.ts.map