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

package/dist/extension/index.js

@@ -0,0 +1,388 @@
+import { Text } from "@earendil-works/pi-tui";
+import { DEFAULT_ADVISOR_LIMITS, formatAdvisorSubtotal, makeAdvisorState } from "./advisor.js";
+import { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.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, buildMastheadString } from "./branding.js";
+import { registerCostCommand } from "./costHud.js";
+import { isFreshWorkspace, runInitPass as defaultRunInitPass } from "./initPass.js";
+import { isInitDone as defaultIsInitDone, markInitDone as defaultMarkInitDone } from "./initDone.js";
+import { registerGoCommand } from "./pipeline/goCommand.js";
+import { registerGoCompareCommand } from "./pipeline/goCompareCommand.js";
+import { 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 { flushSpool as defaultFlushSpool } from "./spool.js";
+import { makeAuthedFetch, makeTokenProvider } from "./tokenProvider.js";
+import { fetchCatalog as defaultFetchCatalog, fetchContextBrief as defaultFetchContextBrief, getToken, getTokenExpiresAt as defaultGetTokenExpiresAt, getWorkspaceId as defaultGetWorkspaceId, 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";
+}
+export async function registerYagni(pi, deps = {}) {
+    const baseUrl = deps.baseUrl ?? resolveBaseUrl();
+    const now = deps.now ?? (() => Date.now());
+    const fetchCatalog = deps.fetchCatalog ?? defaultFetchCatalog;
+    const evalMode = isEvalMode(deps.env ?? process.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;
+    const catalog = await fetchCatalog({ baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+    pi.registerProvider("yagni", buildYagniProvider(catalog, baseUrl));
+    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);
+    // 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);
+    // The grounded multi-agent pipeline entry point: /go <ticket> runs
+    // map → plan → implement → review → fix, each child grounded by inheritance.
+    registerGoCommand(pi);
+    // 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);
+    // 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.
+    registerPermissionGate(pi, {
+        onBlessRemember: decisionCapture
+            ? (ctx, info) => decisionCapture.captureFromBless(ctx, info)
+            : undefined,
+    });
+    // P2: /cost reports session usage (accumulated off turn_end) + credit headroom.
+    // The headroom fetch is fail-soft: until the backend /credits endpoint exists it
+    // resolves null and /cost still shows session usage.
+    registerCostCommand(pi, {
+        // Advisor consults run in a child process, so they never reach /cost's
+        // turn_end accumulator. Thread the subtotal in explicitly (YAG-383 owns the
+        // real fix, which also covers /go's still-invisible stage spend).
+        advisorSubtotal: () => formatAdvisorSubtotal(advisorState.read(), DEFAULT_ADVISOR_LIMITS),
+        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: 10_000, 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;
+            }
+        },
+    });
+    // /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,
+    });
+    // Onramp Door B (spec §5B/§7): on a FRESH workspace (empty/thin grounding
+    // corpus), the first run reads the repo, drafts the engineering-half brief + a
+    // proposed Engineering Team, and seeds decisions — instead of a bare prompt. 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 init pass writes only to
+    // `yagni_code_decisions`, which the context endpoint never reads back (it reads
+    // Vision + Goals), so a Vision/Goals-less workspace looks "fresh" forever and
+    // would re-seed duplicate decisions 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);
+    // Own the identity + inject live company context on every turn.
+    pi.on("before_agent_start", (event) => ({
+        systemPrompt: brandSystemPrompt(event.systemPrompt, { contextBrief }),
+    }));
+    // 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: the CLI init pass (fresh-workspace detection + repo intake +
+// engineering-half drafting + decision seeding + one default next action).
+export { runInitPass, 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, BRAND_NAME } from "./branding.js";
+export { fetchCatalog, getToken, getWorkspaceId, resolveBaseUrl } 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";
+//# 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

