@yagni-app/code-staging 1.1.4-staging.1415.1 → 1.1.4-staging.1419.1

package/dist/cli.js

@@ -713,7 +713,7 @@ export const HELP_TEXT = [
     "  yagni version            Print the CLI version.",
     "",
     "Common agent flags (passed straight through):",
-    "  --model <tier>           Model tier (fixed to advanced).",
+    "  --model <tier>           advanced (default) | standard | efficient | peak; /tier switches mid-session.",
     "  --thinking <level>       off | minimal | low | medium | high | xhigh | max",
     "  --session <id>           Open a specific session; --fork <id> branches one.",
     "  --output-format <fmt>    Output format: text (default), json, stream-json.",

package/dist/extension/askAdvisorTool.js

@@ -174,7 +174,9 @@ export function makeAskAdvisorTool(opts) {
             // rides every partial update's `details.tasks` (painted by
             // renderSubagentResult), the plain-text summary rides `content` for
             // headless consumers, and the harness "Working…" line mirrors it.
-            const progress = newTaskProgress("advisor", params.question, Date.now());
+            // A consult always runs on the advisor rung; naming it on the live line
+            // is the point of the escalation being visible at all.
+            const progress = newTaskProgress("advisor", params.question, Date.now(), ADVISOR_MODEL_TIER);
             const ui = ctx?.hasUI ? ctx.ui : undefined;
             let lastWorking;
             const emit = () => {

package/dist/extension/costHud.d.ts

@@ -43,6 +43,41 @@ export interface CostAccumulator {
     snapshot(): CostSnapshot;
     reset(): void;
 }
+/**
+ * Prompt-cache hit rate, as a whole percent, or null when nothing was sent.
+ *
+ * WHY THIS IS A PRODUCT SURFACE, not a debug stat: the pilot objection to
+ * managed routing was that a reroute costs a cache miss and a fresh cache
+ * write, which on a long task is the dominant cost. The honest answer to that
+ * is a measurement, not a promise. A session reading 90%+ settles the question
+ * in a way a stability guarantee never could, and a session reading badly is a
+ * routing bug worth finding.
+ *
+ * Denominator is every prompt token the session sent: cache reads + cache
+ * WRITES + uncached input. Writes belong in it because a write IS the miss
+ * being complained about — leaving them out would flatter exactly the case
+ * this number exists to expose.
+ *
+ * The three buckets are disjoint on both feeds. pi-ai's openai-completions
+ * parser computes `input = prompt_tokens - cached - writes` before the number
+ * ever reaches `turn_end` (so the local accumulator is already disjoint), and
+ * the backend prices `promptTokens`, `cacheReadTokens` and
+ * `cacheCreationTokens` additively at three separate rates
+ * (`costTracker.calculateWithPricing`, `rateCard.priceSellMillicents`), which
+ * is only coherent if they do not overlap. Double-counting here would
+ * understate the rate rather than overstate it, but the denominator is right
+ * as written.
+ *
+ * PURE. Non-finite fields resolve to null rather than "NaN%", matching {@link usd}'s
+ * posture toward an untyped network response. One finiteness check covers every
+ * field: a NaN or Infinity in any bucket poisons `total`, so the guard below
+ * catches it before the division.
+ */
+export declare function cacheHitPercent(snap: {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+}): number | null;
 /** A pure, session-scoped usage accumulator. */
 export declare function makeCostAccumulator(): CostAccumulator;
 /** Extract a normalized {@link UsageDelta} from a turn_end message, defensively. */
@@ -105,6 +140,20 @@ export interface SpendResponse {
  * this exact money formatting instead of duplicating it.
  */
 export declare const usd: (millicents: number) => string;
+/**
+ * Fold a spend response's rows into the three prompt-token buckets
+ * {@link cacheHitPercent} reads. PURE.
+ *
+ * Rows arrive untyped from the network, so a missing or non-numeric field
+ * contributes 0 rather than poisoning the sum into NaN (which would render as
+ * no line at all, the same fail-soft end state, but by accident instead of on
+ * purpose).
+ */
+export declare function spendTokenTotals(spend: SpendResponse): {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+};
 /**
  * Render the server-authoritative /cost lines: PREFERRED over
  * {@link formatCostLine}'s local accumulator whenever the spend fetch succeeds
@@ -115,7 +164,8 @@ export declare const usd: (millicents: number) => string;
  * (joined with "\n").
  *
  * Line order: total spend, one line per rate tier (aggregated across callers,
- * sorted by spend descending), the savings line (only
+ * sorted by spend descending), the prompt-cache hit rate (whenever the session
+ * sent any prompt tokens at all, 0% included), the savings line (only
  * when a counterfactual total resolved), an incomplete-counterfactual note,
  * an unbilled note, a dropped-run-ids note (carry-over from the /cost
  * re-review — see sessionRuns.ts's `droppedSessionRuns`), then headroom.

package/dist/extension/costHud.js

@@ -25,6 +25,42 @@
  * whenever it is shown it is explicitly labeled "(local, driver only)" rather
  * than presented as the whole session's spend.
  */
+/**
+ * Prompt-cache hit rate, as a whole percent, or null when nothing was sent.
+ *
+ * WHY THIS IS A PRODUCT SURFACE, not a debug stat: the pilot objection to
+ * managed routing was that a reroute costs a cache miss and a fresh cache
+ * write, which on a long task is the dominant cost. The honest answer to that
+ * is a measurement, not a promise. A session reading 90%+ settles the question
+ * in a way a stability guarantee never could, and a session reading badly is a
+ * routing bug worth finding.
+ *
+ * Denominator is every prompt token the session sent: cache reads + cache
+ * WRITES + uncached input. Writes belong in it because a write IS the miss
+ * being complained about — leaving them out would flatter exactly the case
+ * this number exists to expose.
+ *
+ * The three buckets are disjoint on both feeds. pi-ai's openai-completions
+ * parser computes `input = prompt_tokens - cached - writes` before the number
+ * ever reaches `turn_end` (so the local accumulator is already disjoint), and
+ * the backend prices `promptTokens`, `cacheReadTokens` and
+ * `cacheCreationTokens` additively at three separate rates
+ * (`costTracker.calculateWithPricing`, `rateCard.priceSellMillicents`), which
+ * is only coherent if they do not overlap. Double-counting here would
+ * understate the rate rather than overstate it, but the denominator is right
+ * as written.
+ *
+ * PURE. Non-finite fields resolve to null rather than "NaN%", matching {@link usd}'s
+ * posture toward an untyped network response. One finiteness check covers every
+ * field: a NaN or Infinity in any bucket poisons `total`, so the guard below
+ * catches it before the division.
+ */
+export function cacheHitPercent(snap) {
+    const total = snap.input + snap.cacheRead + snap.cacheWrite;
+    if (!Number.isFinite(total) || total <= 0)
+        return null;
+    return Math.round((snap.cacheRead / total) * 100);
+}
 /** A pure, session-scoped usage accumulator. */
 export function makeCostAccumulator() {
     let s = { turns: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
@@ -77,7 +113,11 @@ const fmt = (n) => n.toLocaleString("en-US");
  */
 export function formatCostLine(snap, headroom, advisorLine, source) {
     const turns = `${snap.turns} turn${snap.turns === 1 ? "" : "s"}`;
-    const cached = snap.cacheRead > 0 ? ` (${fmt(snap.cacheRead)} cached)` : "";
+    // Gated on "did this session send anything", NOT on "did it read any cache".
+    // A cold session is precisely the case the hit rate exists to expose, so
+    // hiding the segment at 0 would suppress the only bad news it can carry.
+    const hit = cacheHitPercent(snap);
+    const cached = hit === null ? "" : ` (${fmt(snap.cacheRead)} cached, ${hit}% hit)`;
     const label = source ? `Session usage (${source})` : "Session usage";
     const base = `${label}: ${turns}, ${fmt(snap.input)} in / ${fmt(snap.output)} out tokens${cached}, ` +
         `$${snap.cost.toFixed(2)} this session.`;
@@ -102,6 +142,27 @@ export const usd = (millicents) => {
         return "0.00";
     return (millicents / 100_000).toFixed(2);
 };
+/**
+ * Fold a spend response's rows into the three prompt-token buckets
+ * {@link cacheHitPercent} reads. PURE.
+ *
+ * Rows arrive untyped from the network, so a missing or non-numeric field
+ * contributes 0 rather than poisoning the sum into NaN (which would render as
+ * no line at all, the same fail-soft end state, but by accident instead of on
+ * purpose).
+ */
+export function spendTokenTotals(spend) {
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+    let input = 0;
+    let cacheRead = 0;
+    let cacheWrite = 0;
+    for (const row of spend.rows ?? []) {
+        input += num(row?.promptTokens);
+        cacheRead += num(row?.cacheReadTokens);
+        cacheWrite += num(row?.cacheCreationTokens);
+    }
+    return { input, cacheRead, cacheWrite };
+}
 /**
  * Render the server-authoritative /cost lines: PREFERRED over
  * {@link formatCostLine}'s local accumulator whenever the spend fetch succeeds
@@ -112,7 +173,8 @@ export const usd = (millicents) => {
  * (joined with "\n").
  *
  * Line order: total spend, one line per rate tier (aggregated across callers,
- * sorted by spend descending), the savings line (only
+ * sorted by spend descending), the prompt-cache hit rate (whenever the session
+ * sent any prompt tokens at all, 0% included), the savings line (only
  * when a counterfactual total resolved), an incomplete-counterfactual note,
  * an unbilled note, a dropped-run-ids note (carry-over from the /cost
  * re-review — see sessionRuns.ts's `droppedSessionRuns`), then headroom.
@@ -134,6 +196,14 @@ export function formatServerCostLines(spend, headroom, droppedRunCount = 0) {
         const calls = `${fmt(agg.dispatches)} call${agg.dispatches === 1 ? "" : "s"}`;
         lines.push(`  ${tier}: $${usd(agg.sellMillicents)} over ${calls}.`);
     }
+    // The whole-session cache hit rate, children included. This is the better
+    // of the two feeds for the question it answers: the local accumulator only
+    // ever sees driver turns, while the long, context-heavy work that makes
+    // cache continuity matter is exactly what runs in /go stages and subagents.
+    const hit = cacheHitPercent(spendTokenTotals(spend));
+    if (hit !== null) {
+        lines.push(`Prompt cache: ${hit}% of sent tokens served from cache.`);
+    }
     // typeof guard (not just !== null): a network response is untyped at
     // runtime, and a stray string/boolean here must never sneak "NN%" into the
     // rendered line.

package/dist/extension/errorSink.d.ts

@@ -32,7 +32,7 @@
  */
 export type SinkLevel = "error" | "warn" | "info" | "debug";
 export interface SinkEvent {
-    /** Former filename / subsystem: tool, turn, guardian, image-paste, ask-question, cost, auth, cmux, hooks. */
+    /** Former filename / subsystem: tool, turn, guardian, image-paste, ask-question, cost, auth, cmux, hooks, tier. */
     source: string;
     level: SinkLevel;
     /** Stable machine name (e.g. "turn_start", "bash.exit_1", "denied"). */

package/dist/extension/index.d.ts

@@ -214,7 +214,9 @@ export { makeDecisionCapture, CAPTURE_DEBOUNCE_MS } from "./decisionCapture.js";
 export type { DecisionCapture, DecisionCaptureDeps, BlessCaptureInfo, CaptureCtx } from "./decisionCapture.js";
 export { registerAmbientRecall, fetchRecall, formatRecallBlock, toRepoRelativePath, normalizeRecall, RECALL_TIMEOUT_MS, RECALL_MIN_DECISIONS, } from "./recall.js";
 export type { RecallResult, RecallClientOpts, RegisterRecallDeps } from "./recall.js";
-export { makeCostAccumulator, formatCostLine, registerCostCommand } from "./costHud.js";
+export { makeCostAccumulator, formatCostLine, registerCostCommand, cacheHitPercent, spendTokenTotals, } from "./costHud.js";
+export { SELECTABLE_TIERS, SESSION_START_TIER, formatStartCorrection, formatStartCorrectionFailed, formatTierStatus, formatTierSwitchFailed, formatTierSwitched, isSelectableTier, orderDriverCatalog, parseTierArg, registerStartTierGuard, registerTierCommand, startTierCorrection, } from "./tierCommand.js";
+export type { SelectableTier, TierRequest } from "./tierCommand.js";
 export type { CostSnapshot, Headroom } from "./costHud.js";
 export { makeTokenProvider, makeAuthedFetch, persistRotationToProfile, PROACTIVE_REFRESH_WINDOW_MS, REFRESH_RETRY_MS, } from "./tokenProvider.js";
 export type { TokenProvider, TokenProviderDeps, ScheduleFn } from "./tokenProvider.js";

package/dist/extension/index.js

@@ -17,7 +17,7 @@ import { makeRecordDecisionTool } from "./recordDecisionTool.js";
 import { makeSuggestNextWorkTool } from "./nextWorkTool.js";
 import { BRAND_NAME, brandSystemPrompt, brandingDisabled, buildMastheadString, YAGNI_IDENTITY_DRIVER, YAGNI_IDENTITY_DRIVER_GROUNDING_FREE, YAGNI_IDENTITY_GROUNDING_FREE, YAGNI_IDENTITY_ULTRA, YAGNI_IDENTITY_ULTRA_GROUNDING_FREE } from "./branding.js";
 import { claudeRulesSection } from "./claudeRules.js";
-import { ensureScratchpadDir, SCRATCHPAD_TMPDIR_ENV, scratchpadDir as scratchpadDirFor, scratchpadSection } from "./scratchpad.js";
+import { ensureScratchpadDir, SCRATCHPAD_TMPDIR_ENV, scratchpadDir as scratchpadDirFor, scratchpadOwnerRootFor, scratchpadSection } from "./scratchpad.js";
 import { registerCostCommand } from "./costHud.js";
 import { isDebug } from "./diagnostics.js";
 import { logEvent } from "./errorSink.js";
@@ -61,6 +61,7 @@ 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 { orderDriverCatalog, registerStartTierGuard, registerTierCommand } from "./tierCommand.js";
 import { registerChipEditor } from "./chipEditor.js";
 import { registerSlashCommandFilter } from "./slashCommandFilter.js";
 import { defaultMineBeatGit, fileMineBeatMarkers, maybeOfferMiningBeat as defaultMaybeOfferMiningBeat, } from "./mineBeat.js";
@@ -290,9 +291,16 @@ export async function registerYagni(pi, deps = {}) {
             fields: { reason: !userGrounding ? "user_config" : "workspace" },
         });
     }
-    // Lock the interactive session to the `advanced` tier only. The backend
-    // catalog returns all tiers, but only `advanced` is registered with the
-    // `yagni` provider, so /model and Ctrl+P show a single entry.
+    // The interactive session's picker: the four concrete rungs, in the order
+    // `tierCommand.ts` defines (advanced first, peak last). The backend catalog
+    // also returns `balanced`, which is a session routing POLICY rather than a
+    // rung, so it is dropped here — five entries would read as five tiers.
+    //
+    // This used to be an `advanced`-only filter, i.e. a single-entry picker and
+    // a fixed rung. Pilot feedback asked for a visible manual dial, so the rung
+    // is now the developer's to move; `registerStartTierGuard` keeps every
+    // session OPENING on `advanced` and never on `peak` (see tierCommand.ts for
+    // why peak is reachable but never a resting state).
     //
     // Two exemptions:
     // - CHILD processes: the runner stamps YAGNI_CALLER on every /go, subagent,
@@ -302,13 +310,14 @@ export async function registerYagni(pi, deps = {}) {
     //   catalog — the advanced-only filter used to leave those tier names
     //   unresolved, so pi fell back to its custom-model-id path (a stderr
     //   warning on every non-advanced child and default-shaped capability
-    //   metadata instead of the real context-window/token caps).
+    //   metadata instead of the real context-window/token caps). A child also
+    //   must keep resolving `balanced`, which the driver ordering drops.
     // - Eval mode: a headless harness (scoping sessions, code evals) names its
     //   tier explicitly — the backend's scoping sessions run `--model standard`
     //   — and there is no /model picker to keep tidy. Filtering there turns a
     //   valid tier request into "no models match".
     const driver = isDriverCaller(env);
-    const catalog = evalMode || !driver ? fullCatalog : fullCatalog.filter((m) => m.id === "advanced");
+    const catalog = evalMode || !driver ? fullCatalog : orderDriverCatalog(fullCatalog);
     // 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
@@ -1165,6 +1174,15 @@ export async function registerYagni(pi, deps = {}) {
         // count as costHud's "Excludes N earlier /go runs." note.
         droppedSessionRuns,
     });
+    // The manual tier dial. `/model` (pi's own picker) now lists the four rungs
+    // because the driver catalog carries them; `/tier` is the tier-language
+    // sibling that reports and switches inline. The start guard is what keeps
+    // "movable" from becoming "parked on peak" — driver sessions only, since a
+    // child or eval lane names its tier on the command line.
+    if (!evalMode && driver) {
+        registerTierCommand(pi);
+        registerStartTierGuard(pi);
+    }
     // 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
@@ -1321,24 +1339,69 @@ export async function registerYagni(pi, deps = {}) {
     // so the very first turn already carries the section. Fails closed: no
     // sessionId (a bare pi run) or a failed mkdir means no section, and the mkdir
     // failure is logged so a missing scratchpad is not silent.
+    const scratchpadTmpRoot = env[SCRATCHPAD_TMPDIR_ENV] || undefined;
     const scratchpadDirPath = scratchpadDirFor({
         sessionId: env.YAGNI_SESSION_ID ?? undefined,
         cwd: process.cwd(),
-        tmp: env[SCRATCHPAD_TMPDIR_ENV] || undefined,
+        tmp: scratchpadTmpRoot,
     });
     let scratchpadSectionText;
     if (scratchpadDirPath) {
-        const ensured = ensureScratchpadDir(scratchpadDirPath);
+        const ensured = ensureScratchpadDir(scratchpadDirPath, undefined, {
+            onError: (errorCode) => {
+                logEvent({
+                    source: "scratchpad",
+                    level: "error",
+                    event: "scratchpad_mkdir_failed",
+                    sessionId: env.YAGNI_SESSION_ID ?? undefined,
+                    fields: { path: scratchpadDirPath, errorCode },
+                });
+            },
+        });
         if (ensured) {
             scratchpadSectionText = scratchpadSection(ensured);
-        }
-        else {
-            logEvent({
-                source: "scratchpad",
-                level: "error",
-                event: "scratchpad_mkdir_failed",
-                sessionId: env.YAGNI_SESSION_ID ?? undefined,
-            });
+            // Claude Code parity: srt reads CLAUDE_CODE_TMPDIR from THIS process's
+            // env when wrapping a sandboxed bash command and forces the child's
+            // TMPDIR onto it. Point it at the per-user scratchpad OWNER ROOT (not
+            // the scratchpad itself) so sandboxed-bash temp files land in the same
+            // per-user tree the scratchpad lives in, under a path SHORT enough for
+            // named unix-socket binds (the test-runner IPC pattern — a deep
+            // scratchpad TMPDIR trips macOS's 104-char sun_path limit with EINVAL).
+            // The scratchpad remains the sanctioned staging place by PRIORITY (the
+            // prompt section outranks $TMPDIR), not by path convergence.
+            //
+            // Production note: children (subagents, /go stages) inherit this env
+            // because `env` IS process.env there and the runner spawns with it. A
+            // harness injecting deps.env sees the write only in that object —
+            // spawned children of such a harness do not, by construction of the
+            // runner's own env seam.
+            //
+            // Unset when there is no scratchpad (no session id, or the mkdir
+            // failed) — srt keeps its /tmp/claude default and nothing changes for
+            // those sessions.
+            if (!env.CLAUDE_CODE_TMPDIR) {
+                const ownerRoot = scratchpadOwnerRootFor({ tmp: scratchpadTmpRoot });
+                env.CLAUDE_CODE_TMPDIR = ownerRoot;
+                logEvent({
+                    source: "scratchpad",
+                    level: "info",
+                    event: "scratchpad_tmpdir_pinned",
+                    sessionId: env.YAGNI_SESSION_ID ?? undefined,
+                    fields: { path: ownerRoot },
+                });
+            }
+            else {
+                // The trail must distinguish "pinned" from "respected an operator
+                // override" — no path value here (the explicit value is the
+                // operator's, not ours to echo).
+                logEvent({
+                    source: "scratchpad",
+                    level: "info",
+                    event: "scratchpad_tmpdir_pin_skipped",
+                    sessionId: env.YAGNI_SESSION_ID ?? undefined,
+                    fields: {},
+                });
+            }
         }
     }
     // The condensed Claude Code-style transcript: the seven built-ins re-render
@@ -1898,7 +1961,8 @@ 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";
+export { makeCostAccumulator, formatCostLine, registerCostCommand, cacheHitPercent, spendTokenTotals, } from "./costHud.js";
+export { SELECTABLE_TIERS, SESSION_START_TIER, formatStartCorrection, formatStartCorrectionFailed, formatTierStatus, formatTierSwitchFailed, formatTierSwitched, isSelectableTier, orderDriverCatalog, parseTierArg, registerStartTierGuard, registerTierCommand, startTierCorrection, } from "./tierCommand.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";

package/dist/extension/sandbox/session.js

@@ -118,8 +118,10 @@ export function makeBashComposition(manager, settings, cwd, onShellResolutionRet
         const heredocNote = "Caveat: heredocs (<<EOF) write temp files relative to the current directory on macOS bash 3.2 — from an unwritable cwd they fail; prefer printf or redirect from a file in the working directory.";
         // $TMPDIR guidance (Claude Code parity, always-on): the sandbox sets
         // TMPDIR to the per-user sandbox-writable temp dir; /tmp itself is NOT
-        // writable.
-        const tmpdirNote = "For temporary files, always use the $TMPDIR environment variable. TMPDIR is automatically set to the correct sandbox-writable directory in sandbox mode. Do NOT use /tmp directly - use $TMPDIR instead.";
+        // writable. When the system prompt names a scratchpad directory, that
+        // directory takes priority for temporary files — stated here so the two
+        // guidance lines never read as mutually exclusive always-rules.
+        const tmpdirNote = "For temporary files, use the $TMPDIR environment variable unless your system prompt names a scratchpad directory — the scratchpad takes priority for temporary files. TMPDIR is automatically set to the correct sandbox-writable directory in sandbox mode. Do NOT use /tmp directly - use $TMPDIR instead.";
         const wrapped = {
             ...def,
             description: `${def.description}\n\n## Command sandbox\nCommands run inside an OS sandbox: ${restrictions.join("; ")}. ${strictNote}\n${heredocNote}\n${tmpdirNote}`,

package/dist/extension/scratchpad.d.ts

@@ -48,6 +48,18 @@ export declare function scratchpadDir(opts?: {
     uid?: number;
     tmp?: string;
 }): string | null;
+/**
+ * PURE: the per-user scratchpad OWNER ROOT, recomputed from the SAME inputs
+ * `scratchpadDir` resolves from (never derived by stripping segments off a
+ * built path — a layout change would silently shift a stripped spelling).
+ * The value the sandbox forces TMPDIR onto (Claude parity): per-user, shared
+ * across sessions, and short enough for named unix-socket binds where the
+ * deep scratchpad path would trip macOS's 104-char sun_path limit.
+ */
+export declare function scratchpadOwnerRootFor(opts?: {
+    uid?: number;
+    tmp?: string;
+}): string;
 /**
  * IMPURE: ensure the scratchpad dir exists (owner-only), failing soft. Returns
  * the path on success and null on failure — a null result means "no scratchpad
@@ -56,7 +68,9 @@ export declare function scratchpadDir(opts?: {
 export declare function ensureScratchpadDir(path: string, mkdir?: (p: string, o: {
     mode: number;
     recursive: boolean;
-}) => void): string | null;
+}) => void, opts?: {
+    onError?: (errorCode: string) => void;
+}): string | null;
 /**
  * PURE: the prompt section naming the scratchpad. Gated by the caller on the
  * dir existing; when present, it tells the agent where to put intermediate

package/dist/extension/scratchpad.js

@@ -61,17 +61,39 @@ export function scratchpadDir(opts = {}) {
     const cwd = sanitizeCwdSegment(opts.cwd ?? ".");
     return join(tmp, scratchpadOwnerDir(uid), cwd, sessionId, "scratchpad");
 }
+/**
+ * PURE: the per-user scratchpad OWNER ROOT, recomputed from the SAME inputs
+ * `scratchpadDir` resolves from (never derived by stripping segments off a
+ * built path — a layout change would silently shift a stripped spelling).
+ * The value the sandbox forces TMPDIR onto (Claude parity): per-user, shared
+ * across sessions, and short enough for named unix-socket binds where the
+ * deep scratchpad path would trip macOS's 104-char sun_path limit.
+ */
+export function scratchpadOwnerRootFor(opts = {}) {
+    const tmp = opts.tmp ?? tmpdir();
+    const uid = opts.uid ?? (typeof process.getuid === "function" ? process.getuid() ?? 0 : 0);
+    return join(tmp, scratchpadOwnerDir(uid));
+}
 /**
  * IMPURE: ensure the scratchpad dir exists (owner-only), failing soft. Returns
  * the path on success and null on failure — a null result means "no scratchpad
  * this session", which the caller turns into an omitted prompt section.
  */
-export function ensureScratchpadDir(path, mkdir = mkdirSync) {
+export function ensureScratchpadDir(path, mkdir = mkdirSync, opts = {}) {
     try {
         mkdir(path, { recursive: true, mode: 0o700 });
         return path;
     }
-    catch {
+    catch (err) {
+        // The errno CODE (never the thrown message — the message can carry a
+        // path or system detail, and the caller forwards this to the sink).
+        // fs errors are plain Error instances whose distinguishing value is
+        // .code (ENOTDIR vs EACCES vs EPERM...); the constructor name would
+        // always read "Error" and distinguish nothing. The fallback keeps the
+        // class name for codeless throws (a non-fs throw), so the callback's
+        // value is "errno code, or class name when there is no code".
+        const code = err?.code;
+        opts.onError?.(code ?? (err instanceof Error ? err.constructor.name : typeof err));
         return null;
     }
 }
@@ -82,12 +104,13 @@ export function ensureScratchpadDir(path, mkdir = mkdirSync) {
  */
 export function scratchpadSection(dir) {
     return ("# Scratchpad directory\n\n" +
-        `Use this session scratchpad directory for files that do not belong in the user's project:\n` +
+        `IMPORTANT: Always use this scratchpad directory for temporary files instead of /tmp or other system temp directories (including $TMPDIR in sandboxed bash):\n` +
         `${dir}\n\n` +
+        "Use this directory for ALL temporary file needs:\n" +
         "- Store intermediate results or data during multi-step tasks.\n" +
         "- Write temporary scripts or configuration files.\n" +
         "- Save outputs that don't belong in the user's project.\n" +
-        "- Anything that would otherwise go to /tmp.\n\n" +
+        "- Staging files for subagents: paths in this directory are readable by every subagent of this session, so hand subagents scratchpad paths rather than $TMPDIR or /tmp paths.\n\n" +
         "The directory is session-specific and isolated from the user's project.");
 }
 //# sourceMappingURL=scratchpad.js.map

package/dist/extension/subagentRender.d.ts

@@ -17,7 +17,7 @@
  * the bare title bar), so everything here must stay boringly total.
  */
 import { type Component } from "@earendil-works/pi-tui";
-import type { JsonEvent, StageResult, StageUsage } from "./pipeline/types.js";
+import type { JsonEvent, ModelTier, StageResult, StageUsage } from "./pipeline/types.js";
 /** The minimal slice of pi's `Theme` the renderers style with (same shape as FeedTheme). */
 export interface RenderTheme {
     bold(text: string): string;
@@ -35,6 +35,21 @@ export interface SubagentActionEntry {
 export interface SubagentTaskProgress {
     agent: string;
     task: string;
+    /**
+     * The rung this child runs on, shown on both the live line and the receipt.
+     *
+     * This is the visible half of managed routing. A fan-out that quietly puts
+     * wide search on `efficient` and mechanical edits on `standard` is doing
+     * exactly the cost work the tiers exist for, and until it is printed the
+     * developer has to take that on faith. Seeded from the agent definition at
+     * spawn (so it shows while the child is still running) and re-stamped from
+     * the child's own `StageResult` on completion, which is what reflects a
+     * `YAGNI_GO_TIER_CAP` clamp.
+     *
+     * Optional: a caller-injected runStage seam (unit tests, a custom lane)
+     * need not report one, and the renderers simply omit the segment.
+     */
+    tier?: ModelTier;
     status: "running" | "done" | "error";
     /** -1 while the child is still running (mirrors the pi subagent example). */
     exitCode: number;
@@ -58,7 +73,7 @@ export interface SubagentDetails {
 }
 /** Bound on the retained action log so a chatty child cannot grow details unbounded. */
 export declare const ACTION_LOG_MAX = 120;
-export declare function newTaskProgress(agent: string, task: string, startedAt: number): SubagentTaskProgress;
+export declare function newTaskProgress(agent: string, task: string, startedAt: number, tier?: ModelTier): SubagentTaskProgress;
 /**
  * Fold one child NDJSON event into the task's progress. Returns true when the
  * record changed (the tool emits an update), false for events we drop.
@@ -75,7 +90,7 @@ export declare function formatDuration(ms: number): string;
  * over the churning current-action line with elapsed time and live tokens.
  */
 export declare function runningLines(p: SubagentTaskProgress, theme: RenderTheme, now: number, frame: string): string[];
-/** One-line completion receipt: `✓ agent · N tool uses · Xk tokens · Ys · $c`. */
+/** One-line completion receipt: `✓ agent · tier · N tool uses · Xk tokens · Ys · $c`. */
 export declare function receiptLine(p: SubagentTaskProgress, theme: RenderTheme): string;
 /**
  * Plain-text (no theme) summary for the partial result's `content`, so headless

package/dist/extension/subagentRender.js

@@ -31,10 +31,11 @@ const TASK_PREVIEW_MAX = 64;
 /** Spinner cadence; matches the /go feed's SPINNER_TICK_MS. */
 const SPINNER_TICK_MS = 120;
 const EMPTY_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
-export function newTaskProgress(agent, task, startedAt) {
+export function newTaskProgress(agent, task, startedAt, tier) {
     return {
         agent,
         task,
+        ...(tier ? { tier } : {}),
         status: "running",
         exitCode: -1,
         startedAt,
@@ -122,6 +123,12 @@ export function finalizeTask(p, result, endedAt) {
     // An aborted child can close with exit 0 (SIGTERM close reports a null code),
     // so the stop reason outranks the exit code for the status glyph.
     p.status = result.exitCode === 0 && result.stopReason !== "aborted" ? "done" : "error";
+    // The tier the child ACTUALLY ran on outranks the one seeded at spawn: a
+    // capped lane (`YAGNI_GO_TIER_CAP`) clamps the rung after the fact, and the
+    // receipt must show what was billed, not what was asked for. Keep the seed
+    // when the seam reported none.
+    if (result.tier)
+        p.tier = result.tier;
     p.exitCode = result.exitCode;
     p.endedAt = endedAt;
     p.usage = { ...result.usage };
@@ -190,15 +197,20 @@ function liveDetailText(p) {
 export function runningLines(p, theme, now, frame) {
     const title = `${frame} ${theme.fg("accent", p.agent)} — ${theme.fg("dim", clip(p.task, TASK_PREVIEW_MAX))}`;
     let detail = `  ${theme.fg("muted", "↳")} ${theme.fg("toolOutput", liveDetailText(p))}`;
+    if (p.tier)
+        detail += theme.fg("dim", ` · ${p.tier}`);
     detail += theme.fg("dim", ` · ${formatDuration(now - p.startedAt)}`);
     const tokens = taskTokens(p);
     if (tokens > 0)
         detail += theme.fg("dim", ` · ${formatTokens(tokens)} tokens`);
     return [title, detail];
 }
-/** One-line completion receipt: `✓ agent · N tool uses · Xk tokens · Ys · $c`. */
+/** One-line completion receipt: `✓ agent · tier · N tool uses · Xk tokens · Ys · $c`. */
 export function receiptLine(p, theme) {
     const parts = [
+        // Tier leads the dim run: it is the thing a developer is scanning for when
+        // they want to know the fan-out went out cheap.
+        ...(p.tier ? [p.tier] : []),
         countToolUses(p.toolCalls),
         `${formatTokens(taskTokens(p))} tokens`,
         formatDuration((p.endedAt ?? p.startedAt) - p.startedAt),

package/dist/extension/subagents.js

@@ -601,7 +601,10 @@ export function makeSubagentTool(deps = {}) {
             // `details` (rendered by renderSubagentResult), the plain-text summary
             // rides `content` (pi's fallback renderer and headless consumers), and
             // the harness "Working…" line mirrors the aggregate while children run.
-            const progresses = resolved.map(({ def, task }) => newTaskProgress(def.name, task, Date.now()));
+            // `def.model` is the agent's declared rung, so the live line names the
+            // tier from the moment the child spins up rather than only on the
+            // receipt (finalizeTask re-stamps it from the child's own result).
+            const progresses = resolved.map(({ def, task }) => newTaskProgress(def.name, task, Date.now(), def.model));
             const ui = ctx?.hasUI ? ctx.ui : undefined;
             let lastWorking;
             const emit = () => {

package/dist/extension/tierCommand.d.ts

@@ -0,0 +1,183 @@
+/**
+ * `/tier` — the session's rung, named and switchable.
+ *
+ * Background. The driver session used to register exactly one model with the
+ * `yagni` provider (`advanced`), so pi's built-in `/model` picker and Ctrl+P
+ * showed a single entry and the rung was effectively fixed. Pilot feedback
+ * (the "managed vs. manual" thread) was not really a request for specific
+ * model ids: it was a request for a VISIBLE, manual dial and for the tier in
+ * play to be legible at a glance. So the driver catalog now carries the four
+ * concrete rungs and this module adds the tier-language command on top of
+ * pi's model picker.
+ *
+ * Two deliberate constraints, both encoded here rather than left to the
+ * launcher:
+ *
+ *   - **A session DEFAULTS to `advanced`.** The launcher injects `--model
+ *     advanced` when the user named no model (launch.ts). That is the whole
+ *     of the default: a session that explicitly asks for another rung gets
+ *     it, since `--model standard` (the backend's scoping sessions) is a
+ *     legitimate request and not something to override.
+ *   - **A session never STARTS on `peak`**, whatever asked for it.
+ *     {@link startTierCorrection} is the belt-and-braces half the launcher
+ *     flag cannot reach: a resume, a persisted picker choice, or an explicit
+ *     `--model peak` all open on `advanced` instead. Peak is the deliberate
+ *     escape hatch, not a place to park: it is the thinnest-margin rung and
+ *     the one a session left sitting on would quietly bill several times
+ *     over. It stays reachable in one keystroke (`/tier peak`) and is never
+ *     the resting state. `/advise` remains the capped, per-question
+ *     escalation for people who want peak judgment without moving the whole
+ *     session.
+ *
+ * `balanced` is deliberately NOT selectable. It names a session routing
+ * POLICY rather than a rung (see `pipeline/tierCap.ts` and `mapModelTier` in
+ * subagents.ts, which exclude it for the same reason), and offering a policy
+ * alongside four rungs in one picker makes the list read as five tiers.
+ *
+ * Pure helpers first, wiring last — the same split as `permission.ts` and
+ * `advisor.ts`, so the rules are testable without a pi session.
+ *
+ * LOGGING. This module writes `source: "tier"` to the error sink, with three
+ * events: `start_tier_corrected` (info) and `start_tier_correction_failed`
+ * (warn) from the session_start guard, and `tier_switch_failed` (warn) from
+ * the command. All three are TRAIL-ONLY: nothing downstream parses them, and
+ * they exist so `/diagnostics` and a support session can answer "why is this
+ * session on peak" after the fact. A rung that failed to move is invisible in
+ * every other record, which is why the failures log at all.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** The provider the tier models are registered under (see provider.ts). */
+export declare const YAGNI_PROVIDER = "yagni";
+/**
+ * The rungs a driver session may sit on, in PICKER ORDER.
+ *
+ * Order is the product statement, not an accident: the default leads, the two
+ * cheaper rungs follow, and `peak` sits last. The backend catalog's own order
+ * is strongest-first (`balanced`, `peak`, `advanced`, ...), which would put
+ * peak in the first, most-clickable position of a picker it should never be
+ * the resting state of.
+ */
+export declare const SELECTABLE_TIERS: readonly ["advanced", "standard", "efficient", "peak"];
+export type SelectableTier = (typeof SELECTABLE_TIERS)[number];
+/** The rung every interactive driver session opens on. */
+export declare const SESSION_START_TIER: SelectableTier;
+export declare function isSelectableTier(value: string | undefined): value is SelectableTier;
+/**
+ * The driver's picker catalog: the four rungs, in {@link SELECTABLE_TIERS}
+ * order, filtered against what the backend actually served.
+ *
+ * Filtering against the live catalog rather than returning SELECTABLE_TIERS
+ * verbatim matters: a workspace whose catalog omits a rung (an entitlement,
+ * a backend that dropped one) must not get a picker entry that 404s on first
+ * use. Anything the backend serves that is not a selectable rung (`balanced`)
+ * is dropped.
+ */
+export declare function orderDriverCatalog<T extends {
+    id: string;
+}>(models: readonly T[]): T[];
+/**
+ * The rung a starting session must be moved to, or null to leave it alone.
+ *
+ * Returns the start tier when the session would otherwise open on a
+ * never-start rung. A session opening on any other selectable rung is left
+ * as-is: an explicit `--model standard` (the backend's scoping sessions) is a
+ * legitimate choice, and only `peak` is the one we refuse to rest on.
+ *
+ * PURE. Callers decide whether the correction applies to them at all —
+ * children and eval lanes name their tier on the command line and are exempt.
+ */
+export declare function startTierCorrection(currentId: string | undefined): SelectableTier | null;
+/** What `/tier <args>` was asking for. PURE. */
+export type TierRequest = {
+    kind: "show";
+} | {
+    kind: "set";
+    tier: SelectableTier;
+} | {
+    kind: "unknown";
+    input: string;
+};
+export declare function parseTierArg(args: string): TierRequest;
+/** The `/tier` status line: what is in play, and what else is reachable. PURE. */
+export declare function formatTierStatus(currentId: string | undefined): string;
+/** The notice shown when a switch lands. PURE. */
+export declare function formatTierSwitched(tier: SelectableTier): string;
+/** Upper bound on a trail `reason`, in characters. */
+export declare const TRAIL_REASON_MAX = 180;
+/**
+ * Turn a caught value into a trail-safe `reason`. PURE.
+ *
+ * A provider's `err.message` is untrusted text on its way to a DURABLE file
+ * that a developer may later paste into a support thread, so it is scrubbed
+ * and bounded at write time rather than trusted to be short and clean.
+ *
+ * Redaction delegates to {@link scrubSecrets}, the pattern set already used
+ * for captured command output: it covers provider key prefixes (sk-, gh*_,
+ * xox*, AKIA, AIza), connection-string credentials, secret-named keys,
+ * base64/JWT blobs, and opaque bearer tokens. An earlier version of this
+ * function hand-rolled a keyword-anchored regex, which missed a bare
+ * `Bearer sk-live-…` with no preceding key name, missed a bare `key=` (it
+ * only matched `api_key`), and would have drifted from the shared set over
+ * time. Order matters: redaction runs BEFORE truncation, so a secret cannot
+ * survive by sitting past the cut.
+ *
+ * Then made readable, then bounded. A streamed provider error arrives with
+ * whatever the terminal put in it (ANSI colour and cursor codes survive a
+ * whitespace collapse and garble the entry, or move the cursor of whatever
+ * later cats the log) and can carry a whole response body; the sink rotates
+ * at 256KB, so an unbounded message evicts the surrounding context that makes
+ * it readable.
+ *
+ * A non-Error resolves to "threw": there is nothing to quote, and inventing
+ * a String(err) of an arbitrary thrown value is how "[object Object]" ends up
+ * in a log.
+ */
+export declare function trailReason(err: unknown): string;
+/** The notice shown when a requested switch did not land. PURE. */
+export declare function formatTierSwitchFailed(requested: SelectableTier, currentId: string | undefined): string;
+/** The notice shown when a session is corrected off a never-start rung. PURE. */
+export declare function formatStartCorrection(from: string, to: SelectableTier): string;
+/**
+ * Register `/tier`.
+ *
+ * pi already ships `/model` (and Ctrl+P), which now lists the four rungs
+ * because the driver catalog carries them — that surface is left entirely to
+ * pi rather than shadowed with a same-named command. `/tier` is the
+ * tier-language sibling: it reports the current rung inline without opening a
+ * picker, and switches in one line when the rung is already known.
+ *
+ * `setModel` resolves through `ctx.modelRegistry.find`, so a rung the
+ * workspace's catalog never registered fails with a real message instead of
+ * silently selecting nothing.
+ */
+export declare function registerTierCommand(pi: ExtensionAPI): void;
+/**
+ * The notice shown when the correction could not be applied. PURE.
+ *
+ * Two sentences on purpose, and in this order. The failure is stated first
+ * without a cause, because the cause varies (a registry miss, a refusal, a
+ * thrown provider call) and none of them is about pricing; then the standing
+ * fact about the rung, which is true whatever went wrong and is the reason
+ * the developer should care at all. The earlier single-sentence phrasing
+ * fused the two and read as though pricing had caused the failure.
+ */
+export declare function formatStartCorrectionFailed(from: string): string;
+/**
+ * Hold an interactive driver to {@link SESSION_START_TIER} at session start.
+ *
+ * Wired on `session_start` so it sees the model the session actually resolved
+ * (flag, persisted choice, or resume) rather than the one the launcher asked
+ * for. Fail-soft in the same spirit as the rest of the extension's
+ * session_start work: a registry miss, a rejected `setModel` or a thrown
+ * handler leaves the session on whatever it opened with rather than taking
+ * the session down.
+ *
+ * Fail-soft is NOT fail-silent. The whole point of the guard is that nobody
+ * drives a long session on the thinnest-margin rung by accident, so a failed
+ * correction is the one case that must not pass unremarked: every exit path
+ * logs (with the rung it could not move off), and the user is told plainly
+ * that they are on peak and how to leave. A silent failure here would bill
+ * exactly like the bug the guard exists to prevent.
+ */
+export declare function registerStartTierGuard(pi: ExtensionAPI): void;
+//# sourceMappingURL=tierCommand.d.ts.map

package/dist/extension/tierCommand.js

@@ -0,0 +1,381 @@
+/**
+ * `/tier` — the session's rung, named and switchable.
+ *
+ * Background. The driver session used to register exactly one model with the
+ * `yagni` provider (`advanced`), so pi's built-in `/model` picker and Ctrl+P
+ * showed a single entry and the rung was effectively fixed. Pilot feedback
+ * (the "managed vs. manual" thread) was not really a request for specific
+ * model ids: it was a request for a VISIBLE, manual dial and for the tier in
+ * play to be legible at a glance. So the driver catalog now carries the four
+ * concrete rungs and this module adds the tier-language command on top of
+ * pi's model picker.
+ *
+ * Two deliberate constraints, both encoded here rather than left to the
+ * launcher:
+ *
+ *   - **A session DEFAULTS to `advanced`.** The launcher injects `--model
+ *     advanced` when the user named no model (launch.ts). That is the whole
+ *     of the default: a session that explicitly asks for another rung gets
+ *     it, since `--model standard` (the backend's scoping sessions) is a
+ *     legitimate request and not something to override.
+ *   - **A session never STARTS on `peak`**, whatever asked for it.
+ *     {@link startTierCorrection} is the belt-and-braces half the launcher
+ *     flag cannot reach: a resume, a persisted picker choice, or an explicit
+ *     `--model peak` all open on `advanced` instead. Peak is the deliberate
+ *     escape hatch, not a place to park: it is the thinnest-margin rung and
+ *     the one a session left sitting on would quietly bill several times
+ *     over. It stays reachable in one keystroke (`/tier peak`) and is never
+ *     the resting state. `/advise` remains the capped, per-question
+ *     escalation for people who want peak judgment without moving the whole
+ *     session.
+ *
+ * `balanced` is deliberately NOT selectable. It names a session routing
+ * POLICY rather than a rung (see `pipeline/tierCap.ts` and `mapModelTier` in
+ * subagents.ts, which exclude it for the same reason), and offering a policy
+ * alongside four rungs in one picker makes the list read as five tiers.
+ *
+ * Pure helpers first, wiring last — the same split as `permission.ts` and
+ * `advisor.ts`, so the rules are testable without a pi session.
+ *
+ * LOGGING. This module writes `source: "tier"` to the error sink, with three
+ * events: `start_tier_corrected` (info) and `start_tier_correction_failed`
+ * (warn) from the session_start guard, and `tier_switch_failed` (warn) from
+ * the command. All three are TRAIL-ONLY: nothing downstream parses them, and
+ * they exist so `/diagnostics` and a support session can answer "why is this
+ * session on peak" after the fact. A rung that failed to move is invisible in
+ * every other record, which is why the failures log at all.
+ */
+import { logEvent } from "./errorSink.js";
+import { scrubSecrets } from "./pipeline/scrubSecrets.js";
+/** The provider the tier models are registered under (see provider.ts). */
+export const YAGNI_PROVIDER = "yagni";
+/**
+ * The rungs a driver session may sit on, in PICKER ORDER.
+ *
+ * Order is the product statement, not an accident: the default leads, the two
+ * cheaper rungs follow, and `peak` sits last. The backend catalog's own order
+ * is strongest-first (`balanced`, `peak`, `advanced`, ...), which would put
+ * peak in the first, most-clickable position of a picker it should never be
+ * the resting state of.
+ */
+export const SELECTABLE_TIERS = ["advanced", "standard", "efficient", "peak"];
+/** The rung every interactive driver session opens on. */
+export const SESSION_START_TIER = "advanced";
+/** Rungs a session must never be left parked on at start. Peak only, today. */
+const NEVER_START_TIERS = new Set(["peak"]);
+/** One-line description per rung, for `/tier` with no argument. */
+const TIER_BLURB = {
+    advanced: "the default driver rung",
+    standard: "cheaper, for mechanical work",
+    efficient: "cheapest, for search and triage",
+    peak: "strongest judgment, several times the spend",
+};
+export function isSelectableTier(value) {
+    return !!value && SELECTABLE_TIERS.includes(value);
+}
+/**
+ * The driver's picker catalog: the four rungs, in {@link SELECTABLE_TIERS}
+ * order, filtered against what the backend actually served.
+ *
+ * Filtering against the live catalog rather than returning SELECTABLE_TIERS
+ * verbatim matters: a workspace whose catalog omits a rung (an entitlement,
+ * a backend that dropped one) must not get a picker entry that 404s on first
+ * use. Anything the backend serves that is not a selectable rung (`balanced`)
+ * is dropped.
+ */
+export function orderDriverCatalog(models) {
+    const byId = new Map(models.map((m) => [m.id, m]));
+    const ordered = [];
+    for (const tier of SELECTABLE_TIERS) {
+        const model = byId.get(tier);
+        if (model)
+            ordered.push(model);
+    }
+    return ordered;
+}
+/**
+ * The rung a starting session must be moved to, or null to leave it alone.
+ *
+ * Returns the start tier when the session would otherwise open on a
+ * never-start rung. A session opening on any other selectable rung is left
+ * as-is: an explicit `--model standard` (the backend's scoping sessions) is a
+ * legitimate choice, and only `peak` is the one we refuse to rest on.
+ *
+ * PURE. Callers decide whether the correction applies to them at all —
+ * children and eval lanes name their tier on the command line and are exempt.
+ */
+export function startTierCorrection(currentId) {
+    if (!currentId)
+        return null;
+    return NEVER_START_TIERS.has(currentId) ? SESSION_START_TIER : null;
+}
+export function parseTierArg(args) {
+    const raw = args.trim().toLowerCase();
+    if (!raw)
+        return { kind: "show" };
+    if (isSelectableTier(raw))
+        return { kind: "set", tier: raw };
+    return { kind: "unknown", input: raw };
+}
+/** The `/tier` status line: what is in play, and what else is reachable. PURE. */
+export function formatTierStatus(currentId) {
+    const current = isSelectableTier(currentId) ? currentId : undefined;
+    const head = current
+        ? `This session is on ${current} (${TIER_BLURB[current]}).`
+        : `This session is on "${currentId ?? "unknown"}", which is not one of the selectable rungs.`;
+    const options = SELECTABLE_TIERS.map((t) => `  /tier ${t} - ${TIER_BLURB[t]}`).join("\n");
+    return `${head}\nSwitch with /tier <rung>, or pick from /model:\n${options}\nEvery session starts on ${SESSION_START_TIER}.`;
+}
+/** The notice shown when a switch lands. PURE. */
+export function formatTierSwitched(tier) {
+    const parked = tier === "peak"
+        ? " Peak is priced for judgment, not for driving: the next session starts back on advanced."
+        : "";
+    return `Session tier is now ${tier} (${TIER_BLURB[tier]}).${parked}`;
+}
+/** Upper bound on a trail `reason`, in characters. */
+export const TRAIL_REASON_MAX = 180;
+/**
+ * A signed URL's query string, the one credential shape {@link scrubSecrets}
+ * does not carry a rule for: the signature sits under an arbitrary parameter
+ * name (`sig`, `X-Amz-Signature`, `se`) and is usually too short for the
+ * base64 rule, so no secret-named-key or provider-prefix pattern reaches it.
+ *
+ * Kept local rather than added to `scrubSecrets`, deliberately: that module is
+ * mirrored verbatim against the backend's copy and asks to be kept in sync, so
+ * a one-off addition here would fork it. If signed URLs start showing up in
+ * trails for real, the rule belongs in BOTH copies rather than this file.
+ */
+const SIGNED_URL_QUERY = /(https?:\/\/[^\s?]+)\?\S*/gi;
+/**
+ * ANSI CSI escape sequences. A provider error relayed from a streamed
+ * terminal can carry colour and cursor codes, which survive a whitespace
+ * collapse and render the durable trail entry unreadable (or move the cursor
+ * of whatever later cats the log).
+ *
+ * Stripped BEFORE any redaction runs, never after: see {@link trailReason}.
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI_ESCAPE = /\x1b\[[0-9;]*[A-Za-z]/g;
+/**
+ * Turn a caught value into a trail-safe `reason`. PURE.
+ *
+ * A provider's `err.message` is untrusted text on its way to a DURABLE file
+ * that a developer may later paste into a support thread, so it is scrubbed
+ * and bounded at write time rather than trusted to be short and clean.
+ *
+ * Redaction delegates to {@link scrubSecrets}, the pattern set already used
+ * for captured command output: it covers provider key prefixes (sk-, gh*_,
+ * xox*, AKIA, AIza), connection-string credentials, secret-named keys,
+ * base64/JWT blobs, and opaque bearer tokens. An earlier version of this
+ * function hand-rolled a keyword-anchored regex, which missed a bare
+ * `Bearer sk-live-…` with no preceding key name, missed a bare `key=` (it
+ * only matched `api_key`), and would have drifted from the shared set over
+ * time. Order matters: redaction runs BEFORE truncation, so a secret cannot
+ * survive by sitting past the cut.
+ *
+ * Then made readable, then bounded. A streamed provider error arrives with
+ * whatever the terminal put in it (ANSI colour and cursor codes survive a
+ * whitespace collapse and garble the entry, or move the cursor of whatever
+ * later cats the log) and can carry a whole response body; the sink rotates
+ * at 256KB, so an unbounded message evicts the surrounding context that makes
+ * it readable.
+ *
+ * A non-Error resolves to "threw": there is nothing to quote, and inventing
+ * a String(err) of an arbitrary thrown value is how "[object Object]" ends up
+ * in a log.
+ */
+export function trailReason(err) {
+    if (!(err instanceof Error) || !err.message)
+        return "threw";
+    // ANSI comes off FIRST, before anything tries to match a pattern. Every
+    // redaction rule here keys on a contiguous run (`sk-[A-Za-z0-9]{16,}`, a
+    // URL up to its `?`), so an escape sequence sitting inside a credential
+    // splits that run and the rule misses. Stripping afterwards would then
+    // reassemble the full secret into the durable trail, having skipped the
+    // redaction that was supposed to catch it. Normalize, then match.
+    const normalized = err.message.replace(ANSI_ESCAPE, "");
+    const scrubbed = scrubSecrets(normalized)
+        .replace(SIGNED_URL_QUERY, "$1?[REDACTED]")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!scrubbed)
+        return "threw";
+    return scrubbed.length > TRAIL_REASON_MAX
+        ? `${scrubbed.slice(0, TRAIL_REASON_MAX - 1)}…`
+        : scrubbed;
+}
+/** The notice shown when a requested switch did not land. PURE. */
+export function formatTierSwitchFailed(requested, currentId) {
+    const still = currentId ? ` Still on ${currentId}.` : "";
+    return `Could not switch to ${requested}.${still}`;
+}
+/** The notice shown when a session is corrected off a never-start rung. PURE. */
+export function formatStartCorrection(from, to) {
+    return `Opened on ${to} rather than ${from}: sessions always start on ${to}. Use /tier ${from} to go back.`;
+}
+/**
+ * Register `/tier`.
+ *
+ * pi already ships `/model` (and Ctrl+P), which now lists the four rungs
+ * because the driver catalog carries them — that surface is left entirely to
+ * pi rather than shadowed with a same-named command. `/tier` is the
+ * tier-language sibling: it reports the current rung inline without opening a
+ * picker, and switches in one line when the rung is already known.
+ *
+ * `setModel` resolves through `ctx.modelRegistry.find`, so a rung the
+ * workspace's catalog never registered fails with a real message instead of
+ * silently selecting nothing.
+ */
+export function registerTierCommand(pi) {
+    pi.registerCommand("tier", {
+        description: "Show or switch this session's model tier (advanced / standard / efficient / peak).",
+        handler: async (args, ctx) => {
+            const notify = (message, type) => {
+                if (ctx.hasUI)
+                    ctx.ui.notify(message, type);
+            };
+            const request = parseTierArg(args);
+            if (request.kind === "show") {
+                notify(formatTierStatus(ctx.model?.id), "info");
+                return;
+            }
+            if (request.kind === "unknown") {
+                notify(`"${request.input}" is not a tier. Choose one of: ${SELECTABLE_TIERS.join(", ")}.`, "warning");
+                return;
+            }
+            if (ctx.model?.id === request.tier) {
+                notify(`Already on ${request.tier}.`, "info");
+                return;
+            }
+            const model = ctx.modelRegistry.find(YAGNI_PROVIDER, request.tier);
+            if (!model) {
+                logEvent({
+                    source: "tier",
+                    level: "warn",
+                    event: "tier_switch_failed",
+                    fields: { from: ctx.model?.id ?? "unknown", to: request.tier, reason: "registry_miss" },
+                });
+                notify(`The ${request.tier} tier is not available on this workspace.`, "error");
+                return;
+            }
+            // Mirrors the start guard's posture: a switch that does not land is
+            // logged AND named. `setModel` reaches a provider, so it can reject or
+            // throw; an uncaught throw here would escape the command handler, and a
+            // silent one would leave a developer believing they moved rungs when
+            // they did not. Both end on the same durable trail entry.
+            let ok = false;
+            let reason = "set_model_rejected";
+            try {
+                ok = await pi.setModel(model);
+            }
+            catch (err) {
+                reason = trailReason(err);
+            }
+            if (!ok) {
+                logEvent({
+                    source: "tier",
+                    level: "warn",
+                    event: "tier_switch_failed",
+                    fields: { from: ctx.model?.id ?? "unknown", to: request.tier, reason },
+                });
+            }
+            // A failed switch still has to leave the rung in play legible: that is
+            // the whole feature, and "could not switch" alone tells you nothing
+            // about what you are now driving on.
+            notify(ok ? formatTierSwitched(request.tier) : formatTierSwitchFailed(request.tier, ctx.model?.id), ok ? "info" : "error");
+        },
+    });
+}
+/**
+ * The notice shown when the correction could not be applied. PURE.
+ *
+ * Two sentences on purpose, and in this order. The failure is stated first
+ * without a cause, because the cause varies (a registry miss, a refusal, a
+ * thrown provider call) and none of them is about pricing; then the standing
+ * fact about the rung, which is true whatever went wrong and is the reason
+ * the developer should care at all. The earlier single-sentence phrasing
+ * fused the two and read as though pricing had caused the failure.
+ */
+export function formatStartCorrectionFailed(from) {
+    return `Could not move this session off ${from}. That rung is priced for judgment rather than driving, so use /tier ${SESSION_START_TIER} unless you need it.`;
+}
+/**
+ * Hold an interactive driver to {@link SESSION_START_TIER} at session start.
+ *
+ * Wired on `session_start` so it sees the model the session actually resolved
+ * (flag, persisted choice, or resume) rather than the one the launcher asked
+ * for. Fail-soft in the same spirit as the rest of the extension's
+ * session_start work: a registry miss, a rejected `setModel` or a thrown
+ * handler leaves the session on whatever it opened with rather than taking
+ * the session down.
+ *
+ * Fail-soft is NOT fail-silent. The whole point of the guard is that nobody
+ * drives a long session on the thinnest-margin rung by accident, so a failed
+ * correction is the one case that must not pass unremarked: every exit path
+ * logs (with the rung it could not move off), and the user is told plainly
+ * that they are on peak and how to leave. A silent failure here would bill
+ * exactly like the bug the guard exists to prevent.
+ */
+export function registerStartTierGuard(pi) {
+    pi.on("session_start", async (_event, ctx) => {
+        const from = ctx.model?.id ?? "unknown";
+        // Self-contained: this runs from the outer catch as well as from the
+        // ordinary failure paths, so a throw out of `notify` (a UI teardown
+        // mid-session_start) must not escape the handler it was called to
+        // rescue. `logEvent` already swallows its own errors; the notify does
+        // not, so it gets its own guard and the log still lands either way.
+        const warn = (reason) => {
+            logEvent({
+                source: "tier",
+                level: "warn",
+                event: "start_tier_correction_failed",
+                fields: { from, to: SESSION_START_TIER, reason },
+            });
+            try {
+                if (ctx.hasUI)
+                    ctx.ui.notify(formatStartCorrectionFailed(from), "warning");
+            }
+            catch {
+                /* the trail entry above is the durable half; a dead UI cannot undo it */
+            }
+        };
+        try {
+            const correction = startTierCorrection(ctx.model?.id);
+            if (!correction)
+                return;
+            const model = ctx.modelRegistry.find(YAGNI_PROVIDER, correction);
+            if (!model) {
+                warn("registry_miss");
+                return;
+            }
+            if (!(await pi.setModel(model))) {
+                warn("set_model_rejected");
+                return;
+            }
+            logEvent({
+                source: "tier",
+                level: "info",
+                event: "start_tier_corrected",
+                fields: { from, to: correction },
+            });
+            // Guarded separately from the failure notify, and for a sharper reason:
+            // the correction has ALREADY landed by this point, so letting a throw
+            // here reach the outer catch would write `start_tier_correction_failed`
+            // for a session that did move rungs. A trail that contradicts the
+            // session's actual state is worse than no trail at all, which is the
+            // whole thing this logging exists to avoid.
+            try {
+                if (ctx.hasUI)
+                    ctx.ui.notify(formatStartCorrection(from, correction), "info");
+            }
+            catch {
+                /* the rung moved and the info entry says so; a dead UI changes neither */
+            }
+        }
+        catch (err) {
+            warn(trailReason(err));
+        }
+    });
+}
+//# sourceMappingURL=tierCommand.js.map

package/dist/launch.js

@@ -127,10 +127,13 @@ 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 model is locked: the
-    // catalog is filtered to only `advanced` (see index.ts), so the user
-    // cannot switch to a different tier via /model or Ctrl+P. The proxy still
-    // resolves the tier to the concrete backing model.
+    // Open every session on the `advanced` tier. The rung is no longer locked:
+    // the driver catalog carries all four (see index.ts and tierCommand.ts), so
+    // /model, Ctrl+P and /tier can move it mid-session. This flag decides only
+    // where a session STARTS, and the extension's start guard enforces the same
+    // thing for the paths this flag cannot reach (a resume, a persisted picker
+    // choice, an explicit `--model peak`). The proxy still resolves the tier to
+    // the concrete backing model.
     const userChoseModel = passthroughArgs.some(arg => arg === "--model" || arg.startsWith("--model="));
     // Engineering-practice enrichment (YAG-496): appended to the DRIVER's system
     // prompt only — /go stage children and subagents build their own pi argv, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.1.4-staging.1415.1",
+  "version": "1.1.4-staging.1419.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -58,5 +58,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "f4fe956b10a09436d8429ae3f6b82cfa73a8d880"
+  "yagniSourceSha": "72326f4909f8b24a2657ae8ddd9caa4f4ad2e614"
 }