@pellux/goodvibes-tui 1.13.0 → 1.14.0

package/src/config/tui-extension-settings.ts

@@ -0,0 +1,169 @@
+/**
+ * TUI-extension settings — config namespaces the TUI reads that are NOT part
+ * of the SDK's ConfigManager schema.
+ *
+ * The SDK owns settings.json's typed schema (its `ConfigKey` union), but its
+ * loader deep-merges user JSON over the defaults and only strips unknown
+ * `permissions.tools` keys — every other unknown top-level key survives load
+ * and round-trips through `save()`. That lets the TUI keep its own namespaces
+ * (e.g. `checkpoints.*`) in the same settings.json file and read them back
+ * here via `getRaw()`.
+ *
+ * Every reader hand-validates each field and returns a PARTIAL object holding
+ * only the keys the user actually set to a well-typed value. A missing or
+ * malformed block yields an empty object rather than throwing, so a bad edit
+ * degrades to "use the built-in defaults", never a crash. Returning a partial
+ * (rather than filling in defaults here) keeps the underlying default values
+ * owned by their real consumer instead of being duplicated in the TUI.
+ */
+
+import type { ConfigManager } from './index.ts';
+
+type RawRecord = Record<string, unknown>;
+
+function readNamespace(configManager: Pick<ConfigManager, 'getRaw'>, namespace: string): RawRecord | null {
+  const block = (configManager.getRaw() as RawRecord)[namespace];
+  if (!block || typeof block !== 'object' || Array.isArray(block)) return null;
+  return block as RawRecord;
+}
+
+function readBoolean(src: RawRecord, key: string): boolean | undefined {
+  const value = src[key];
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function readPositiveInt(src: RawRecord, key: string): number | undefined {
+  const value = src[key];
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return undefined;
+  return Math.floor(value);
+}
+
+function readNonEmptyString(src: RawRecord, key: string): string | undefined {
+  const value = src[key];
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+// ─── statusline.* — scriptable status line ───────────────────────────────────
+
+/**
+ * User-settable scriptable status line. When `command` is present it is run as
+ * a POSIX shell command at each turn boundary and its first stdout line renders
+ * in the status area. `timeoutMs` bounds each run.
+ */
+export interface StatuslineSettings {
+  /** Shell command whose first stdout line renders in the status area. Absent/empty disables the feature. */
+  readonly command?: string;
+  /** Per-run timeout in milliseconds. Defaults to 2000; clamped to [100, 15000]. */
+  readonly timeoutMs?: number;
+}
+
+export const STATUSLINE_DEFAULT_TIMEOUT_MS = 2000;
+const STATUSLINE_MIN_TIMEOUT_MS = 100;
+const STATUSLINE_MAX_TIMEOUT_MS = 15_000;
+
+// ─── session.* — session behavior ────────────────────────────────────────────
+
+/** User-settable session behavior. */
+export interface SessionSettings {
+  /**
+   * Auto-title an untitled session using the configured tool/helper (weak/fast)
+   * model after the first turn. Off by default because it costs a small model
+   * call. Only ever sets a system-sourced title; a user-chosen title is left alone.
+   */
+  readonly autoTitle?: boolean;
+}
+
+/** Read `session.*` from settings.json. */
+export function readSessionSettings(configManager: Pick<ConfigManager, 'getRaw'>): SessionSettings {
+  const src = readNamespace(configManager, 'session');
+  if (!src) return {};
+  const out: { autoTitle?: boolean } = {};
+  const autoTitle = readBoolean(src, 'autoTitle');
+  if (autoTitle !== undefined) out.autoTitle = autoTitle;
+  return out;
+}
+
+/** Read `statusline.*` from settings.json, validating and clamping the timeout. */
+export function readStatuslineSettings(configManager: Pick<ConfigManager, 'getRaw'>): StatuslineSettings {
+  const src = readNamespace(configManager, 'statusline');
+  if (!src) return {};
+  const out: { command?: string; timeoutMs?: number } = {};
+  const command = readNonEmptyString(src, 'command');
+  if (command !== undefined) out.command = command;
+  const timeoutMs = readPositiveInt(src, 'timeoutMs');
+  if (timeoutMs !== undefined) {
+    out.timeoutMs = Math.min(STATUSLINE_MAX_TIMEOUT_MS, Math.max(STATUSLINE_MIN_TIMEOUT_MS, timeoutMs));
+  }
+  return out;
+}
+
+// ─── checkpoints.* — workspace checkpoint root-guard options ─────────────────
+
+/**
+ * User-settable root-guard options for the SDK's WorkspaceCheckpointManager.
+ * All optional: an omitted key defers to the manager's own default. Field
+ * names and semantics mirror the SDK's `WorkspaceCheckpointManagerOptions`.
+ */
+export interface CheckpointGuardSettings {
+  /** Prefer the enclosing git repo's top level over the raw workspace root. SDK default: true. */
+  readonly preferGitRoot?: boolean;
+  /** Opt in to snapshotting a broad root (filesystem root / home / ~/.goodvibes). SDK default: false. */
+  readonly allowBroadRoot?: boolean;
+  /** Opt in to a first snapshot whose full sweep exceeds maxFirstSnapshotFiles. SDK default: false. */
+  readonly allowLargeFirstSnapshot?: boolean;
+  /** Ceiling for the first-ever snapshot's file sweep. SDK default: 50000. */
+  readonly maxFirstSnapshotFiles?: number;
+  /** Run a retention sweep automatically after each create() and once at init. SDK default: true. */
+  readonly autoRetention?: boolean;
+}
+
+/**
+ * Merge the user's `checkpoints.*` root-guard settings onto a base
+ * WorkspaceCheckpointManager options object.
+ *
+ * NOTE: the pinned platform SDK's WorkspaceCheckpointManager may predate these
+ * root-guard options — an older constructor reads only
+ * workspaceRoot/checkpointDir/runtimeBus/retention/now and silently ignores the
+ * rest, making the guard keys INERT. They become effective the moment the SDK
+ * is upgraded to a build whose options type declares them (preferGitRoot,
+ * allowBroadRoot, allowLargeFirstSnapshot, maxFirstSnapshotFiles,
+ * autoRetention) — no code change needed here. The return type intersects the
+ * base with CheckpointGuardSettings so the extra keys flow through structurally
+ * without an unsafe cast.
+ */
+export function withCheckpointGuardSettings<T extends object>(
+  base: T,
+  configManager: Pick<ConfigManager, 'getRaw'>,
+): T & CheckpointGuardSettings {
+  return { ...base, ...readCheckpointGuardSettings(configManager) };
+}
+
+/**
+ * Read `checkpoints.*` from settings.json. Returns only the keys present and
+ * well-typed; unknown or malformed values are dropped so the SDK's own
+ * defaults apply for them.
+ */
+export function readCheckpointGuardSettings(configManager: Pick<ConfigManager, 'getRaw'>): CheckpointGuardSettings {
+  const src = readNamespace(configManager, 'checkpoints');
+  if (!src) return {};
+  const out: {
+    preferGitRoot?: boolean;
+    allowBroadRoot?: boolean;
+    allowLargeFirstSnapshot?: boolean;
+    maxFirstSnapshotFiles?: number;
+    autoRetention?: boolean;
+  } = {};
+  const preferGitRoot = readBoolean(src, 'preferGitRoot');
+  if (preferGitRoot !== undefined) out.preferGitRoot = preferGitRoot;
+  const allowBroadRoot = readBoolean(src, 'allowBroadRoot');
+  if (allowBroadRoot !== undefined) out.allowBroadRoot = allowBroadRoot;
+  const allowLargeFirstSnapshot = readBoolean(src, 'allowLargeFirstSnapshot');
+  if (allowLargeFirstSnapshot !== undefined) out.allowLargeFirstSnapshot = allowLargeFirstSnapshot;
+  const maxFirstSnapshotFiles = readPositiveInt(src, 'maxFirstSnapshotFiles');
+  if (maxFirstSnapshotFiles !== undefined) out.maxFirstSnapshotFiles = maxFirstSnapshotFiles;
+  const autoRetention = readBoolean(src, 'autoRetention');
+  if (autoRetention !== undefined) out.autoRetention = autoRetention;
+  return out;
+}

package/src/core/approval-alert.ts

@@ -24,11 +24,19 @@ import type { WebhookNotifier } from '@pellux/goodvibes-sdk/platform/integration
 import type { PermissionRequestHandler, PermissionPromptRequest } from '@pellux/goodvibes-sdk/platform/permissions';
 import type { FocusTracker } from './focus-tracker.ts';
 import { shouldFireAlert, FORCE_NOTIFY_DURATION_MS, type ConfigGet } from './alert-gating.ts';
+import type { TerminalNotifier } from './terminal-notifier.ts';
 
 export interface ApprovalAlertDeps {
   readonly focusTracker: Pick<FocusTracker, 'shouldAlertWhenUnfocused'>;
   readonly configGet: ConfigGet;
   readonly webhookNotifier?: WebhookNotifier | null;
+  /**
+   * Optional in-terminal (OSC 9) notifier. When present, a permission prompt
+   * appearing also emits an in-terminal notification, gated independently by
+   * the notifier's own per-signal config + focus rule (separate from the
+   * desktop-alert gate below). Absent in tests/headless.
+   */
+  readonly terminalNotifier?: TerminalNotifier | null;
 }
 
 /**
@@ -48,11 +56,16 @@ export function wrapRequestPermissionWithAlert(
 }
 
 function fireApprovalAlert(request: PermissionPromptRequest, deps: ApprovalAlertDeps): void {
+  // PRIVACY: tool name + category only. Never request.args.
+  const message = `${request.tool} (${request.category}) is waiting for approval`;
+
+  // In-terminal (OSC 9) notification fires on its OWN gating (independent of the
+  // desktop-alert gate below), so it is emitted before the early return.
+  deps.terminalNotifier?.notify('approval-wait', message);
+
   if (!shouldFireAlert(deps.focusTracker, deps.configGet, 'behavior.notifyOnApprovalPending')) return;
 
   const title = 'GoodVibes — approval needed';
-  // PRIVACY: tool name + category only. Never request.args.
-  const message = `${request.tool} (${request.category}) is waiting for approval`;
 
   try {
     notifyCompletion(title, message, FORCE_NOTIFY_DURATION_MS);

package/src/core/compaction-receipt.ts

@@ -0,0 +1,127 @@
+/**
+ * Post-compaction receipt rendering.
+ *
+ * The SDK emits a mandatory COMPACTION_RECEIPT event after every automatic (and
+ * the manual) compaction path, so a compaction is never silent. This module
+ * turns that receipt into a distinct, multi-line `[Compaction]` block for the
+ * transcript. It is a pure formatter — no state, no I/O — so it is unit-testable
+ * and the wiring layer only has to route the returned string.
+ *
+ * Why a visible receipt: automatic behavior (the orchestrator's post-turn
+ * auto-compaction) previously ran without any transcript trace. The receipt
+ * makes the audit trail visible: what was compacted, the quality the guard
+ * computed, whether the standing-instruction chain was re-injected, and the
+ * outcome — applied, kept-original (quality guard rejected it), or failed.
+ *
+ * The `[Compaction]` prefix is one of the FORCE_CONVERSATION_PREFIXES the
+ * system-message router always surfaces inline (see system-message-router.ts),
+ * so the receipt cannot be routed away into a panel and vanish.
+ */
+
+/** The shape of the SDK's COMPACTION_RECEIPT event payload we render from. */
+export interface CompactionReceiptInput {
+  readonly trigger: 'auto' | 'manual';
+  readonly strategy: string;
+  readonly tokensBefore: number;
+  readonly tokensAfter: number;
+  readonly messagesBefore: number;
+  readonly messagesAfter: number;
+  readonly qualityScore: number;
+  readonly qualityGrade: string;
+  readonly lowQuality: boolean;
+  readonly instructionsReinjected: boolean;
+  readonly validationPassed: boolean;
+  /**
+   * IDs of the sections the compactor actually carried into the compacted
+   * output. Rendered plainly so the receipt says which parts of context
+   * survived; an empty list is narrated as "none recorded" rather than hidden.
+   */
+  readonly sectionsIncluded: readonly string[];
+  readonly outcome: 'applied' | 'kept-original' | 'failed';
+  readonly detail?: string | undefined;
+  /**
+   * The strategy the caller REQUESTED (from `behavior.compactionStrategy`),
+   * present only when it differs from `strategy` — i.e. a distiller→structured
+   * fallback happened. `strategy` always names what actually ran.
+   */
+  readonly requestedStrategy?: string | undefined;
+  /** Why the requested strategy fell back to `strategy`. Present only alongside requestedStrategy. */
+  readonly strategyFallbackReason?: string | undefined;
+}
+
+function fmtN(n: number): string {
+  return Math.max(0, Math.round(n)).toLocaleString();
+}
+
+/** Human-readable outcome clause naming exactly what happened. */
+function describeOutcome(outcome: CompactionReceiptInput['outcome']): string {
+  switch (outcome) {
+    case 'applied':
+      return 'applied — compacted context committed';
+    case 'kept-original':
+      return 'kept original — quality guard rejected the summary, conversation retained';
+    case 'failed':
+      return 'failed — compaction did not produce a usable result';
+    default:
+      return outcome;
+  }
+}
+
+/**
+ * Build the distinct multi-line receipt block. Lines after the header are
+ * indented two spaces so the transcript renders them as one grouped block under
+ * the `[Compaction] Receipt` heading.
+ */
+export function buildCompactionReceiptBlock(receipt: CompactionReceiptInput): string {
+  const triggerWord = receipt.trigger === 'auto' ? 'Automatic' : 'Manual';
+  const savings = Math.max(0, receipt.tokensBefore - receipt.tokensAfter);
+  const savingsPct = receipt.tokensBefore > 0
+    ? Math.round((savings / receipt.tokensBefore) * 100)
+    : 0;
+
+  const lines: string[] = [];
+  lines.push(`[Compaction] Receipt — ${triggerWord.toLowerCase()} compaction, outcome: ${describeOutcome(receipt.outcome)}`);
+
+  // Only report the size delta when the summary was actually applied; on
+  // kept-original / failed the "after" counts describe the retained original,
+  // so a savings figure would be misleading.
+  if (receipt.outcome === 'applied') {
+    lines.push(
+      `  ${receipt.messagesBefore} → ${receipt.messagesAfter} messages, ` +
+      `~${fmtN(receipt.tokensBefore)} → ~${fmtN(receipt.tokensAfter)} tokens ` +
+      `(saved ~${fmtN(savings)}, ${savingsPct}%).`,
+    );
+  } else {
+    lines.push(`  Context retained at ~${fmtN(receipt.tokensBefore)} tokens across ${receipt.messagesBefore} messages.`);
+  }
+
+  const gradeStr = receipt.qualityGrade ? `${receipt.qualityGrade} ` : '';
+  const qualitySuffix = receipt.lowQuality ? ' (below the quality bar)' : '';
+  lines.push(`  Quality: ${gradeStr}${Math.round(receipt.qualityScore)}/100${qualitySuffix} · strategy: ${receipt.strategy || 'unknown'}.`);
+
+  // Only present on a distiller→structured fallback — say plainly what was
+  // requested, what actually ran, and why, so the fallback is never silent.
+  if (receipt.requestedStrategy && receipt.requestedStrategy !== receipt.strategy) {
+    const reasonSuffix = receipt.strategyFallbackReason ? `: ${receipt.strategyFallbackReason}` : '';
+    lines.push(`  Requested strategy "${receipt.requestedStrategy}" fell back to "${receipt.strategy}"${reasonSuffix}.`);
+  }
+
+  const reinjected = receipt.instructionsReinjected ? 'standing instructions re-injected' : 'no standing instructions to re-inject';
+  const validated = receipt.validationPassed ? 'validation passed' : 'validation did NOT pass';
+  lines.push(`  ${reinjected}; ${validated}.`);
+
+  // Name the sections carried into the compacted output. Only meaningful when a
+  // summary was actually applied; on kept-original / failed nothing new was
+  // committed, so an empty list there is expected, not a fault.
+  const sections = (receipt.sectionsIncluded ?? []).map((s) => s.trim()).filter((s) => s.length > 0);
+  if (receipt.outcome === 'applied') {
+    const sectionsText = sections.length > 0 ? sections.join(', ') : 'none recorded';
+    lines.push(`  Sections included: ${sectionsText}.`);
+  }
+
+  if (receipt.detail && receipt.detail.trim().length > 0) {
+    lines.push(`  ${receipt.detail.trim()}`);
+  }
+
+  return lines.join('\n');
+}

package/src/core/model-routing-chip.ts

@@ -0,0 +1,82 @@
+/**
+ * model-routing-chip — turns a mid-session model change into a visible one-line
+ * conversation notice so a route/fallback/downgrade is NEVER silent.
+ *
+ * Driven by the provider registry's `MODEL_CHANGED` runtime event (fired on
+ * every setCurrentModel — user command, automatic capability route, or
+ * SDK-internal downgrade). The chip's job is the OTHERWISE-SILENT changes: the
+ * SDK-internal auto-route/downgrade paths call setCurrentModel with no TUI-side
+ * narration of their own.
+ *
+ * Division of labour with the failover path: the optimizer-gated failover in
+ * stream-event-wiring.ts already renders a richer `[Failover] from → to
+ * (reason)(+cost)` line AND records the transition into the optimizer's
+ * fallback log. So when a MODEL_CHANGED correlates to a just-recorded fallback
+ * transition, this chip stays silent (buildRoutingChip returns null) — the
+ * [Failover] line already narrated that exact change with its real reason.
+ * Every other change is surfaced here.
+ *
+ * Reason honesty: for the paths this chip surfaces the routing layer exposes no
+ * machine-readable reason (a deliberate user switch has none; an SDK-internal
+ * downgrade does not thread one to the TUI), so the notice states "reason
+ * unknown" rather than omitting the change — per the honesty rule that a change
+ * with no explanation is still reported, just marked unknown.
+ */
+
+/** The subset of a FallbackTransition this module reads (structural, SDK-agnostic). */
+export interface FallbackTransitionLike {
+  readonly from: string;
+  readonly to: string;
+  readonly reason: string;
+  readonly ts: number;
+}
+
+/** The subset of a MODEL_CHANGED event this module reads. */
+export interface ModelChangedLike {
+  readonly registryKey: string;
+  readonly provider: string;
+  readonly previous?: { readonly registryKey: string; readonly provider: string } | undefined;
+}
+
+/** How long after a recorded fallback transition a MODEL_CHANGED still counts as "that failover". */
+export const FALLBACK_CORRELATION_WINDOW_MS = 4_000;
+
+/** The forced conversation prefix so the notice is never gated as noise or routed away. */
+export const ROUTING_CHIP_PREFIX = '[Routing]';
+
+/**
+ * Most recent fallback-log reason for a from→to provider transition within the
+ * correlation window, or null. Scans newest-first so the freshest transition wins.
+ */
+export function findRecentFallbackReason(
+  fallbackLog: readonly FallbackTransitionLike[],
+  fromProvider: string,
+  toProvider: string,
+  now: number,
+  windowMs: number = FALLBACK_CORRELATION_WINDOW_MS,
+): string | null {
+  for (let i = fallbackLog.length - 1; i >= 0; i--) {
+    const t = fallbackLog[i]!;
+    if (t.from === fromProvider && t.to === toProvider && now - t.ts <= windowMs) return t.reason;
+  }
+  return null;
+}
+
+/**
+ * The routing-chip line to emit for a MODEL_CHANGED event, or null to stay
+ * silent. Null only when there is no real change (no/same previous model) or
+ * when the change was a failover already narrated by its own [Failover] line
+ * (correlated via the fallback log). Otherwise returns the honest
+ * `[Routing] model changed: old → new (reason unknown)` notice.
+ */
+export function buildRoutingChip(
+  change: ModelChangedLike,
+  fallbackLog: readonly FallbackTransitionLike[],
+  now: number,
+): string | null {
+  const prev = change.previous;
+  if (!prev || prev.registryKey === change.registryKey) return null;
+  const failoverReason = findRecentFallbackReason(fallbackLog, prev.provider, change.provider, now);
+  if (failoverReason !== null) return null; // [Failover] already narrated this transition
+  return `${ROUTING_CHIP_PREFIX} model changed: ${prev.registryKey} → ${change.registryKey} (reason unknown)`;
+}

package/src/core/permission-mode.ts

@@ -0,0 +1,89 @@
+/**
+ * Session permission mode — the small vocabulary and cycle logic shared by the
+ * Shift+Tab mode-cycle key, the `/plan` toggle, and the footer mode pill.
+ *
+ * The SDK owns the permission mode: it lives at config key `permissions.mode`
+ * and is read by the SDK's PermissionManager.getMode() (which the orchestrator
+ * consults for the standing plan-mode instruction). Setting the config value is
+ * the SDK-sanctioned way to change the mode — the SDK's mode-change emitter then
+ * broadcasts PERMISSION_MODE_CHANGED on the runtime bus so every attached
+ * surface can reflect it. This module only maps and cycles the values; it never
+ * owns the state.
+ *
+ * Two vocabularies exist and must not be confused:
+ *  - the CONFIG values ('prompt' | 'allow-all' | 'custom' | 'plan' |
+ *    'accept-edits') — what is stored and what this module operates on.
+ *  - the user-facing LABELS ('normal' | 'auto' | 'custom' | 'plan' |
+ *    'accept-edits') — what the pill shows.
+ */
+
+/** The config `permissions.mode` values, exactly as the SDK schema defines them. */
+export type PermissionModeValue = 'prompt' | 'allow-all' | 'custom' | 'plan' | 'accept-edits';
+
+/**
+ * The Shift+Tab cycle order over the four named SESSION modes. `custom` is a
+ * per-rule policy, not a session posture, so it is deliberately excluded from
+ * the cycle — cycling FROM custom starts at the first entry (normal).
+ *
+ * Order (matches the settled convention: escalating autonomy, then wrap):
+ *   normal → accept-edits → plan → auto → normal
+ */
+export const PERMISSION_MODE_CYCLE: readonly PermissionModeValue[] = [
+  'prompt',
+  'accept-edits',
+  'plan',
+  'allow-all',
+] as const;
+
+/** User-facing label for a mode value (what the pill and messages show). */
+export function permissionModeLabel(mode: PermissionModeValue | string | undefined): string {
+  switch (mode) {
+    case 'prompt': return 'normal';
+    case 'allow-all': return 'auto';
+    case 'plan': return 'plan';
+    case 'accept-edits': return 'accept-edits';
+    case 'custom': return 'custom';
+    default: return 'normal';
+  }
+}
+
+/**
+ * A coarse tone key for the pill, so the renderer can color modes without
+ * importing the value vocabulary. `neutral` for normal, `caution` for the
+ * autonomy-raising modes, `info` for plan (read-only, safe).
+ */
+export type PermissionModeTone = 'neutral' | 'info' | 'caution';
+
+export function permissionModeTone(mode: PermissionModeValue | string | undefined): PermissionModeTone {
+  switch (mode) {
+    case 'plan': return 'info';
+    case 'accept-edits': return 'caution';
+    case 'allow-all': return 'caution';
+    case 'custom': return 'caution';
+    default: return 'neutral';
+  }
+}
+
+/**
+ * Next mode in the Shift+Tab cycle. An unknown or `custom` current value maps
+ * to the first cycle entry (normal), so the cycle is always well-defined.
+ */
+export function nextPermissionMode(current: PermissionModeValue | string | undefined): PermissionModeValue {
+  const idx = PERMISSION_MODE_CYCLE.indexOf(current as PermissionModeValue);
+  if (idx < 0) return PERMISSION_MODE_CYCLE[0];
+  return PERMISSION_MODE_CYCLE[(idx + 1) % PERMISSION_MODE_CYCLE.length];
+}
+
+/** True when the value is plan mode. */
+export function isPlanMode(mode: PermissionModeValue | string | undefined): boolean {
+  return mode === 'plan';
+}
+
+/**
+ * The result of a `/plan` toggle: entering plan mode from any non-plan mode,
+ * or leaving it back to normal. Kept here so the command and any future caller
+ * agree on the toggle target.
+ */
+export function togglePlanMode(current: PermissionModeValue | string | undefined): PermissionModeValue {
+  return isPlanMode(current) ? 'prompt' : 'plan';
+}

package/src/core/rewind-receipt.ts

@@ -0,0 +1,83 @@
+/**
+ * rewind-receipt.ts — transcript rendering for an applied unified rewind.
+ *
+ * The SDK's UnifiedRewindService returns a RewindReceipt from rewind.apply (and
+ * emits a matching REWIND_APPLIED workspace event). This module turns that
+ * receipt into a distinct, multi-line `[Rewind]` block, mirroring the
+ * `[Compaction]` receipt (compaction-receipt.ts) so a rewind is never a silent
+ * mutation of files or conversation history — the transcript records exactly
+ * what was restored and whether it can be reversed.
+ *
+ * The `[Rewind]` prefix is one of the FORCE_CONVERSATION_PREFIXES the
+ * system-message router always surfaces inline (see core/system-message-router.ts),
+ * so the receipt cannot be routed into a panel and vanish.
+ */
+
+/** The subset of the SDK's RewindReceipt this formatter renders. */
+export interface RewindReceiptInput {
+  readonly scope: 'files' | 'conversation' | 'both';
+  readonly turnId: string | null;
+  readonly files: {
+    readonly restored: boolean;
+    readonly restoredFileCount: number;
+    readonly removedFileCount: number;
+    readonly safetyCheckpointId: string | null;
+  } | null;
+  readonly conversation: {
+    readonly rewound: boolean;
+    readonly droppedMessages: number;
+    readonly undoSnapshotId: string | null;
+  } | null;
+  readonly undoAvailable: boolean;
+  readonly warnings: readonly string[];
+}
+
+function plural(n: number, word: string): string {
+  return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+
+/** Short, human turn reference for the receipt heading. */
+function describeAnchor(turnId: string | null): string {
+  return turnId ? `turn ${turnId.length > 12 ? `${turnId.slice(0, 12)}…` : turnId}` : 'the most recent checkpoint';
+}
+
+/**
+ * Build the distinct multi-line `[Rewind]` receipt block. Pure — no state, no
+ * I/O. Lines after the header are indented two spaces so the transcript renders
+ * them as one grouped block under the `[Rewind] Receipt` heading.
+ */
+export function buildRewindReceiptBlock(receipt: RewindReceiptInput): string {
+  const lines: string[] = [];
+  lines.push(`[Rewind] Receipt — rewound ${receipt.scope} to ${describeAnchor(receipt.turnId)}.`);
+
+  if (receipt.files) {
+    if (receipt.files.restored) {
+      lines.push(
+        `  Files: restored ${plural(receipt.files.restoredFileCount, 'file')}, ` +
+        `removed ${plural(receipt.files.removedFileCount, 'file')}.`,
+      );
+    } else {
+      lines.push('  Files: not restored — no workspace checkpoint matched this anchor.');
+    }
+  }
+
+  if (receipt.conversation) {
+    if (receipt.conversation.rewound) {
+      lines.push(`  Conversation: dropped ${plural(receipt.conversation.droppedMessages, 'message')} after this turn.`);
+    } else {
+      lines.push('  Conversation: not rewound — no conversation boundary was recorded for this anchor.');
+    }
+  }
+
+  lines.push(
+    receipt.undoAvailable
+      ? '  Reversible: run /undo rewind to restore the pre-rewind state (/redo rewind re-applies).'
+      : '  Reversible: no undo point was recorded for this rewind.',
+  );
+
+  for (const warning of receipt.warnings) {
+    lines.push(`  note: ${warning}`);
+  }
+
+  return lines.join('\n');
+}