package/dist/extension/initDone.js

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { codeStateHome } from "./stateHome.js";
+/**
+ * Test seam mirroring {@link checkpoint._setCheckpointHomeForTest}: when set, the
+ * marker roots here instead of `~/.yagni-code`, so tests hit a tmpdir. Pass
+ * `null` to restore.
+ */
+let homeOverride = null;
+export function _setInitDoneHomeForTest(dir) {
+    homeOverride = dir;
+}
+function initDoneHome() {
+    return codeStateHome(homeOverride);
+}
+/**
+ * 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 function initDoneMarkerFile(workspaceId) {
+    const hash = createHash("sha256").update(workspaceId).digest("hex").slice(0, 16);
+    return join(initDoneHome(), `init-done-${hash}`);
+}
+/** Has the init pass already run once for this workspace? Fail-soft → false. */
+export function isInitDone(workspaceId) {
+    if (!workspaceId)
+        return false;
+    try {
+        return existsSync(initDoneMarkerFile(workspaceId));
+    }
+    catch {
+        return false; // unreadable → treat as not-yet-run (the caller still guards on freshness)
+    }
+}
+/** Record that the init pass has run once for this workspace. Fail-soft (never throws). */
+export function markInitDone(workspaceId) {
+    if (!workspaceId)
+        return;
+    try {
+        mkdirSync(initDoneHome(), { recursive: true, mode: 0o700 });
+        // Content is a bare timestamp — no token, no PII (the id is hashed in the name).
+        writeFileSync(initDoneMarkerFile(workspaceId), `${new Date().toISOString()}\n`, { mode: 0o600 });
+    }
+    catch {
+        /* fail-soft: a marker write must never break session start */
+    }
+}
+//# sourceMappingURL=initDone.js.map

