@mgiles/perk 1.1.0 → 2.0.0

package/extension/surfaces/surfaces.ts

@@ -16,6 +16,10 @@
 
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
+// `Key` is keybinding vocabulary (`pi.registerShortcut(Key.ctrlAlt("p"), …)`), not rich UI —
+// re-exported so pi-tui imports stay structurally confined to the surfaces module (the
+// surfacesGuard pi-tui import rule) without allowlisting the shortcut-registering modules.
+export { Key } from "@earendil-works/pi-tui";
 // Re-exports: the notify seam stays in report.ts; surfaces.ts is the one import for UI vocabulary.
 export { type ReportTarget, report, type Severity } from "./report.ts";
 
@@ -30,7 +34,7 @@ export const WIDGET_SLOT_CHECKPOINTS = "perk-checkpoints";
 export const MARK_CHECKPOINTS = "📋";
 export const MARK_OBJECTIVE = "🎯";
 
-// --- glyph vocabulary (charter §5 / D3) — data only; themed rendering binds in nodes 2.2/3.1 ---
+// --- glyph vocabulary (charter §5 / D3) — data only; themed rendering lives in the widget/footer builders below ---
 export type GlyphKind = "done" | "current" | "pending" | "warning" | "failure";
 export const GLYPHS: Record<GlyphKind, { glyph: string; themeColor: string }> = {
   done: { glyph: "✓", themeColor: "success" },
@@ -40,7 +44,7 @@ export const GLYPHS: Record<GlyphKind, { glyph: string; themeColor: string }> =
   failure: { glyph: "✗", themeColor: "error" },
 };
 
-// --- height bounds (charter §4 / D1/D8) — enforcement lands in nodes 2.2/2.3/4.1 ---
+// --- height bounds (charter §4 / D1/D8) — enforced by the report() notify budget and the footer/widget builders ---
 export const NOTIFY_MAX_LINES = 1;
 export const FOOTER_MAX_LINES = 1;
 export const CHECKPOINTS_WIDGET_MAX_LINES = 4;
