@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/src/tui-keymap.ts

@@ -0,0 +1,152 @@
+import type { KeyId } from '@earendil-works/pi-tui';
+
+/**
+ * The TUI's keys in one table (trial polish C, 2026-10-31). The global bindings in tui.ts and the
+ * `?` key sheet both read this, so the sheet cannot drift from what the keys do.
+ */
+export type GlobalAction =
+  | 'palette'
+  | 'sessions'
+  | 'new'
+  | 'approvals'
+  | 'changes'
+  | 'commands'
+  | 'rail'
+  | 'transcript'
+  | 'refresh'
+  | 'editor'
+  | 'mode'
+  | 'help';
+
+export const GLOBAL_KEYS: readonly { key: KeyId; action: GlobalAction; label: string }[] = [
+  { key: 'ctrl+k', action: 'palette', label: 'all actions' },
+  { key: 'f2', action: 'palette', label: 'all actions' },
+  { key: 'ctrl+p', action: 'sessions', label: 'sessions' },
+  { key: 'ctrl+n', action: 'new', label: 'new session' },
+  { key: 'ctrl+o', action: 'approvals', label: 'approvals' },
+  { key: 'alt+g', action: 'changes', label: 'changes' },
+  { key: 'ctrl+t', action: 'commands', label: 'commands' },
+  { key: 'ctrl+b', action: 'rail', label: 'show or hide the side panel' },
+  { key: 'ctrl+x', action: 'transcript', label: 'full transcript on or off' },
+  { key: 'f5', action: 'refresh', label: 'refresh' },
+  { key: 'ctrl+g', action: 'editor', label: 'external prompt editor' },
+  { key: 'shift+tab', action: 'mode', label: 'next mode' },
+  { key: 'f1', action: 'help', label: 'these keys' },
+];
+
+/** The per-file review on the Changes tab of a desk session. */
+export const REVIEW_KEYS = {
+  nextFile: { key: 'alt+right', label: 'next file' },
+  previousFile: { key: 'alt+left', label: 'previous file' },
+  nextHunk: { key: 'alt+down', label: 'next hunk' },
+  previousHunk: { key: 'alt+up', label: 'previous hunk' },
+  accept: { key: 'a', label: 'accept the file or hunk' },
+  revert: { key: 'r', label: 'revert it (asks first)' },
+  instruct: { key: 'i', label: 'tell the model about it' },
+} as const;
+
+/** Keys while a desk turn runs (tui-turn-keys.ts decides them). */
+export const TURN_KEYS = [
+  { key: 'escape', label: 'stop the turn' },
+  { key: 'enter', label: 'steer it' },
+  { key: 'tab', label: 'queue for after' },
+] as const;
+
+const COMPOSER: { label: string; description?: string }[] = [
+  { label: 'Enter · send', description: 'The durable outbox saves it before delivery' },
+  { label: 'Alt+Enter / Ctrl+J · new line' },
+  { label: 'Tab · switch view', description: 'Conversation · Changes · Commands · Context' },
+  { label: 'PageUp / PageDown · scroll', description: 'Ctrl+Home/End jump to the top/bottom' },
+  { label: '@ · attach a file or image' },
+  { label: '/ · slash commands' },
+  {
+    label: 'Ctrl+R · search sent messages',
+    description: 'Ctrl+R for older, Enter keeps, Esc restores',
+  },
+  {
+    label: 'Ctrl+A/E · Ctrl+U/K/W · Ctrl+Y · Ctrl+-',
+    description: 'Line start/end, kill to start/end/word, yank, undo; Alt+B/F words',
+  },
+  {
+    label: '!command · run a shell command',
+    description: 'Same approval, sandbox and danger check',
+  },
+  {
+    label: 'Ctrl+C · stop, clear, then leave',
+    description: 'Stops a running turn, else clears text; twice on empty leaves. Work continues.',
+  },
+];
+const CODING_COMMANDS = [
+  { label: '/rewind · go back to an earlier turn' },
+  { label: '/jobs · background commands' },
+  { label: '/undo · revert the last edit' },
+];
+
+export function keyLabel(key: string): string {
+  const names: Record<string, string> = { escape: 'Esc', enter: 'Enter', tab: 'Tab' };
+  if (names[key]) return names[key];
+  if (key.length === 1) return key;
+  return key
+    .split('+')
+    .map((part) =>
+      part === 'right'
+        ? '→'
+        : part === 'left'
+          ? '←'
+          : part === 'up'
+            ? '↑'
+            : part === 'down'
+              ? '↓'
+              : part.length <= 2
+                ? part.toUpperCase()
+                : part[0]!.toUpperCase() + part.slice(1),
+    )
+    .join('+');
+}
+
+export interface KeyContext {
+  tab: string;
+  coding: boolean;
+  running: boolean;
+  /** Your own slash commands (Phase 4b), listed in the conversation sheet. */
+  custom?: readonly { name: string; description: string; argumentHint?: string }[];
+}
+
+export function keySheet(c: KeyContext): {
+  title: string;
+  rows: { label: string; description?: string }[];
+} {
+  const global = GLOBAL_KEYS.map((k) => ({ label: keyLabel(k.key) + ' · ' + k.label }));
+  const approvals = { label: 'Approvals show their own keys along the bottom' };
+  if (c.tab === 'changes' && c.coding)
+    return {
+      title: 'Keys · Review changes',
+      rows: [
+        ...Object.values(REVIEW_KEYS).map((k) => ({ label: keyLabel(k.key) + ' · ' + k.label })),
+        { label: 'a, r and i work while the composer is empty' },
+        ...global,
+      ],
+    };
+  if (c.coding && c.running)
+    return {
+      title: 'Keys · Turn running',
+      rows: [
+        ...TURN_KEYS.map((k) => ({ label: keyLabel(k.key) + ' · ' + k.label })),
+        ...global,
+        approvals,
+      ],
+    };
+  return {
+    title: 'Keys · Conversation',
+    rows: [
+      ...COMPOSER,
+      ...(c.coding ? CODING_COMMANDS : []),
+      ...(c.custom ?? []).map((k) => ({
+        label: `/${k.name}${k.argumentHint ? ' ' + k.argumentHint : ''} · your command`,
+        description: k.description,
+      })),
+      ...global,
+      approvals,
+    ],
+  };
+}