package/dist/extension/initPass.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The CLI init pass (Onramp Door B, spec §5B/§7).
+ *
+ * On a FRESH workspace, the first `yagni` run in a repo should not drop the
+ * user into a bare prompt. Instead it runs a one-time init pass:
+ *   1. detect a fresh workspace (an empty/thin grounding corpus, via the existing
+ *      `GET /api/yagni-code/context` brief),
+ *   2. read the repo (README, AGENTS.md/CLAUDE.md, package.json scripts, ADRs),
+ *   3. draft the ENGINEERING HALF of the company brief + a proposed Engineering
+ *      Team, and record the salient ADRs/conventions as decisions so the corpus
+ *      is non-empty for the very first `/go`,
+ *   4. present the draft for approve/edit in-terminal (mirrored to the app via the
+ *      recorded decisions), NEVER auto-committing the Team, and
+ *   5. offer the ONE default next action (`suggest_next_work`) with escape hatches.
+ *
+ * Honesty rails (non-negotiable, spec §9): when a repo has no README/AGENTS/ADRs
+ * the engineering half stays THIN and SAYS SO — nothing is fabricated, and no
+ * decision is seeded from thin air. The proposed Team is only ever a DRAFT; it is
+ * never created/committed automatically.
+ *
+ * No new backend transport: the only writes are through the existing token-scoped
+ * `record_decision` endpoint (reused via {@link recordDecision}). Every seam is
+ * injectable so the whole pass is unit-testable without a network or a filesystem.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { fetchContextBrief as defaultFetchContextBrief, type ContextBrief } from "./config.js";
+import { type NextActionOption } from "./nextWorkTool.js";
+import { recordDecision as defaultRecordDecision, type RecordDecisionParams } from "./recordDecisionTool.js";
+/**
+ * Below this many non-whitespace characters (and with no sources), a returned
+ * context brief is treated as thin/empty — i.e. the corpus has not been seeded
+ * yet, so this is a fresh workspace that should run the init pass.
+ */
+export declare const FRESH_BRIEF_MIN_CHARS = 40;
+/**
+ * Is this a fresh workspace (an empty/thin grounding corpus)? A `null` brief, or
+ * a brief with only a stub of text and no sources, means nothing has grounded the
+ * workspace yet. A brief with real text OR any sources means it is already
+ * populated and the init pass must be skipped.
+ */
+export declare function isFreshWorkspace(brief: ContextBrief | null | undefined): boolean;
+/** A single architecture-decision record found in the repo. */
+export interface RepoAdr {
+    /** Repo-relative path, e.g. `docs/adr/0001-use-fly.md`. */
+    path: string;
+    /** The record's title (its first heading, or the filename when headingless). */
+    title: string;
+    /** A short first-paragraph summary, when present. */
+    summary?: string;
+}
+/** What the repo intake could find. All fields are best-effort / optional. */
+export interface RepoIntake {
+    /** README body (capped), when present. */
+    readme?: string;
+    /** AGENTS.md or CLAUDE.md body (capped), when present. */
+    agents?: string;
+    /** package.json `scripts` map (empty when absent/unparseable). */
+    packageScripts: Record<string, string>;
+    /** Architecture decision records found under docs/adr (etc.). */
+    adrs: RepoAdr[];
+    /** The literal test command (package.json `scripts.test`), when present. */
+    testCommand?: string;
+    /** The literal build command (package.json `scripts.build`), when present. */
+    buildCommand?: string;
+}
+/** Injectable filesystem seam so repo intake is unit-testable without disk. */
+export interface RepoIntakeFs {
+    readFile(p: string): Promise<string>;
+    readdir(p: string): Promise<string[]>;
+}
+/**
+ * Read the repo at `cwd` for the signals that seed the engineering half of the
+ * brief. Every read is best-effort; a missing file simply drops that signal.
+ */
+export declare function readRepoIntake(cwd: string, fs?: RepoIntakeFs): Promise<RepoIntake>;
+/** A proposed Engineering Team — a DRAFT that is never auto-committed. */
+export interface DraftTeam {
+    name: string;
+    mission: string;
+    responsibilities: string[];
+    playbookRules: string[];
+    testCommand?: string;
+    buildCommand?: string;
+    riskAreas: string[];
+}
+/** The drafted engineering half: the brief, seeded decisions, and a Team draft. */
+export interface EngineeringDraft {
+    /** The engineering-half brief text (honest-when-thin). */
+    brief: string;
+    /** True when the repo had no README/AGENTS/ADRs — the brief says so, nothing is fabricated. */
+    thin: boolean;
+    /** Decisions to seed into the corpus. EMPTY when thin (no fabrication). */
+    decisions: RecordDecisionParams[];
+    /** The proposed Engineering Team (a draft; never auto-committed). */
+    team: DraftTeam;
+}
+/**
+ * Draft the engineering half of the brief from repo intake. PURE. Honest-when-thin:
+ * with no README/AGENTS/ADRs the brief says so and NO decision is seeded.
+ */
+export declare function draftEngineering(intake: RepoIntake): EngineeringDraft;
+/** Injectable dependencies for {@link runInitPass}. */
+export interface RunInitPassDeps {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    /**
+     * A pre-fetched context brief (the caller usually already fetched it to boot
+     * grounded). When `undefined`, the pass fetches it itself. Pass `null`
+     * explicitly to signal "fetched, and it was empty".
+     */
+    brief?: ContextBrief | null;
+    fetchContextBrief?: typeof defaultFetchContextBrief;
+    readRepoIntake?: (cwd: string) => Promise<RepoIntake>;
+    recordDecision?: typeof defaultRecordDecision;
+}
+/** The outcome of an init-pass attempt. */
+export type InitPassOutcome = {
+    ran: false;
+    reason: "not_fresh" | "non_interactive";
+} | {
+    ran: true;
+    thin: boolean;
+    decisionsRecorded: number;
+    /** The Team was drafted for the user. */
+    teamDrafted: true;
+    /** The Team is NEVER created/committed automatically. Always false. */
+    teamCommitted: false;
+    /** Which next action the user picked (undefined in headless mode). */
+    chosenAction?: NextActionOption["id"];
+};
+/**
+ * Compact one-screen PREVIEW of the draft for the approve/edit dialog.
+ *
+ * Approval-gated (spec §5B/§9, F2/F13): NOTHING is written to the corpus until
+ * the human approves or corrects the draft, so this is a preview of INTENT — it
+ * states what will be recorded ON APPROVAL, and never claims a corpus was
+ * already seeded. When thin there is nothing to record (honest — nothing to
+ * fabricate). The ACTUAL recorded count is reported after the write runs (see
+ * `runInitPass`).
+ */
+export declare function summarizeDraft(draft: EngineeringDraft): string;
+/**
+ * Run the init pass. Guards on fresh-workspace detection (defensive — the caller
+ * also guards), reads the repo, drafts the engineering half, presents it for
+ * approve/edit, and ONLY THEN seeds the corpus (approval-gated: an approve banks
+ * the drafted decisions, an edit banks the correction, a decline writes nothing),
+ * before offering the one default next action. Fully fail-soft: a UI or network
+ * hiccup never throws (it must never break session start).
+ */
+export declare function runInitPass(pi: ExtensionAPI, ctx: ExtensionContext, deps: RunInitPassDeps): Promise<InitPassOutcome>;
+//# sourceMappingURL=initPass.d.ts.map