@yagni-app/code 0.1.0 → 0.2.1

package/dist/extension/todos.js

@@ -0,0 +1,217 @@
+/**
+ * The session todo list — the visible checklist for multi-step work.
+ *
+ * A `todo_write` tool the model calls with the FULL list every time (replace,
+ * not patch: replacement is idempotent under retries and always renders a
+ * coherent board), a persistent above-editor widget while steps remain open,
+ * and a `/todos` command to pull the list on demand.
+ *
+ * State follows pi's branching model the same way the session does: the
+ * canonical list is the LAST `todo_write` tool result on the current branch,
+ * reconstructed on session_start/session_tree, so forking or rewinding a
+ * session automatically shows the list as it stood at that point. The
+ * in-memory copy is just a cache of that.
+ */
+import { Type } from "typebox";
+import { isDesktopSurface } from "./surface.js";
+export const TODO_TOOL_NAME = "todo_write";
+export const MAX_TODOS = 50;
+export const MAX_TODO_TEXT = 300;
+const WIDGET_KEY = "yagni-todos";
+/**
+ * The desktop's structured state record rides its own widget key, like the
+ * `/go` run state: one JSON line the app parses and renders itself, never
+ * themed terminal lines. The desktop shell hand-declares the matching parser
+ * (`parseTodoState` in its piProtocol.ts); a key-set assertion in
+ * todos.test.ts guards the two against drift.
+ */
+export const TODO_STATE_KEY = "yagni-todos:state";
+/** Header + items + overflow line must stay under pi's 10-line widget cap. */
+const MAX_WIDGET_ITEMS = 7;
+const STATUSES = ["pending", "in_progress", "completed"];
+/**
+ * Validate a full replacement list. Strict: this is model input rendered
+ * straight into the terminal. An empty list is valid (it clears the board).
+ */
+export function normalizeTodos(raw) {
+    if (!Array.isArray(raw))
+        return { ok: false, error: "todos must be an array" };
+    if (raw.length > MAX_TODOS)
+        return { ok: false, error: `todos is capped at ${MAX_TODOS} items` };
+    const todos = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object")
+            return { ok: false, error: "each todo must be an object" };
+        const { text, status } = item;
+        if (typeof text !== "string" || text.trim().length === 0) {
+            return { ok: false, error: "each todo needs non-empty text" };
+        }
+        if (typeof status !== "string" || !STATUSES.includes(status)) {
+            return { ok: false, error: `status must be one of ${STATUSES.join(", ")}` };
+        }
+        todos.push({ text: text.trim().slice(0, MAX_TODO_TEXT), status: status });
+    }
+    return { ok: true, todos };
+}
+export function todoSummary(todos) {
+    return {
+        done: todos.filter((t) => t.status === "completed").length,
+        total: todos.length,
+        active: todos.find((t) => t.status === "in_progress")?.text ?? null,
+    };
+}
+const GLYPH = { pending: "[ ]", in_progress: "[>]", completed: "[x]" };
+/** Plain-text checklist (tool results, /todos in headless contexts). */
+export function formatTodoList(todos) {
+    if (todos.length === 0)
+        return "No todos.";
+    const { done, total } = todoSummary(todos);
+    const lines = todos.map((t) => `${GLYPH[t.status]} ${t.text}`);
+    return [`${done}/${total} done`, ...lines].join("\n");
+}
+/**
+ * The above-editor checklist. Empty (paint nothing) when there is no list or
+ * every step is completed — a finished board should leave the screen. Capped
+ * so header + items + overflow stays under pi's 10-line widget truncation.
+ */
+export function renderTodoWidget(todos, theme) {
+    const { done, total } = todoSummary(todos);
+    if (total === 0 || done === total)
+        return [];
+    const lines = [theme.fg("muted", `Todos ${done}/${total}`)];
+    const visible = todos.slice(0, MAX_WIDGET_ITEMS);
+    for (const todo of visible) {
+        if (todo.status === "completed") {
+            const text = theme.strikethrough ? theme.strikethrough(todo.text) : todo.text;
+            lines.push(`${theme.fg("success", "☑ ")}${theme.fg("dim", text)}`);
+        }
+        else if (todo.status === "in_progress") {
+            lines.push(`${theme.fg("accent", "▶ ")}${theme.fg("text", todo.text)}`);
+        }
+        else {
+            lines.push(`${theme.fg("dim", "☐ ")}${theme.fg("muted", todo.text)}`);
+        }
+    }
+    if (todos.length > visible.length) {
+        lines.push(theme.fg("dim", `…and ${todos.length - visible.length} more`));
+    }
+    return lines;
+}
+/** The desktop state record: exactly one JSON line under TODO_STATE_KEY. */
+export function todoStateLine(todos) {
+    return JSON.stringify({ v: 1, todos });
+}
+/** Replay the branch: the last todo_write result is the canonical list. */
+export function reconstructTodos(entries) {
+    let todos = [];
+    for (const entry of entries) {
+        const e = entry;
+        if (e?.type !== "message")
+            continue;
+        const msg = e.message;
+        if (msg?.role !== "toolResult" || msg.toolName !== TODO_TOOL_NAME)
+            continue;
+        const details = msg.details;
+        const normalized = normalizeTodos(details?.todos);
+        if (normalized.ok)
+            todos = normalized.todos;
+    }
+    return todos;
+}
+const parameters = Type.Object({
+    todos: Type.Array(Type.Object({
+        text: Type.String({ description: "The step, short and imperative." }),
+        status: Type.Union([
+            Type.Literal("pending"),
+            Type.Literal("in_progress"),
+            Type.Literal("completed"),
+        ]),
+    }), { description: "The FULL list; it replaces the previous one." }),
+});
+function paintWidget(ctx, todos) {
+    if (!ctx?.hasUI)
+        return;
+    try {
+        if (isDesktopSurface()) {
+            // The desktop renders the checklist itself, so it gets the structured
+            // record instead of themed lines (RPC mode forwards widgetLines
+            // verbatim, and ANSI would land in the DOM). Painted on EVERY change —
+            // including an empty or finished list — so the app can clear its board,
+            // and on branch replay so resume/fork restores the list. The "todos
+            // n/m" status chip would be redundant next to the app's own rendering.
+            ctx.ui.setWidget?.(TODO_STATE_KEY, [todoStateLine(todos)], { placement: "aboveEditor" });
+            return;
+        }
+        const theme = ctx.ui.theme;
+        const lines = renderTodoWidget(todos, theme);
+        ctx.ui.setWidget?.(WIDGET_KEY, lines.length > 0 ? lines : undefined, {
+            placement: "aboveEditor",
+        });
+        const { done, total } = todoSummary(todos);
+        ctx.ui.setStatus?.(WIDGET_KEY, total > 0 && done < total ? `todos ${done}/${total}` : undefined);
+    }
+    catch {
+        // Painting is chrome; it must never break the tool call.
+    }
+}
+/**
+ * Build the todo_write tool definition around a shared store. Separated from
+ * registration so tests can drive execute directly.
+ */
+export function makeTodoTool(get, set) {
+    return {
+        name: TODO_TOOL_NAME,
+        label: "Todos",
+        description: "Track your plan for multi-step work as a checklist the user can see. " +
+            "Pass the FULL list every time — it replaces the previous list. Keep exactly one item " +
+            "in_progress at a time, mark items completed the moment they are done, and add newly " +
+            "discovered steps as pending. Use it for any task with three or more steps, updating as you go.",
+        promptSnippet: "todo_write: keep a user-visible checklist for multi-step work (full-list replacement).",
+        parameters,
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            const normalized = normalizeTodos(params.todos);
+            if (!normalized.ok) {
+                return {
+                    content: [{ type: "text", text: `Error: ${normalized.error}` }],
+                    details: { todos: get() },
+                    isError: true,
+                };
+            }
+            set(normalized.todos);
+            paintWidget(ctx, normalized.todos);
+            return {
+                content: [{ type: "text", text: formatTodoList(normalized.todos) }],
+                details: { todos: normalized.todos },
+            };
+        },
+    };
+}
+/** Wire the tool, the branch-replay events, and the /todos command. */
+export function registerTodos(pi) {
+    let todos = [];
+    const reconstruct = (ctx) => {
+        try {
+            todos = reconstructTodos(ctx.sessionManager.getBranch());
+        }
+        catch {
+            todos = [];
+        }
+        paintWidget(ctx, todos);
+    };
+    pi.on("session_start", async (_event, ctx) => reconstruct(ctx));
+    pi.on("session_tree", async (_event, ctx) => reconstruct(ctx));
+    pi.registerTool(makeTodoTool(() => todos, (next) => {
+        todos = next;
+    }));
+    pi.registerCommand("todos", {
+        description: "Show the agent's current task list for this session.",
+        handler: async (_args, ctx) => {
+            if (!ctx.hasUI)
+                return;
+            ctx.ui.notify(todos.length === 0
+                ? "No todos. The agent keeps a checklist here when a task takes multiple steps."
+                : formatTodoList(todos), "info");
+        },
+    });
+}
+//# sourceMappingURL=todos.js.map