package/src/tui-mentions.ts

@@ -0,0 +1,43 @@
+import { CombinedAutocompleteProvider } from '@earendil-works/pi-tui';
+import { basename } from 'node:path';
+import { listWorkspaceFiles, rankFiles } from './mentions.js';
+
+/**
+ * `@` completes workspace files from git's own listing (ignored files stay out) instead of
+ * pi-tui's `fd` walk, which is absent on most desks. The listing is cached for 5 s.
+ */
+export class MentionAutocompleteProvider extends CombinedAutocompleteProvider {
+  private cache?: { at: number; files: string[] };
+  constructor(
+    commands: ConstructorParameters<typeof CombinedAutocompleteProvider>[0],
+    private readonly root: string,
+  ) {
+    super(commands, root, null);
+  }
+  files(): string[] {
+    if (!this.cache || Date.now() - this.cache.at > 5000)
+      this.cache = { at: Date.now(), files: listWorkspaceFiles(this.root) };
+    return this.cache.files;
+  }
+  override async getSuggestions(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+    options: { signal: AbortSignal; force?: boolean },
+  ): ReturnType<CombinedAutocompleteProvider['getSuggestions']> {
+    const before = (lines[cursorLine] ?? '').slice(0, cursorCol);
+    const match = /(?:^|[\s([{])(@"[^"]*|@[^\s"]*)$/.exec(before);
+    if (!match) return super.getSuggestions(lines, cursorLine, cursorCol, options);
+    if (options.signal.aborted) return null;
+    const prefix = match[1]!;
+    const quoted = prefix.startsWith('@"');
+    const items = rankFiles(this.files(), prefix.slice(quoted ? 2 : 1))
+      .slice(0, 20)
+      .map((file) => ({
+        value: quoted || /\s/.test(file) ? `@"${file}"` : `@${file}`,
+        label: basename(file),
+        description: file,
+      }));
+    return items.length ? { items, prefix } : null;
+  }
+}

package/src/tui-modals.ts

@@ -152,13 +152,17 @@ export class FormModal implements Component, Focusable {
         this.theme.ink(this.labels?.field ?? 'Project directory', 'muted'),
         ...this.input.render(Math.max(1, width - 4)).map((line) => this.theme.ink(line)),
         '',
-        this.theme.ink(
-          this.allowCoding
-            ? this.coding
-              ? '[✓] Coding workspace · guarded tools'
-              : '[ ] Conversation session'
-            : (this.labels?.hint ?? 'Conversation session · coding service is off'),
-          this.coding ? 'jade' : 'muted',
+        // A long hint (the YOLO warning) wraps instead of running past the frame.
+        ...wrapTextWithAnsi(
+          this.theme.ink(
+            this.allowCoding
+              ? this.coding
+                ? '[✓] Coding workspace · guarded tools'
+                : '[ ] Conversation session'
+              : (this.labels?.hint ?? 'Conversation session · coding service is off'),
+            this.coding ? 'jade' : 'muted',
+          ),
+          Math.max(1, width - 4),
         ),
         '',
         this.theme.key('enter', this.labels?.submit ?? 'create') +
@@ -191,7 +195,11 @@ export class ConfirmModal implements Component, Focusable {
     readonly renderAgain: () => void,
     readonly close: () => void,
     readonly confirm: () => void,
-  ) {}
+    /** Start on the action rather than on "Keep current state" (cancel a running turn). */
+    confirmByDefault = false,
+  ) {
+    this.selected = confirmByDefault;
+  }
   invalidate(): void {}
   render(width: number): string[] {
     return framed(
@@ -230,11 +238,40 @@ export class ConfirmModal implements Component, Focusable {
     this.renderAgain();
   }
 }
+export type ApprovalDecision = 'approve' | 'approve-session' | 'always' | 'deny' | 'deny-feedback';
+/**
+ * Why a request asks, in one plain line (trial polish #2): the danger check's verdict when it has
+ * one, otherwise what the session mode leaves to a person.
+ */
+export function approvalReason(value: string, mode: string | undefined): string {
+  const danger = /^Dangerous \(([^)]+)\): (.*)$/m.exec(value);
+  if (danger) return `Asks because this command is dangerous (${danger[1]}): ${danger[2]}`;
+  const outside = /^Outside the sandbox: (.*?)\. This one command/m.exec(value);
+  if (outside) return `Asks because it wants to run outside the sandbox: ${outside[1]}`;
+  const edit = /^(---|\+\+\+) /m.test(value) && !/\nCommand:\n/.test(value);
+  if (mode === 'review') return 'Asks because review mode asks before every edit and command.';
+  if (mode === 'accept-edits' && !edit)
+    return 'Asks because accept edits still asks before commands.';
+  if (mode === 'auto')
+    return edit
+      ? 'Asks because this edit is outside what auto mode approves on its own.'
+      : 'Asks because auto mode approves only sandboxed commands it can read.';
+  return 'Asks because nothing approves this request on its own.';
+}
+/**
+ * The approval prompt (phase 2a): what will run, in plain words, with the exact binding (approval
+ * id, digest, revision, expiry) one key away rather than in the way. Desk sessions can also approve
+ * for the rest of the session or always for this repo; strict work only ever approves once. A
+ * request longer than the screen must be read to the end before anything but Deny is possible, and
+ * a request that changed or expired cannot be approved at all.
+ */
+export { onceOnlyReason } from './approval-rules.js';
 export class ApprovalModal implements Component, Focusable {
   focused = false;
   offset = 0;
   reviewed = false;
-  approve = false;
+  showDetails = false;
+  choice = 0;
   private total = 0;
   private pageSize = 1;
   private stale = false;
@@ -246,25 +283,86 @@ export class ApprovalModal implements Component, Focusable {
     readonly current: () => Approval | undefined,
     readonly renderAgain: () => void,
     readonly close: () => void,
-    readonly decide: (decision: 'approve' | 'deny') => void,
-  ) {}
+    readonly decide: (decision: ApprovalDecision) => void,
+    readonly offerRules = false,
+    /** Why only Approve once and Deny are offered, shown above the choices. */
+    readonly onceOnly?: string,
+    /**
+     * Desk sessions (trial polish #1) see the change and decide; there is no read-to-the-end gate
+     * there, since the person chose the session and its mode. Strict work keeps the gate.
+     */
+    readonly options: { desk?: boolean; reason?: string } = {},
+  ) {
+    this.choice = 1;
+  }
+  private choices(): {
+    decision: ApprovalDecision;
+    key: string;
+    label: string;
+    colour: 'amber' | 'jade';
+  }[] {
+    return [
+      { decision: 'deny', key: 'n', label: 'Deny', colour: 'amber' },
+      { decision: 'approve', key: 'y', label: 'Approve once', colour: 'jade' },
+      ...(this.options.desk
+        ? [
+            {
+              decision: 'deny-feedback' as const,
+              key: 'f',
+              label: 'Deny and tell it why',
+              colour: 'amber' as const,
+            },
+          ]
+        : []),
+      ...(this.offerRules
+        ? [
+            {
+              decision: 'approve-session' as const,
+              key: 's',
+              label: 'Approve for this session',
+              colour: 'jade' as const,
+            },
+            {
+              decision: 'always' as const,
+              key: 'a',
+              label: 'Always allow in this repo',
+              colour: 'jade' as const,
+            },
+          ]
+        : []),
+    ];
+  }
   invalidate(): void {}
   render(width: number): string[] {
     const a = this.approval,
       op = this.operation,
       t = this.theme,
       inner = Math.max(1, width - 4);
-    const details = [
-      `Operation: ${op.kind}`,
-      `Target: ${safeText(op.target)}`,
-      'Value:',
-      safeText(op.value),
-      `Expected target version: ${safeText(op.target_version)}`,
-      `Approval: ${a.id}`,
-      `Digest: ${a.operation_digest}`,
-      `Revision: ${a.revision} · worker epoch: ${a.worker_epoch}`,
-      `Expires: ${new Date(a.expires_at).toISOString()}`,
-    ].flatMap((line) => wrapTextWithAnsi(t.ink(line), inner));
+    // A diff reads as a diff: added lines jade, removed lines red, hunk headers muted.
+    const diffInk = (line: string) =>
+      /^(\+\+\+|---) /.test(line) || line.startsWith('@@')
+        ? t.ink(line, 'muted')
+        : line.startsWith('+')
+          ? t.ink(line, 'jade')
+          : line.startsWith('-')
+            ? t.ink(line, 'red')
+            : t.ink(line);
+    const body = [
+      ...[safeText(op.target), ''].flatMap((line) => wrapTextWithAnsi(t.ink(line), inner)),
+      ...safeText(op.value)
+        .split('\n')
+        .flatMap((line) => wrapTextWithAnsi(diffInk(line), inner)),
+      ...[
+        ...(this.showDetails
+          ? [
+              '',
+              `Approval ${a.id} · revision ${a.revision} · worker epoch ${a.worker_epoch}`,
+              `Digest ${a.operation_digest}`,
+              `Target version ${safeText(op.target_version)} · expires ${new Date(a.expires_at).toISOString()}`,
+            ]
+          : []),
+      ].flatMap((line) => wrapTextWithAnsi(t.ink(line), inner)),
+    ];
     const current = this.current();
     this.stale =
       !current ||
@@ -272,40 +370,67 @@ export class ApprovalModal implements Component, Focusable {
       current.operation_digest !== a.operation_digest ||
       current.revision !== a.revision ||
       Date.now() >= a.expires_at;
-    this.total = details.length;
+    this.total = body.length;
     this.pageSize = Math.max(1, Math.min(18, this.rows() - 11));
     this.offset = Math.max(0, Math.min(this.offset, Math.max(0, this.total - this.pageSize)));
-    if (this.rows() >= 12 && this.offset + this.pageSize >= this.total) this.reviewed = true;
+    if (this.options.desk || (this.rows() >= 12 && this.offset + this.pageSize >= this.total))
+      this.reviewed = true;
+    const below = this.total - (this.offset + this.pageSize);
     const disabled = !this.reviewed || this.stale;
+    const choices = this.choices();
+    this.choice = Math.max(0, Math.min(this.choice, choices.length - 1));
     return framed(
       t,
-      'Review approval',
+      'Approve?',
       [
-        ...details.slice(this.offset, this.offset + this.pageSize),
+        ...body.slice(this.offset, this.offset + this.pageSize),
         '',
-        t.ink(
-          this.stale
-            ? 'This request changed or expired. Close and refresh.'
-            : this.reviewed
-              ? 'Exact request binding reviewed.'
-              : `Scroll to the end to enable approval · ${this.offset + 1}–${Math.min(this.total, this.offset + this.pageSize)} of ${this.total}`,
-          this.stale ? 'red' : 'muted',
+        ...(this.stale
+          ? [t.ink('This request changed or expired. Close and refresh.', 'red')]
+          : this.reviewed
+            ? []
+            : [
+                t.ink(
+                  `Read to the end to approve · ${this.offset + 1}–${Math.min(this.total, this.offset + this.pageSize)} of ${this.total}`,
+                  'muted',
+                ),
+              ]),
+        ...(this.options.desk && below > 0
+          ? [t.ink(`${below} more lines · ↓ to scroll`, 'muted')]
+          : []),
+        ...(this.options.reason
+          ? wrapTextWithAnsi(t.ink(this.options.reason, 'amber'), inner)
+          : []),
+        ...(this.onceOnly ? wrapTextWithAnsi(t.ink(this.onceOnly, 'muted'), inner) : []),
+        ...choices.map((c, i) =>
+          t.ink(
+            (i === this.choice ? '› ' : '  ') + `${c.key}  ${c.label}`,
+            !c.decision.startsWith('deny') && disabled
+              ? 'muted'
+              : i === this.choice
+                ? c.colour
+                : 'muted',
+          ),
         ),
-        t.ink((this.approve ? '  ' : '› ') + 'Deny', this.approve ? 'muted' : 'amber') +
-          '     ' +
-          t.ink((this.approve ? '› ' : '  ') + 'Approve once', disabled ? 'muted' : 'jade'),
         '',
-        t.key('↑↓', 'scroll') +
-          '   ' +
-          t.key('←→', 'choose') +
+        t.key('←→', 'choose') +
           '   ' +
           t.key('enter', 'decide') +
           '   ' +
+          t.key('d', this.showDetails ? 'hide details' : 'details') +
+          '   ' +
+          t.key('↑↓', 'scroll') +
+          '   ' +
           t.key('esc', 'back'),
       ],
       width,
     );
   }
+  private pick(decision: ApprovalDecision): void {
+    if (decision !== 'deny' && decision !== 'deny-feedback' && (this.stale || !this.reviewed))
+      return;
+    this.decide(decision);
+  }
   handleInput(data: string): void {
     const current = this.current(),
       a = this.approval;
@@ -316,17 +441,22 @@ export class ApprovalModal implements Component, Focusable {
       current.revision !== a.revision ||
       current.worker_epoch !== a.worker_epoch ||
       Date.now() >= a.expires_at;
+    const choices = this.choices();
+    const byKey = choices.find((c) => c.key === data);
     if (matchesKey(data, 'escape')) this.close();
+    else if (byKey) this.pick(byKey.decision);
+    else if (data === 'd') this.showDetails = !this.showDetails;
     else if (matchesKey(data, 'down')) this.offset++;
     else if (matchesKey(data, 'up')) this.offset--;
     else if (matchesKey(data, 'pageDown')) this.offset += this.pageSize;
     else if (matchesKey(data, 'pageUp')) this.offset -= this.pageSize;
     else if (matchesKey(data, 'end')) this.offset = this.total;
     else if (matchesKey(data, 'home')) this.offset = 0;
-    else if (matchesKey(data, 'left') || matchesKey(data, 'right') || matchesKey(data, 'tab'))
-      this.approve = !this.approve;
-    else if (matchesKey(data, 'enter') && !this.stale && (!this.approve || this.reviewed))
-      this.decide(this.approve ? 'approve' : 'deny');
+    else if (matchesKey(data, 'right') || matchesKey(data, 'tab'))
+      this.choice = (this.choice + 1) % choices.length;
+    else if (matchesKey(data, 'left'))
+      this.choice = (this.choice + choices.length - 1) % choices.length;
+    else if (matchesKey(data, 'enter')) this.pick(choices[this.choice]!.decision);
     this.renderAgain();
   }
 }

package/src/tui-notify.ts

@@ -0,0 +1,77 @@
+import { spawn } from 'node:child_process';
+import type { DurableEvent } from './protocol.js';
+
+/** How the desk TUI gets a person's attention: off, a terminal bell, or a desktop notification
+ * (which also rings the bell). Set with SALAAM_NOTIFY; the bell is the default. */
+export type NotifyMode = 'off' | 'bell' | 'desktop';
+export function notifyMode(env: NodeJS.ProcessEnv = process.env): NotifyMode {
+  const v = env.SALAAM_NOTIFY;
+  return v === 'off' || v === 'desktop' ? v : 'bell';
+}
+
+/** The events worth interrupting someone for, in plain words; everything else stays quiet. */
+export function notificationFor(event: DurableEvent): string | null {
+  const p = (event.payload ?? {}) as Record<string, unknown>;
+  if (event.kind === 'approval.requested') return 'Salaam is waiting for your approval';
+  if (event.kind === 'attempt.completed') return 'Salaam finished the turn';
+  if (event.kind === 'attempt.failed') return 'Salaam’s turn failed';
+  if (event.kind === 'local.task_finished') {
+    const how =
+      p.state === 'exited'
+        ? p.exit_code === 0
+          ? 'finished'
+          : `exited with ${String(p.exit_code)}`
+        : String(p.state).replace('_', ' ');
+    return `Background command ${how}: ${String(p.command ?? '').slice(0, 80)}`;
+  }
+  return null;
+}
+
+export function notify(
+  message: string,
+  mode: NotifyMode,
+  platform: NodeJS.Platform = process.platform,
+  run: (cmd: string, args: string[]) => void = detached,
+  bell: (s: string) => void = (s) => void process.stdout.write(s),
+): void {
+  if (mode === 'off') return;
+  bell('\x07');
+  if (mode !== 'desktop') return;
+  // Passed as an argument, never interpolated into the script: a command name cannot inject.
+  if (platform === 'darwin')
+    run('osascript', [
+      '-e',
+      'on run argv\ndisplay notification (item 1 of argv) with title "Salaam"\nend run',
+      message,
+    ]);
+  else if (platform === 'linux') run('notify-send', ['Salaam', message]);
+}
+function detached(cmd: string, args: string[]): void {
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch {
+    /* the bell already rang */
+  }
+}
+
+export interface JobRow {
+  id: string;
+  command: string;
+  state: string;
+  exit_code: number | null;
+  started_at: string;
+}
+export function jobsText(tasks: JobRow[], outputs: { output: string }[]): string {
+  if (!tasks.length)
+    return 'No background commands in this session.\nThe model starts one with salaam_local background: true.';
+  return tasks
+    .map((t, i) => {
+      const state = t.state === 'exited' ? `exited ${String(t.exit_code)}` : t.state;
+      const tail = outputs[i]?.output.split('\n').slice(-12).join('\n').trimEnd();
+      return `${t.id}  ${state}  ${t.command}${tail ? '\n' + tail.replace(/^/gm, '  │ ') : ''}`;
+    })
+    .join('\n\n')
+    .concat('\n\n/jobs stop <id> stops one.');
+}

package/src/tui-review.ts

@@ -0,0 +1,76 @@
+import { relativeTime } from './session-pick.js';
+import type { CheckpointChange, CheckpointHunk } from './turn-checkpoints.js';
+import type { ChangeReview, RewindReview } from './turn-rewind.js';
+
+/** The Changes tab of a local coding session: one file selected, optionally one of its hunks. */
+export interface ReviewView {
+  data: ChangeReview | null;
+  file: number;
+  hunks?: CheckpointHunk[];
+  /** -1 means the whole file. */
+  hunk: number;
+}
+
+const SHOWN = 12;
+
+/** Background commands may keep writing while a review or rewind is open (operator ruling). */
+export function backgroundNote(running: number | undefined): string | null {
+  if (!running) return null;
+  return running === 1
+    ? '1 background task running; its writes may change files. /jobs shows it.'
+    : `${running} background tasks running; their writes may change files. /jobs shows them.`;
+}
+
+export function changeCounts(change: CheckpointChange): string {
+  return change.added === null ? 'binary' : `+${change.added} −${change.removed}`;
+}
+
+/** What one confirm of a rewind does, in words. `changes` are from the folder now to the
+ * checkpoint, so a file the checkpoint has and the folder lacks is brought back. */
+export function rewindSummary(review: RewindReview): string {
+  const lines: string[] = [];
+  if (review.mode === 'conversation') lines.push('Files are not changed.');
+  else if (!review.changes.length) lines.push('Files already match the checkpoint.');
+  else {
+    lines.push(
+      `Files: ${review.changes.length} to put back as they were before turn ${review.turn}.`,
+    );
+    for (const change of review.changes.slice(0, SHOWN))
+      lines.push(
+        '  ' +
+          (change.status === 'modified'
+            ? 'restore '
+            : change.status === 'added'
+              ? 'bring back '
+              : 'remove ') +
+          change.path +
+          ` (${changeCounts(change)})`,
+      );
+    if (review.changes.length > SHOWN)
+      lines.push(`  … and ${review.changes.length - SHOWN} more files`);
+  }
+  lines.push(
+    review.mode === 'files'
+      ? 'The conversation is kept as it is.'
+      : `The conversation continues in a new session from before turn ${review.turn}; this session stays as it is, and its instruction comes back to edit.`,
+  );
+  lines.push('Commands and anything outside this folder are not undone.');
+  const note = backgroundNote(review.background_running);
+  if (note) lines.push(note);
+  return lines.join('\n');
+}
+
+/** /rewind's turn list: newest first, with how long ago each turn started. */
+export function rewindItems(
+  points: readonly { attempt_id: string; turn: number; text: string; at: string }[],
+  now = Date.now(),
+) {
+  return points
+    .slice()
+    .reverse()
+    .map((p) => ({
+      value: p.attempt_id,
+      label: `Turn ${p.turn} · ${p.text.split('\n')[0]!.slice(0, 80)}`,
+      description: relativeTime(p.at, now),
+    }));
+}