@@ -192,8 +196,8 @@ export function createPerkStatus(): PerkStatusHandle {
 /**
  * The raw material for one composed footer line. Left group (charter order 1–3): `identity`,
  * `objective`, `checkpoints` — the segments render verbatim (they carry their own 🎯/📋 marks).
- * Right group (charter order 4, 5, +context, 6): `branch`, `model`, `thinking`, `context`, `guests` —
- * right-aligned, non-segment system text dim-themed.
+ * Right group (charter order 4, 5, +context, 6): `branch`, `model`, `thinking`, `cache`,
+ * `context`, `guests` — right-aligned, non-segment system text dim-themed.
  */
 export interface FooterParts {
   /** e.g. `perk v0.0.1` — standing identity (D7), dim. */
@@ -208,12 +212,52 @@ export interface FooterParts {
   model?: string;
   /** The session thinking level (dim; e.g. `high`/`off`); omitted when there is no model. */
   thinking?: string;
+  /** The prompt-cache-hit segment, e.g. `CH42.3%` (dim; right group); omitted until cache activity. */
+  cache?: string;
   /** Context usage — rendered `<pct>%/<window>` (dim; warning >70, error >90; `?` when null). */
   context?: { percent: number | null; contextWindow: number };
   /** Guest extension statuses (dim), pre-sorted by slot key; sanitized here. */
   guests: string[];
 }
 
+/**
+ * A structural slice of pi's `SessionEntry` — only what `latestCacheHitRate` reads. Keeps
+ * surfaces.ts dependency-light (no pi imports; `SessionEntry[]` is assignable) — the same
+ * structural-mirror pattern as `FooterDataLike`/`ThemeLike`.
+ */
+export interface UsageEntryLike {
+  type: string;
+  message?: {
+    role?: string;
+    usage?: { input: number; cacheRead: number; cacheWrite: number };
+  };
+}
+
+/**
+ * The prompt-cache-hit rate of the latest usage-bearing assistant message, as a percentage —
+ * an exact local mirror of pi's default-footer `CH` computation (pi's cache-stats helpers are
+ * unexported; the `sanitizeGuestStatus` reimplementation precedent). Includes pi's display gate:
+ * returns `null` unless the session shows cache activity (total cacheRead or cacheWrite > 0) AND
+ * the latest usage-bearing assistant message has prompt tokens > 0 (a trailing zero-prompt-token
+ * assistant message resets the rate, exactly like pi's `undefined`).
+ */
+export function latestCacheHitRate(entries: readonly UsageEntryLike[]): number | null {
+  let totalCacheRead = 0;
+  let totalCacheWrite = 0;
+  let latest: number | null = null;
+  for (const entry of entries) {
+    if (entry.type !== "message" || entry.message?.role !== "assistant") continue;
+    const usage = entry.message.usage;
+    if (usage === undefined) continue;
+    totalCacheRead += usage.cacheRead;
+    totalCacheWrite += usage.cacheWrite;
+    const promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;
+    latest = promptTokens > 0 ? (usage.cacheRead / promptTokens) * 100 : null;
+  }
+  if (totalCacheRead <= 0 && totalCacheWrite <= 0) return null;
+  return latest;
+}
+
 /** Pi's `sanitizeStatusText` behavior, reimplemented locally (pi does not export it). */
 function sanitizeGuestStatus(text: string): string {
   return text
@@ -239,8 +283,8 @@ function formatContextSegment(
  * checkpoints (two-space-joined, charter order); right group = branch + model + context + guests
  * (two-space-joined), right-aligned with ≥2 spaces of padding. When the line exceeds `width`,
  * whole segments drop in the extended D9 order — guests (rightmost-first) → thinking → model →
- * branch → context → checkpoints; `identity` and `objective` are NEVER dropped — then `truncateToWidth`
- * as the last resort (ANSI- and 2-cell-emoji-aware).
+ * branch → cache → context → checkpoints; `identity` and `objective` are NEVER dropped — then
+ * `truncateToWidth` as the last resort (ANSI- and 2-cell-emoji-aware).
  */
 export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: number): string {
   const keep = {
@@ -248,6 +292,7 @@ export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: n
     model: true,
     thinking: true,
     branch: true,
+    cache: true,
     context: true,
     checkpoints: true,
   };
@@ -259,6 +304,7 @@ export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: n
     if (keep.branch && parts.branch !== undefined) right.push(theme.fg("dim", parts.branch));
     if (keep.model && parts.model !== undefined) right.push(theme.fg("dim", parts.model));
     if (keep.thinking && parts.thinking !== undefined) right.push(theme.fg("dim", parts.thinking));
+    if (keep.cache && parts.cache !== undefined) right.push(theme.fg("dim", parts.cache));
     if (keep.context && parts.context !== undefined) {
       right.push(formatContextSegment(parts.context, theme));
     }
@@ -275,6 +321,7 @@ export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: n
     else if (keep.thinking) keep.thinking = false;
     else if (keep.model) keep.model = false;
     else if (keep.branch) keep.branch = false;
+    else if (keep.cache) keep.cache = false;
     else if (keep.context) keep.context = false;
     else if (keep.checkpoints) keep.checkpoints = false;
     else break; // identity + objective only — nothing left to drop
@@ -299,6 +346,7 @@ export interface PerkFooterDeps {
   status: PerkStatusHandle;
   getModelId(): string | null;
   getThinkingLevel(): string | null;
+  getCacheHitRate(): number | null;
   getContext(): { percent: number | null; contextWindow: number } | null;
 }
 
@@ -318,7 +366,7 @@ export type PerkFooterFactory = (
  * line in the intended split layout. `render` gathers everything live per call (D10 stateless
  * render): segments via the handle, branch/guests via `footerData` (excluding perk's own
  * `STATUS_SLOT_PERK` — the slot keeps publishing for RPC, but the footer renders the segments
- * directly), model/context via the deps closures. Reactivity (the D2 contract): repaints on
+ * directly), model/cache/context via the deps closures. Reactivity (the D2 contract): repaints on
  * every handle recompose and on branch change; `dispose` detaches both.
  */
 export function perkFooter(deps: PerkFooterDeps): PerkFooterFactory {
@@ -331,6 +379,7 @@ export function perkFooter(deps: PerkFooterDeps): PerkFooterFactory {
           .filter(([key]) => key !== STATUS_SLOT_PERK)
           .sort(([a], [b]) => a.localeCompare(b))
           .map(([, text]) => text);
+        const rate = deps.getCacheHitRate();
         const parts: FooterParts = {
           identity: deps.identity,
           objective: deps.status.get("objective"),
@@ -338,6 +387,7 @@ export function perkFooter(deps: PerkFooterDeps): PerkFooterFactory {
           branch: footerData.getGitBranch() ?? undefined,
           model: deps.getModelId() ?? undefined,
           thinking: deps.getThinkingLevel() ?? undefined,
+          cache: rate === null ? undefined : `CH${rate.toFixed(1)}%`,
           context: deps.getContext() ?? undefined,
           guests,
         };
@@ -438,14 +488,28 @@ export function renderProgressLines(
     if (item.kind === "elision") {
       return truncateToWidth(theme.fg("dim", `… +${item.hidden} ${item.side}`), width);
     }
-    const kind = stepGlyphKind(state, item.step);
-    const glyph = theme.fg(GLYPHS[kind].themeColor, GLYPHS[kind].glyph);
-    const text = `${item.step.step}. ${item.step.text}`;
-    const line = `${glyph} ${kind === "done" ? theme.fg("muted", text) : text}`;
-    return truncateToWidth(line, width);
+    return renderStepLine(state, item.step, theme, width);
   });
 }
 
+/**
+ * ONE themed per-step line (`✓/▸/○ <n>. <text>`, §5 colors, D9-truncated) — shared by the
+ * checkpoints widget (`renderProgressLines`, windowed) and the checkpoint transcript marker's
+ * expanded view (all steps, unwindowed), so the two surfaces render steps identically.
+ */
+function renderStepLine(
+  state: ProgressState,
+  step: ProgressStep,
+  theme: ThemeLike,
+  width: number,
+): string {
+  const kind = stepGlyphKind(state, step);
+  const glyph = theme.fg(GLYPHS[kind].themeColor, GLYPHS[kind].glyph);
+  const text = `${step.step}. ${step.text}`;
+  const line = `${glyph} ${kind === "done" ? theme.fg("muted", text) : text}`;
+  return truncateToWidth(line, width);
+}
+
 function formatTokens(tokens: number): string {
   if (tokens < 1000) return `${tokens}`;
   // Whole-k values render bare (`200k`, matching pi's footer); fractional keep one decimal.
@@ -465,3 +529,257 @@ function formatElapsed(ms: number): string {
 export function formatBudgetLine(args: { tokens: number; elapsedMs: number }): string {
   return `${formatTokens(args.tokens)} tok · ${formatElapsed(args.elapsedMs)}`;
 }
+
+// --- the transcript markers — display-only entry renderers ---------------------------------------
+// The audit §2.3 verdict (docs/design/pi-adoption-audit.md): perk's four display-only custom-entry
+// families render as durable one-line transcript markers. Renderer BODIES live here (a transcript
+// renderer IS a rich-UI surface the surfaces module owns); registration is wiring at the feature
+// modules via the `registerTranscriptRenderer` seam below. Renderers are an interactive-TUI-only
+// concern (never invoked in json/RPC mode), so registration is inert-safe everywhere.
+
+/** Structural slice of pi's `CustomEntry` — the only field the marker renderers read. */
+export interface TranscriptEntryLike {
+  data?: unknown;
+}
+
+/** Structural mirror of pi's `EntryRenderOptions`. */
+export interface EntryRenderOptionsLike {
+  expanded: boolean;
+}
+
+/**
+ * A transcript entry renderer, assignable to pi's `EntryRenderer<unknown>`: the params are
+ * structural supertypes of pi's (`CustomEntry`/`EntryRenderOptions`/`Theme`), and the returned
+ * object satisfies pi-tui's structural `Component` (`render(width): string[]`; `handleInput` is
+ * optional). `undefined` = render nothing (malformed/missing `data` stays invisible — exactly the
+ * pre-renderer behavior).
+ */
+export type TranscriptRenderer = (
+  entry: TranscriptEntryLike,
+  options: EntryRenderOptionsLike,
+  theme: ThemeLike,
+) => { render(width: number): string[] } | undefined;
+
+/**
+ * The minimal host surface the registration seam needs. The member is OPTIONAL and
+ * method-syntax (bivariant — the `PerkFooterFactory` recipe): pi ≥ 0.80.4's `ExtensionAPI`
+ * satisfies it; pre-0.80.4 hosts simply don't have the method.
+ */
+export interface TranscriptRendererHost {
+  registerEntryRenderer?(customType: string, renderer: TranscriptRenderer): void;
+}
+
+/**
+ * The one sanctioned `registerEntryRenderer` call site (guard-confined) carrying the one typeof
+ * feature-detect: on a pre-0.80.4 host the method is absent (calling it would `TypeError`), so
+ * registration is a silent no-op and the entries stay invisible — exactly today's behavior.
+ */
+export function registerTranscriptRenderer(
+  host: TranscriptRendererHost,
+  customType: string,
+  renderer: TranscriptRenderer,
+): void {
+  if (typeof host.registerEntryRenderer !== "function") return; // pre-0.80.4 host: inert
+  host.registerEntryRenderer(customType, renderer);
+}
+
+/**
+ * Charter budget: a COLLAPSED transcript marker is exactly one line. The expanded view is
+ * human-requested scrollback and renders its full detail unbounded (all checkpoint steps, the
+ * whole btw answer).
+ */
+export const TRANSCRIPT_MARKER_MAX_LINES = 1;
+
+/**
+ * The collapsed-marker grammar: the `report()` transition grammar `perk: <scope> — <message>`,
+ * dim, D9-truncated. Emoji stay footer-only (D3); themed §5 glyphs appear only in expanded
+ * checkpoint step lines.
+ */
+function markerLine(scope: string, message: string, theme: ThemeLike, width: number): string {
+  return truncateToWidth(theme.fg("dim", `perk: ${scope} — ${message}`), width);
+}
+
+/** The three-clause object-shape guard: a plain (non-null, non-array) object or null. */
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+/** Decode `{ steps }` from a `perk:checkpoint` entry: a non-empty array of valid steps, or null. */
+function decodeCheckpointSteps(data: unknown): ProgressStep[] | null {
+  const record = asRecord(data);
+  if (record === null) return null;
+  const steps = record.steps;
+  if (!Array.isArray(steps) || steps.length === 0) return null;
+  const decoded: ProgressStep[] = [];
+  for (const raw of steps) {
+    const step = asRecord(raw);
+    if (step === null) return null;
+    if (
+      typeof step.step !== "number" ||
+      typeof step.text !== "string" ||
+      typeof step.completed !== "boolean"
+    ) {
+      return null;
+    }
+    decoded.push({ step: step.step, text: step.text, completed: step.completed });
+  }
+  return decoded;
+}
+
+/**
+ * `perk:checkpoint` marker. Collapsed: `perk: checkpoints — <done/total>`. Expanded: that line +
+ * one §5 glyph line per step — ALL steps, unwindowed (scrollback is human-requested, so the
+ * `CHECKPOINTS_WIDGET_MAX_LINES` standing budget does not apply). `current` is derived state that
+ * lives in checkpoints.ts; a historical marker renders with `current: null` (bare `done/total`,
+ * no `▸` step) — which keeps surfaces.ts free of checkpoint imports.
+ */
+export const checkpointEntryRenderer: TranscriptRenderer = (entry, options, theme) => {
+  const steps = decodeCheckpointSteps(entry.data);
+  if (steps === null) return undefined;
+  const state: ProgressState = { steps, current: null };
+  return {
+    render(width) {
+      const collapsed = markerLine("checkpoints", progressLine(state), theme, width);
+      if (!options.expanded) return [collapsed];
+      return [collapsed, ...steps.map((step) => renderStepLine(state, step, theme, width))];
+    },
+  };
+};
+
+/**
+ * The first matching workflow-state field's marker message — a deliberately BOUNDED vocabulary
+ * (the four headline fields + a SET `objective_node_claim`), extensible later. Bookkeeping deltas
+ * (`session_artifacts`, `last_review*`, `conflict_resolution_attempts`, cleared node claims) stay
+ * invisible by returning null.
+ */
+function workflowStateMessage(data: Record<string, unknown>): string | null {
+  if (typeof data.run_id === "string") {
+    if (typeof data.predecessor === "string") {
+      return `run ${data.run_id} · child of ${data.predecessor}`;
+    }
+    let message = `run ${data.run_id} claimed`;
+    if (typeof data.stage === "string") message += ` · stage ${data.stage}`;
+    if (typeof data.mode === "string") message += ` · ${data.mode}`;
+    return message;
+  }
+  if (typeof data.mode === "string") return `${data.mode} mode`;
+  // Key-presence check (not value truthiness): an explicit null means "cleared" here.
+  if (Object.hasOwn(data, "active_objective")) {
+    if (typeof data.active_objective === "string") {
+      return `objective ${data.active_objective} activated`;
+    }
+    if (data.active_objective === null) return "objective cleared";
+  }
+  const planRef = asRecord(data.active_plan_ref);
+  if (planRef !== null && typeof planRef.pr_id === "string") {
+    return `plan ${planRef.pr_id} linked`;
+  }
+  const claim = asRecord(data.objective_node_claim);
+  if (claim !== null && typeof claim.objective === "string" && typeof claim.node === "string") {
+    // A cleared claim (null) stays invisible — only the SET claim is a marker-worthy moment.
+    return `node ${claim.node} claimed for objective ${claim.objective}`;
+  }
+  return null;
+}
+
+/**
+ * `perk:workflow-state` marker: the first matching headline field renders (precedence:
+ * run claim/fork → mode flip → objective set/clear → plan link → node claim); bookkeeping-only
+ * deltas stay invisible. Expanded: the collapsed line + the raw delta as one dim JSON line
+ * (/learn-grade debuggability).
+ */
+export const workflowStateEntryRenderer: TranscriptRenderer = (entry, options, theme) => {
+  const data = asRecord(entry.data);
+  if (data === null) return undefined;
+  const message = workflowStateMessage(data);
+  if (message === null) return undefined;
+  return {
+    render(width) {
+      const collapsed = markerLine("workflow", message, theme, width);
+      if (!options.expanded) return [collapsed];
+      return [collapsed, truncateToWidth(theme.fg("dim", JSON.stringify(data)), width)];
+    },
+  };
+};
+
+/**
+ * `perk:objective-budget` marker (`{ objective_id, activated_at }` activation entries).
+ * Collapsed: `perk: objective — <id> budget tracking started`. Expanded: + a dim activation
+ * timestamp line.
+ */
+export const objectiveBudgetEntryRenderer: TranscriptRenderer = (entry, options, theme) => {
+  const data = asRecord(entry.data);
+  if (data === null) return undefined;
+  const objectiveId = data.objective_id;
+  const activatedAt = data.activated_at;
+  if (typeof objectiveId !== "string" || typeof activatedAt !== "string") return undefined;
+  return {
+    render(width) {
+      const collapsed = markerLine(
+        "objective",
+        `${objectiveId} budget tracking started`,
+        theme,
+        width,
+      );
+      if (!options.expanded) return [collapsed];
+      return [collapsed, truncateToWidth(theme.fg("dim", `activated at ${activatedAt}`), width)];
+    },
+  };
+};
+
+/**
+ * `btw-thread-entry` marker. Collapsed: `perk: btw — <first line of question>` (dim). Expanded:
+ * the question line accented + the answer split on newlines, each line dim + width-truncated —
+ * no wrapping (a bounded choice: the marker is a durable pointer; the `/btw` overlay remains the
+ * full reader).
+ */
+export const btwThreadEntryRenderer: TranscriptRenderer = (entry, options, theme) => {
+  const data = asRecord(entry.data);
+  if (data === null) return undefined;
+  const question = data.question;
+  const answer = data.answer;
+  if (typeof question !== "string" || typeof answer !== "string") return undefined;
+  const headline = question.split("\n", 1)[0] ?? "";
+  return {
+    render(width) {
+      if (!options.expanded) return [markerLine("btw", headline, theme, width)];
+      return [
+        truncateToWidth(theme.fg("accent", `perk: btw — ${headline}`), width),
+        ...answer.split("\n").map((line) => truncateToWidth(theme.fg("dim", line), width)),
+      ];
+    },
+  };
+};
+
+/** `btw-thread-reset` marker: `perk: btw — thread reset` (+ a dim ISO timestamp line expanded). */
+export const btwThreadResetEntryRenderer: TranscriptRenderer = (entry, options, theme) => {
+  const data = asRecord(entry.data);
+  if (data === null) return undefined;
+  const timestamp = data.timestamp;
+  if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) return undefined;
+  return {
+    render(width) {
+      const collapsed = markerLine("btw", "thread reset", theme, width);
+      if (!options.expanded) return [collapsed];
+      return [
+        collapsed,
+        truncateToWidth(theme.fg("dim", new Date(timestamp).toISOString()), width),
+      ];
+    },
+  };
+};
+
+/**
+ * The coarse prose-plan widget line (relocated verbatim from checkpoints.ts's inline factory —
+ * its only pi-tui usage): one dim, D9-truncated line naming the active plan with no `## Steps`
+ * checklist.
+ */
+export function renderCoarsePlanLines(planId: string, theme: ThemeLike, width: number): string[] {
+  return [
+    truncateToWidth(
+      theme.fg("dim", `Plan #${planId}: prose plan — no \`## Steps\` checklist`),
+      width,
+    ),
+  ];
+}

package/extension/vendor/btw/btw.ts

@@ -57,6 +57,11 @@ type OverlayHandleLike = {
 
 import type { ToolGating } from "../../substrate/toolGating.ts";
 import { report } from "../../surfaces/report.ts";
+import {
+  btwThreadEntryRenderer,
+  btwThreadResetEntryRenderer,
+  registerTranscriptRenderer,
+} from "../../surfaces/surfaces.ts";
 import {
   extractEventAssistantText,
   extractText,
@@ -304,6 +309,11 @@ class BtwOverlay extends Container implements Focusable {
 }
 
 export function registerBtw(pi: ExtensionAPI, gating: ToolGating): void {
+  // Transcript markers for the btw thread entries (audit §2.3): renderer bodies in surfaces.ts,
+  // registration = wiring, feature-detect inside the seam (pre-0.80.4 hosts stay inert).
+  registerTranscriptRenderer(pi, BTW_ENTRY_TYPE, btwThreadEntryRenderer);
+  registerTranscriptRenderer(pi, BTW_RESET_TYPE, btwThreadResetEntryRenderer);
+
   let thread: BtwDetails[] = [];
   let pendingQuestion: string | null = null;
   let pendingAnswer = "";

package/extension/worker/readOnlySession.ts

@@ -80,25 +80,38 @@ export interface CapResult {
 
 /**
  * UTF-8-byte-safe truncation (subagent's byte-trim loop). Under cap ⇒ unchanged, truncated:false.
- * When truncated, appends a notice that points at the scratch file holding the full result.
- * Pure.
+ * When truncated, a notice points at the scratch file holding the full result; the notice sits at
+ * the cut edge (appended in head mode, prepended in tail mode) so a top-down reader immediately
+ * knows which side is missing.
+ *
+ * `keep` mirrors the SDK's truncateHead/truncateTail guidance: "head" (default) for
+ * model-authored summaries/handoffs where the beginning matters; "tail" for command/CI logs where
+ * failure summaries live at the end. Deliberately perk's own byte-only util (not the SDK's
+ * line-count-aware `truncateTail`): `CapResult`'s byte fields and the scratch-pointing notice are
+ * load-bearing in `ChildStructured`/`CiCheckResult`. Pure.
  */
 export function capForModel(
   text: string,
   cap: number = DEFAULT_MODEL_VISIBLE_CAP,
   scratchPath: string | null = null,
+  keep: "head" | "tail" = "head",
 ): CapResult {
   const bytesTotal = Buffer.byteLength(text, "utf8");
   if (bytesTotal <= cap) {
     return { shown: text, bytesTotal, bytesShown: bytesTotal, truncated: false };
   }
-  let trimmed = text.slice(0, cap);
-  while (Buffer.byteLength(trimmed, "utf8") > cap) trimmed = trimmed.slice(0, -1);
+  let trimmed = keep === "head" ? text.slice(0, cap) : text.slice(-cap);
+  while (Buffer.byteLength(trimmed, "utf8") > cap) {
+    trimmed = keep === "head" ? trimmed.slice(0, -1) : trimmed.slice(1);
+  }
   const bytesShown = Buffer.byteLength(trimmed, "utf8");
   const omitted = bytesTotal - bytesShown;
   const where = scratchPath ? ` Full output preserved at ${scratchPath}.` : "";
-  const notice = `\n\n[Output truncated: ${omitted} bytes omitted.${where}]`;
-  return { shown: `${trimmed}${notice}`, bytesTotal, bytesShown, truncated: true };
+  const shown =
+    keep === "head"
+      ? `${trimmed}\n\n[Output truncated: ${omitted} bytes omitted.${where}]`
+      : `[Output truncated: ${omitted} bytes omitted.${where}]\n\n${trimmed}`;
+  return { shown, bytesTotal, bytesShown, truncated: true };
 }
 
 /**

package/extension/worker/worker.ts

@@ -12,6 +12,10 @@
 // /plan-body materialization, `run_id` mint) is the cold-door/runner's job and is a PREPARED-
 // WORKTREE input (audit Gap 7): the worker inherits `PERK_RUN_ID` from the env and never re-mints.
 //
+// Budget semantics: `budget.tokens` counts FRESH WORK only — assistant `input + output` per
+// `turn_end`. Cache reads/writes and the provider `reasoning` breakdown (a subset of `output` in
+// pi-ai's normalization) are excluded by design; see `applyEvent`.
+//
 // Inverse of `extension/worker/readOnlySession.ts`: that builds a fully-isolated READ-ONLY child (loads
 // nothing, `["read","grep","find","ls"]`); the worker is the OPPOSITE — read-write defaults + the
 // real perk extension loaded from the worktree's `.pi/settings.json` (disk-layered settings:
@@ -23,7 +27,10 @@ import { appendFileSync, mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { env } from "node:process";
-import type { Api, Model } from "@earendil-works/pi-ai";
+// pi-ai's `ModelThinkingLevel` (`"off" | minimal | … | xhigh`) is the union `resolveCliModel`
+// returns and `createAgentSessionFromServices` accepts; the pi-coding-agent root does not
+// re-export a thinking-level type (only `ThinkingLevelChangeEntry`).
+import type { Api, Model, ModelThinkingLevel as ThinkingLevel } from "@earendil-works/pi-ai";
 import {
   AuthStorage,
   type CreateAgentSessionRuntimeFactory,
@@ -31,6 +38,7 @@ import {
   createAgentSessionRuntime,
   createAgentSessionServices,
   ModelRegistry,
+  resolveCliModel,
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
@@ -124,6 +132,11 @@ export interface DriveStageOptions {
    * the first provider (a since-removed `claude-3-5-haiku` date-pin 404'd a whole remote drive).
    */
   model?: Model<Api>;
+  /**
+   * Thinking level parsed from the `--model <pattern>:<level>` suffix (`resolveWorkerModel`).
+   * `undefined` ⇒ the SDK's settings-default resolution — unchanged behavior.
+   */
+  thinkingLevel?: ThinkingLevel;
   authStorage?: AuthStorage;
   modelRegistry?: ModelRegistry;
   budget: DriveBudget;
@@ -155,7 +168,14 @@ export interface DriveEvent {
     role?: string;
     stopReason?: string;
     errorMessage?: string;
-    usage?: { input?: number; output?: number };
+    /**
+     * Assistant token usage. `reasoning` is a provider-reported breakdown that is a **subset of
+     * `output`** on every pi-ai provider that populates it (anthropic `thinking_tokens`, google
+     * `thoughtsTokenCount` folded into `output`, openai `reasoning_tokens` inside completion/
+     * output tokens — verified @ pi-ai 0.80.5), so it is deliberately EXCLUDED from the budget
+     * sum: adding it would double-count.
+     */
+    usage?: { input?: number; output?: number; reasoning?: number };
     /** Assistant text/content blocks (where `[WIP:n]`/`[DONE:n]` markers live). */
     content?: unknown;
   };
@@ -221,6 +241,10 @@ function detailsOf(result: unknown): Record<string, unknown> | null {
  * assistant token usage (the `sumAssistantTokens` pattern in objective.ts), captures the `submit`
  * /`resolve_review_threads` terminal tool details, and records a post-acceptance model error
  * (assistant `message_end` with `stopReason:"error"`, surfaced with retry off — audit §B #4).
+ *
+ * The token sum is `input + output` ONLY: `usage.reasoning` is a subset of `output` on every
+ * pi-ai provider that reports it (see the `DriveEvent.usage` doc), so summing it would
+ * double-count.
  */
 export function applyEvent(counters: DriveCounters, event: DriveEvent): void {
   if (event.type === "turn_end") {
@@ -488,9 +512,11 @@ export function defaultEventSink(worktree: string, runId: string): RunEventSink
 /**
  * Re-derive the stage's initial prompt from the plan-ref — the TS twin of
  * `perk/run/launch.py._implement_prompt`/`_address_prompt`. INVARIANT: textual parity with the Python
- * plane (asserted reciprocally in `worker.test.ts` + `tests/test_worker_prompt_parity.py`); the
- * resolved skill-binding suffix is delivered by the cold door, not here. Returns
- * `null` when there is no plan-ref (nothing to prime).
+ * plane (asserted reciprocally in `worker.test.ts` + `tests/test_worker_prompt_parity.py`). No
+ * skill-binding suffix is appended here: in the driven session the bindings arrive via Mechanism A
+ * (bindingDelivery.ts injects the handoff stage's render because this prompt carries no
+ * `BINDING_HEADER`) — content byte-identical to the cold door's suffix (contracts.md §8.38).
+ * Returns `null` when there is no plan-ref (nothing to prime).
  *
  * The implement primer's wording lives in the canonical template `prompts/stages/implement.md`,
  * rendered by the shared seam (contracts.md §8.31); branching stays in code — only the `read_cmd`
@@ -516,7 +542,7 @@ export function initialPromptFor(
   }
   // address
   const modelClause = classifierModel
-    ? `, passing \`model: "${classifierModel}"\` on that call (the configured [subagents] review-classifier model)`
+    ? `, passing \`model: "${classifierModel}"\` on that call (the configured [models.subagents] review-classifier model)`
     : "";
   return render("stages/address/action.md", {
     provider,
@@ -601,8 +627,10 @@ async function defaultCreateRuntime(
       services,
       sessionManager: factoryOpts.sessionManager,
       sessionStartEvent: factoryOpts.sessionStartEvent,
-      // `undefined` ⇒ the SDK's initial-model resolution picks the model (see `resolveAuth`).
+      // `undefined` ⇒ the SDK's initial-model resolution picks the model (see `resolveAuth`);
+      // an `undefined` thinkingLevel likewise defers to the settings default.
       model: resolved.model,
+      thinkingLevel: opts.thinkingLevel,
     });
     // Name the model that will actually drive (the SDK may have picked it) — the remote step
     // log is otherwise silent about it until a provider error.
@@ -652,6 +680,48 @@ export function resolveAuth(opts: DriveStageOptions): ResolvedAuth | null {
   return { authStorage, modelRegistry, model: opts.model };
 }
 
+/** What an explicit `--model` flag resolves to (a thin projection of `ResolveCliModelResult`). */
+export interface ResolvedWorkerModel {
+  model: Model<Api> | undefined;
+  thinkingLevel: ThinkingLevel | undefined;
+  /** Non-fatal resolution diagnostic (e.g. an invalid `:thinking` suffix) — surface, continue. */
+  warning: string | undefined;
+  /** Fatal: the pattern resolved to no model — fail fast, never guess. */
+  error: string | undefined;
+}
+
+/**
+ * Resolve an explicit `--model` flag with pi's OWN CLI semantics (`resolveCliModel`): fuzzy
+ * matching, bare-id resolution, `provider/pattern`, and a `:thinking` suffix — the same chain the
+ * flag's string hits in an interactive pi launch, closing the warm/cold parity gap (cf.
+ * docs/learned/workflow/execution-path-parity.md). `raw` falsy ⇒ all-undefined (the SDK's own
+ * default resolution picks the model at session creation — see `resolveAuth`). A resolution that
+ * yields neither a model nor an error is normalized to the worker's not-found error.
+ */
+export function resolveWorkerModel(
+  raw: string | undefined,
+  modelRegistry: ModelRegistry,
+): ResolvedWorkerModel {
+  if (!raw) {
+    return { model: undefined, thinkingLevel: undefined, warning: undefined, error: undefined };
+  }
+  const result = resolveCliModel({ cliModel: raw, modelRegistry });
+  if (result.model === undefined && result.error === undefined) {
+    return {
+      model: undefined,
+      thinkingLevel: undefined,
+      warning: result.warning,
+      error: `model '${raw}' not found in the registry.`,
+    };
+  }
+  return {
+    model: result.model,
+    thinkingLevel: result.thinkingLevel,
+    warning: result.warning,
+    error: result.error,
+  };
+}
+
 // --- the drive primitive ------------------------------------------------------------------------
 
 /**