package/dist/extension/tokenProvider.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Refreshing TokenProvider — kills the boot-time token snapshot (spec §4, W4).
+ *
+ * The extension used to capture `YAGNI_TOKEN` once at registration, so a long
+ * session outlived its token and every grounding tool started 401-ing with no
+ * recovery. The provider owns the CURRENT token + expiry instead:
+ *
+ *  - `getToken()` always returns the current token (tools read it per call).
+ *  - A proactive, unref'd timer rotates the token via `POST /auth/refresh`
+ *    when it is within 24h of expiry (the CLI launcher covers the 7-day
+ *    window at spawn; this covers sessions that outlive that).
+ *  - On a tool 401, {@link makeAuthedFetch} asks for ONE refresh and retries
+ *    the request once with the fresh token. ALL refresh calls (proactive and
+ *    401-triggered, from any number of concurrent tools) are serialized behind
+ *    a single in-flight promise, so a burst of 401s costs one rotation.
+ *  - On rotation the provider updates `process.env.YAGNI_TOKEN` (pi re-resolves
+ *    `$YAGNI_TOKEN` per model request — see provider.ts) AND
+ *    `process.env.YAGNI_TOKEN_EXPIRES_AT` (config.ts reads it), and persists
+ *    the rotated token back to the launcher's profile file (`YAGNI_PROFILE_PATH`,
+ *    atomic write, 0600) when set, so the next `yagni` launch reuses it.
+ *
+ * Everything is FAIL-SOFT: a refresh failure leaves the current token in place
+ * (the old token keeps a 5-minute server-side grace after a successful rotation,
+ * so in-flight requests never race the swap).
+ */
+/** How close to expiry (24h) the proactive in-session refresh fires. */
+export declare const PROACTIVE_REFRESH_WINDOW_MS: number;
+/** How long after a failed proactive refresh the timer retries (fail-soft). */
+export declare const REFRESH_RETRY_MS: number;
+/** The rotated-token payload from `POST /api/yagni-code/auth/refresh` (§2). */
+interface RefreshResponse {
+    token: string;
+    expiresAt?: string;
+    workspaceId?: string;
+}
+/** A cancellable timer seam: schedule `fn` after `ms`, return a cancel. */
+export type ScheduleFn = (fn: () => void, ms: number) => () => void;
+/** Injectable seams for {@link makeTokenProvider}. */
+export interface TokenProviderDeps {
+    baseUrl: string;
+    /**
+     * The env object rotations are WRITTEN to (default: process.env). Seeding is
+     * the caller's job (registerYagni resolves the env itself) so the provider
+     * never silently re-reads a different env than the caller intended.
+     */
+    env?: NodeJS.ProcessEnv;
+    /** Seed token (undefined = not authenticated; refresh() is then a no-op). */
+    initialToken?: string;
+    /** Seed ISO expiry (undefined = unknown; the proactive timer stays off). */
+    initialExpiresAt?: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    /** Timer seam (default: unref'd setTimeout); injected in tests. */
+    schedule?: ScheduleFn;
+    /**
+     * Persist a rotation to the active profile file. Default: atomic 0600 write
+     * to `env.YAGNI_PROFILE_PATH` (merging the existing profile JSON), no-op when
+     * the launcher did not forward a profile path. Always fail-soft.
+     */
+    persistProfile?: (rotation: RefreshResponse) => void;
+}
+/** The live token surface the tools and the model provider read through. */
+export interface TokenProvider {
+    getToken(): string | undefined;
+    getExpiresAt(): string | undefined;
+    /**
+     * Rotate the token via `POST /auth/refresh`. Serialized: concurrent callers
+     * share one in-flight request. Resolves `true` only when a new token was
+     * installed. Never throws (fail-soft).
+     */
+    refresh(): Promise<boolean>;
+    /** Cancel the proactive timer (test hygiene; the default timer is unref'd). */
+    dispose(): void;
+}
+/**
+ * Atomic profile write: merge the rotation into the existing profile JSON,
+ * write a fresh 0600 temp file in the same directory, then rename over the
+ * original (rename is atomic on the same filesystem). Mirrors the launcher's
+ * profiles.ts format (2-space indent + trailing newline). Fail-soft.
+ */
+export declare function persistRotationToProfile(profilePath: string, rotation: RefreshResponse): void;
+export declare function makeTokenProvider(deps: TokenProviderDeps): TokenProvider;
+/**
+ * The ONE 401 seam for every authed fetch: wrap the base fetch so a 401
+ * triggers a single serialized refresh and, when the token actually rotated,
+ * ONE retry with a fresh `authorization` header. Non-401 responses and
+ * failed refreshes pass through untouched; a body that cannot be replayed
+ * (anything but a string/undefined) is never retried. The wrapper adds no
+ * retry loops of its own — resilientFetch above it still owns transient retry.
+ */
+export declare function makeAuthedFetch(provider: TokenProvider, baseFetch?: typeof fetch): typeof fetch;
+export {};
+//# sourceMappingURL=tokenProvider.d.ts.map

