@mgiles/perk 1.0.1 → 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`, `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. */
@@ -206,12 +210,54 @@ export interface FooterParts {
   branch?: string;
   /** Model id (dim); omitted when no model. */
   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
@@ -236,15 +282,17 @@ function formatContextSegment(
  * Compose THE one footer line (FOOTER_MAX_LINES = 1): left group = identity + objective +
  * 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) → model → branch →
- * context → checkpoints; `identity` and `objective` are NEVER dropped — then `truncateToWidth`
- * as the last resort (ANSI- and 2-cell-emoji-aware).
+ * whole segments drop in the extended D9 order — guests (rightmost-first) → thinking → model →
+ * 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 = {
     guests: parts.guests.map((g) => sanitizeGuestStatus(g)),
     model: true,
+    thinking: true,
     branch: true,
+    cache: true,
     context: true,
     checkpoints: true,
   };
@@ -255,6 +303,8 @@ export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: n
     const right: string[] = [];
     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));
     }
@@ -268,8 +318,10 @@ export function composeFooterLine(parts: FooterParts, theme: ThemeLike, width: n
   let line = compose();
   while (visibleWidth(line) > width) {
     if (keep.guests.length > 0) keep.guests.pop();
+    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
@@ -293,6 +345,8 @@ export interface PerkFooterDeps {
   identity: string;
   status: PerkStatusHandle;
   getModelId(): string | null;
+  getThinkingLevel(): string | null;
+  getCacheHitRate(): number | null;
   getContext(): { percent: number | null; contextWindow: number } | null;
 }
 
@@ -312,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 {
@@ -325,12 +379,15 @@ 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"),
           checkpoints: deps.status.get("checkpoints"),
           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,
         };
@@ -431,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.
@@ -458,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 };
 }
 
 /**