package/dist/extension/tokenProvider.js

@@ -0,0 +1,234 @@
+/**
+ * Refreshing TokenProvider — kills the boot-time token snapshot (spec §4, W4).
+ *
+ * The extension used to capture `YAGNI_TOKEN` once at registration, so a long
+ * session outlived its token and every grounding tool started 401-ing with no
+ * recovery. The provider owns the CURRENT token + expiry instead:
+ *
+ *  - `getToken()` always returns the current token (tools read it per call).
+ *  - A proactive, unref'd timer rotates the token via `POST /auth/refresh`
+ *    when it is within 24h of expiry (the CLI launcher covers the 7-day
+ *    window at spawn; this covers sessions that outlive that).
+ *  - On a tool 401, {@link makeAuthedFetch} asks for ONE refresh and retries
+ *    the request once with the fresh token. ALL refresh calls (proactive and
+ *    401-triggered, from any number of concurrent tools) are serialized behind
+ *    a single in-flight promise, so a burst of 401s costs one rotation.
+ *  - On rotation the provider updates `process.env.YAGNI_TOKEN` (pi re-resolves
+ *    `$YAGNI_TOKEN` per model request — see provider.ts) AND
+ *    `process.env.YAGNI_TOKEN_EXPIRES_AT` (config.ts reads it), and persists
+ *    the rotated token back to the launcher's profile file (`YAGNI_PROFILE_PATH`,
+ *    atomic write, 0600) when set, so the next `yagni` launch reuses it.
+ *
+ * Everything is FAIL-SOFT: a refresh failure leaves the current token in place
+ * (the old token keeps a 5-minute server-side grace after a successful rotation,
+ * so in-flight requests never race the swap).
+ */
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** How close to expiry (24h) the proactive in-session refresh fires. */
+export const PROACTIVE_REFRESH_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** How long after a failed proactive refresh the timer retries (fail-soft). */
+export const REFRESH_RETRY_MS = 60 * 60 * 1000;
+/** Per-request wall-clock cap so a hung refresh never stalls a 401 retry. */
+const REFRESH_REQUEST_TIMEOUT_MS = 10_000;
+/** setTimeout overflows past 2^31-1 ms; clamp long delays and re-arm on fire. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const defaultSchedule = (fn, ms) => {
+    const t = setTimeout(fn, ms);
+    // Never keep the process alive for a background refresh.
+    t.unref?.();
+    return () => clearTimeout(t);
+};
+/**
+ * Atomic profile write: merge the rotation into the existing profile JSON,
+ * write a fresh 0600 temp file in the same directory, then rename over the
+ * original (rename is atomic on the same filesystem). Mirrors the launcher's
+ * profiles.ts format (2-space indent + trailing newline). Fail-soft.
+ */
+export function persistRotationToProfile(profilePath, rotation) {
+    try {
+        let existing = {};
+        try {
+            const parsed = JSON.parse(readFileSync(profilePath, "utf8"));
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                existing = parsed;
+            }
+        }
+        catch {
+            /* missing/corrupt profile — still persist the rotation fields */
+        }
+        const next = {
+            ...existing,
+            token: rotation.token,
+            ...(rotation.expiresAt ? { expiresAt: rotation.expiresAt } : {}),
+            ...(rotation.workspaceId ? { workspaceId: rotation.workspaceId } : {}),
+        };
+        mkdirSync(dirname(profilePath), { recursive: true, mode: 0o700 });
+        const tmp = join(dirname(profilePath), `.${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}.tmp`);
+        writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+        // writeFile honors mode only on create; the tmp file IS a create, but be
+        // explicit so a umask can never widen a token-bearing file.
+        chmodSync(tmp, 0o600);
+        renameSync(tmp, profilePath);
+    }
+    catch {
+        /* fail-soft: a failed persist never breaks the session (memory + env win) */
+    }
+}
+export function makeTokenProvider(deps) {
+    const env = deps.env ?? process.env;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const now = deps.now ?? (() => Date.now());
+    const schedule = deps.schedule ?? defaultSchedule;
+    const persistProfile = deps.persistProfile ??
+        ((rotation) => {
+            const profilePath = env.YAGNI_PROFILE_PATH?.trim();
+            if (profilePath)
+                persistRotationToProfile(profilePath, rotation);
+        });
+    let token = deps.initialToken;
+    let expiresAt = deps.initialExpiresAt;
+    let cancelTimer = null;
+    let inFlight = null;
+    function parsedExpiryMs() {
+        if (!expiresAt)
+            return null;
+        const ms = Date.parse(expiresAt);
+        return Number.isNaN(ms) ? null : ms;
+    }
+    /** (Re)arm the proactive timer from the current expiry. Unknown expiry → off. */
+    function armProactiveTimer() {
+        cancelTimer?.();
+        cancelTimer = null;
+        const expiryMs = parsedExpiryMs();
+        if (expiryMs === null)
+            return;
+        if (expiryMs <= now())
+            return; // already expired: refresh would 401 forever
+        const untilWindow = expiryMs - now() - PROACTIVE_REFRESH_WINDOW_MS;
+        const delay = Math.min(Math.max(untilWindow, 0), MAX_TIMER_MS);
+        cancelTimer = schedule(() => {
+            cancelTimer = null;
+            // A clamped long delay fired early: not in the window yet, just re-arm.
+            const nowExpiryMs = parsedExpiryMs();
+            if (nowExpiryMs !== null && nowExpiryMs - now() > PROACTIVE_REFRESH_WINDOW_MS) {
+                armProactiveTimer();
+                return;
+            }
+            void refresh().then((rotated) => {
+                // Success re-arms from the new expiry inside applyRotation; a failure
+                // retries later (fail-soft) as long as the token is not yet expired.
+                if (!rotated && cancelTimer === null) {
+                    const expiry = parsedExpiryMs();
+                    if (expiry !== null && expiry > now()) {
+                        cancelTimer = schedule(() => {
+                            cancelTimer = null;
+                            void refresh();
+                        }, Math.min(REFRESH_RETRY_MS, MAX_TIMER_MS));
+                    }
+                }
+            });
+        }, delay);
+    }
+    function applyRotation(rotation) {
+        token = rotation.token;
+        if (rotation.expiresAt)
+            expiresAt = rotation.expiresAt;
+        // pi re-resolves $YAGNI_TOKEN per model request; config helpers read the
+        // expiry env. Both must see the rotation immediately.
+        env.YAGNI_TOKEN = rotation.token;
+        if (rotation.expiresAt)
+            env.YAGNI_TOKEN_EXPIRES_AT = rotation.expiresAt;
+        try {
+            persistProfile(rotation);
+        }
+        catch {
+            /* fail-soft */
+        }
+        armProactiveTimer();
+    }
+    async function doRefresh() {
+        const current = token;
+        if (!current)
+            return false;
+        try {
+            const res = await fetchImpl(`${deps.baseUrl}/api/yagni-code/auth/refresh`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${current}`,
+                },
+                body: "{}",
+                signal: AbortSignal.timeout(REFRESH_REQUEST_TIMEOUT_MS),
+            });
+            if (!res.ok)
+                return false;
+            const data = (await res.json());
+            if (!data || typeof data.token !== "string" || data.token.length === 0)
+                return false;
+            applyRotation({
+                token: data.token,
+                expiresAt: typeof data.expiresAt === "string" ? data.expiresAt : undefined,
+                workspaceId: typeof data.workspaceId === "string" ? data.workspaceId : undefined,
+            });
+            return true;
+        }
+        catch {
+            return false; // network/timeout: keep the current token (fail-soft)
+        }
+    }
+    function refresh() {
+        // Single-flight: a proactive tick and N simultaneous 401 handlers share
+        // one POST, so the backend never sees a refresh stampede and the 5-minute
+        // grace window on the old token stays meaningful.
+        if (!inFlight) {
+            inFlight = doRefresh().finally(() => {
+                inFlight = null;
+            });
+        }
+        return inFlight;
+    }
+    armProactiveTimer();
+    return {
+        getToken: () => token,
+        getExpiresAt: () => expiresAt,
+        refresh,
+        dispose: () => {
+            cancelTimer?.();
+            cancelTimer = null;
+        },
+    };
+}
+/**
+ * The ONE 401 seam for every authed fetch: wrap the base fetch so a 401
+ * triggers a single serialized refresh and, when the token actually rotated,
+ * ONE retry with a fresh `authorization` header. Non-401 responses and
+ * failed refreshes pass through untouched; a body that cannot be replayed
+ * (anything but a string/undefined) is never retried. The wrapper adds no
+ * retry loops of its own — resilientFetch above it still owns transient retry.
+ */
+export function makeAuthedFetch(provider, baseFetch) {
+    const underlying = baseFetch ?? fetch;
+    const wrapped = async (input, init) => {
+        const res = await underlying(input, init);
+        if (res.status !== 401)
+            return res;
+        // Only string (or absent) bodies are safely re-sendable.
+        if (init?.body !== undefined && typeof init.body !== "string")
+            return res;
+        let rotated = false;
+        try {
+            rotated = await provider.refresh();
+        }
+        catch {
+            rotated = false;
+        }
+        if (!rotated)
+            return res;
+        const headers = new Headers(init?.headers);
+        headers.set("authorization", `Bearer ${provider.getToken() ?? ""}`);
+        return underlying(input, { ...init, headers });
+    };
+    return wrapped;
+}
+//# sourceMappingURL=tokenProvider.js.map

package/dist/launch.d.ts

@@ -1,7 +1,9 @@
 /**
- * Build the configured pi launch. `buildLaunch` is pure (no spawn, no fs) so it
- * is fully unit-testable: it returns the child environment and the pi argv that
- * registers pi-extension-yagni and defaults the provider to `yagni`.
+ * Build the configured pi launch. `buildLaunch` has no spawn/fs side effects,
+ * so it stays fully unit-testable, though it is no longer strictly pure: it
+ * mints a fresh session id (`randomUUID()`) on every call. It returns the
+ * child environment and the pi argv that registers pi-extension-yagni and
+ * defaults the provider to `yagni`.
  */
 import type { Credentials } from "./credentials.js";
 export interface LaunchPlan {
@@ -59,10 +61,30 @@ export interface BuildLaunchOptions {
      * in-process only, still fail-soft).
      */
     profilePath?: string;
+    /** Distribution-specific root shared with the bundled extension. */
+    stateDir?: string;
+    /**
+     * Launcher version, forwarded as `YAGNI_CODE_VERSION` so the bundled
+     * extension (which has no package.json on disk to read) can label its crash
+     * reports with the shipping version. Optional: omitted, reports say "unknown".
+     */
+    cliVersion?: string;
     /** Base environment to extend (defaults to process.env at call sites). */
     baseEnv?: NodeJS.ProcessEnv;
     /** Clock seam for the token-expiry preflight (defaults to Date.now). */
     now?: () => number;
+    /**
+     * Launcher-computed agent flags (e.g. Claude-compat `--skill` /
+     * `--prompt-template` paths). Inserted before the user's passthrough args so
+     * anything the user passes explicitly still wins.
+     */
+    extraAgentArgs?: string[];
+    /**
+     * Launcher-computed child env (e.g. Claude-compat plugin agent dirs and
+     * rules dirs). Merged before the YAGNI-critical keys so it can never
+     * override the token, base URL, or hermetic agent dir.
+     */
+    extraEnv?: Record<string, string>;
 }
 export declare function buildLaunch(creds: Credentials | null, passthroughArgs: string[], opts: BuildLaunchOptions): LaunchPlan;
 //# sourceMappingURL=launch.d.ts.map

package/dist/launch.js

@@ -1,8 +1,11 @@
 /**
- * Build the configured pi launch. `buildLaunch` is pure (no spawn, no fs) so it
- * is fully unit-testable: it returns the child environment and the pi argv that
- * registers pi-extension-yagni and defaults the provider to `yagni`.
+ * Build the configured pi launch. `buildLaunch` has no spawn/fs side effects,
+ * so it stays fully unit-testable, though it is no longer strictly pure: it
+ * mints a fresh session id (`randomUUID()`) on every call. It returns the
+ * child environment and the pi argv that registers pi-extension-yagni and
+ * defaults the provider to `yagni`.
  */
+import { randomUUID } from "node:crypto";
 import { agentDirEnvVar } from "./branding.js";
 /**
  * How close to expiry the token can be before launch warns. A coding session
@@ -50,6 +53,13 @@ export function buildLaunch(creds, passthroughArgs, opts) {
     }
     const env = {
         ...(opts.baseEnv ?? {}),
+        ...(opts.extraEnv ?? {}),
+        // One session id per launch (YAG-471 attribution). The extension reads this
+        // as YAGNI_SESSION_ID and forwards it as the model proxy's x-yagni-session-id
+        // header on the driver's own completions. /go's children override
+        // YAGNI_CALLER with their own stage/subagent/advisor label but inherit this
+        // session id (unless they also carry a YAGNI_RUN_ID, which wins server-side).
+        YAGNI_SESSION_ID: randomUUID(),
         YAGNI_TOKEN: creds.token,
         YAGNI_BASE_URL: creds.baseUrl,
         // Forward the token's expiry (when known) so the extension can surface a
@@ -62,6 +72,10 @@ export function buildLaunch(creds, passthroughArgs, opts) {
         // atomically persist a mid-session token rotation back to the same profile
         // the launcher read (0600). Absent when the caller can't resolve it.
         ...(opts.profilePath ? { YAGNI_PROFILE_PATH: opts.profilePath } : {}),
+        ...(opts.stateDir ? { YAGNI_CODE_HOME: opts.stateDir } : {}),
+        // Forward the launcher's version so the extension's crash reports carry
+        // the shipping version (the bundled extension has no package.json to read).
+        ...(opts.cliVersion ? { YAGNI_CODE_VERSION: opts.cliVersion } : {}),
         // Rebrand pi's chrome ("pi"/"π" → "YAGNI Code"): pi reads piConfig.name from
         // the package at PI_PACKAGE_DIR (a shadow package the launcher generates).
         ...(opts.piPackageDir ? { PI_PACKAGE_DIR: opts.piPackageDir } : {}),
@@ -85,20 +99,24 @@ export function buildLaunch(creds, passthroughArgs, opts) {
     // Always load our extension. Default the provider to `yagni` unless the user
     // explicitly chose one (so power users can still point pi elsewhere).
     const userChoseProvider = passthroughArgs.some(arg => arg === "--provider" || arg.startsWith("--provider="));
-    // Default the model to the `advanced` tier — the strongest judgment-grade
-    // model, so interactive sessions get the best reasoning by default. A user
-    // `--model` (e.g. `standard` or `efficient`) still wins. Without this, pi's
-    // default-model heuristic could land an interactive session on a weaker tier.
+    // Default the model to the `balanced` tier (YAG-380). Balanced drives on the
+    // judgment-grade `advanced` model and additionally lets the session escalate
+    // hard calls to `peak` through the capped ask_advisor tool. So it is strictly
+    // additive: no session reasons worse than plain advanced, and the hard ones
+    // can reason better. A user `--model` (e.g. `standard` or `efficient`) still
+    // wins. Without this, pi's default-model heuristic could land an interactive
+    // session on a weaker tier.
     // Detect if the user explicitly set a model, whether via "--model" as a separate
     // argument or using the equals form "--model=efficient". The previous check only
-    // caught the separate form, causing a duplicate "--model advanced" to be added
+    // caught the separate form, causing a duplicate "--model balanced" to be added
     // when the equals form was used.
     const userChoseModel = passthroughArgs.some(arg => arg === "--model" || arg.startsWith("--model="));
     const argv = [
         "-e",
         opts.extensionPath,
         ...(userChoseProvider ? [] : ["--provider", "yagni"]),
-        ...(userChoseModel ? [] : ["--model", "advanced"]),
+        ...(userChoseModel ? [] : ["--model", "balanced"]),
+        ...(opts.extraAgentArgs ?? []),
         ...passthroughArgs,
     ];
     return { env, argv, warnings };

package/dist/login.d.ts

@@ -9,6 +9,13 @@ export interface LoginDeps {
     baseUrl?: string;
     /** Which profile to store the minted token in. Defaults to the active one. */
     profileName?: string;
+    /**
+     * Client identifier sent with the token poll so the backend can attribute
+     * the minted credential to the app that requested it. Defaults to "cli";
+     * the desktop shell (which reuses this flow) passes "desktop". The server
+     * treats unknown values as absent, so this can never break a login.
+     */
+    client?: string;
     fetchImpl?: typeof fetch;
     now?: () => number;
     sleep?: (ms: number) => Promise<void>;