@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/src/tui-client.ts

@@ -45,7 +45,15 @@ export interface UsageView {
   known_output: number;
   known_cost: number;
   estimated_cost: number;
+  /** Prompt tokens read from or written to the provider's cache; most of a turn's input. */
+  known_cache_read?: number;
+  known_cache_write?: number;
 }
+/** All input tokens, cached or not. `known_input` alone is only the uncached part. */
+export const usageInput = (u: UsageView) =>
+  u.known_input + (u.known_cache_read ?? 0) + (u.known_cache_write ?? 0);
+/** Known and estimated costs come from different observations, so the spend is their sum. */
+export const usageCost = (u: UsageView) => u.known_cost + u.estimated_cost;
 export interface ToolActivity {
   seq: number;
   kind: string;
@@ -57,6 +65,8 @@ export interface ToolActivity {
     input?: string;
     input_truncated?: boolean;
     failed?: boolean;
+    output?: string;
+    output_truncated?: boolean;
   };
 }
 export interface LivePreview {
@@ -66,6 +76,15 @@ export interface LivePreview {
 }
 export type OperatorConnection = 'connecting' | 'connected' | 'reconnecting' | 'offline';
 /** An operator client only: the service owns workers, authority and durable outcomes. */
+/** "AGENTS.md" or "AGENTS.md (2 files)": which instruction files guide this session. */
+export function instructionsLabel(
+  summary: import('./project-instructions.js').InstructionsSummary,
+): string {
+  const names = [...new Set(summary.files.map((f) => f.path.split('/').at(-1)!))].join(' + ');
+  return summary.files.length > 1 ? `${names} (${summary.files.length} files)` : names;
+}
+/** Longest a stale control lease is waited out (the service's lease TTL is 15 s). */
+const CONTROL_LAPSE_MS = 16000;
 export class OperatorClient extends EventEmitter {
   readonly socket: string;
   readonly clientId = randomUUID();
@@ -142,7 +161,13 @@ export class OperatorClient extends EventEmitter {
     policy: import('./autonomy.js').PermissionPolicy;
     configurable: boolean;
     coding: boolean;
-    command_auto_approval: false;
+    command_auto_approval: boolean;
+    /** Phase 2b: whether this host lets a session choose full access. */
+    full_access_allowed?: boolean;
+    /** Whether this desk session may choose YOLO. */
+    yolo_allowed?: boolean;
+    /** Where the next command runs, e.g. "in a Seatbelt sandbox (workspace-write)". */
+    command_sandbox?: string;
   }> {
     if (!this.snapshot) throw new Error('Choose a session first.');
     return call(this.socket, `/v1/sessions/${this.snapshot.id}/permissions`);
@@ -150,7 +175,11 @@ export class OperatorClient extends EventEmitter {
   async setPermissions(
     session: string,
     expected: number,
-    policy: { mode: import('./autonomy.js').PermissionMode; paths: string[] },
+    policy: {
+      mode: import('./autonomy.js').PermissionMode;
+      paths: string[];
+      access?: 'full' | 'yolo';
+    },
   ): Promise<void> {
     if (this.snapshot?.id !== session)
       throw new Error('Session changed; review permissions again.');
@@ -165,6 +194,64 @@ export class OperatorClient extends EventEmitter {
     );
     await this.refresh();
   }
+  /** Desk-session approval rules (phase 2a). */
+  async approvalRules(): Promise<{
+    applies: boolean;
+    rules: import('./approval-rules.js').StoredRule[];
+    problems: string[];
+  }> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    return call(this.socket, `/v1/sessions/${this.snapshot.id}/approval-rules`);
+  }
+  /** Turn a reviewed request into a rule: its exact command words or its exact edited paths. */
+  async ruleFromOperation(operation: string, scope: 'session' | 'repo'): Promise<void> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    await call(this.socket, `/v1/sessions/${this.snapshot.id}/approval-rules`, {
+      ...this.actor(),
+      request_id: randomUUID(),
+      scope,
+      operation_id: operation,
+    });
+  }
+  async addRule(
+    scope: 'session' | 'repo',
+    rule: import('./approval-rules.js').ApprovalRule,
+  ): Promise<void> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    await call(this.socket, `/v1/sessions/${this.snapshot.id}/approval-rules`, {
+      ...this.actor(),
+      request_id: randomUUID(),
+      scope,
+      rule,
+    });
+    this.report('Rule added.');
+  }
+  async removeRule(id: string): Promise<void> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    await call(this.socket, `/v1/sessions/${this.snapshot.id}/approval-rules/${id}/remove`, {
+      ...this.actor(),
+    });
+    this.report('Rule removed.');
+  }
+  /** Your hooks and this workspace's, with their trust state (Phase 4b). */
+  async hooks(): Promise<{ sources: import('./hooks.js').HookSource[] }> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    return call(this.socket, `/v1/sessions/${this.snapshot.id}/hooks`);
+  }
+  /** Trust this workspace's hooks file as reviewed; `digest` binds the content you saw. */
+  async trustHooks(digest: string): Promise<void> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    await call(this.socket, `/v1/sessions/${this.snapshot.id}/hooks/trust`, {
+      ...this.actor(),
+      digest,
+    });
+    this.report('Workspace hooks trusted. They run from the next tool call or prompt.');
+  }
+  async revokeHooks(): Promise<void> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    await call(this.socket, `/v1/sessions/${this.snapshot.id}/hooks/revoke`, { ...this.actor() });
+    this.report('Workspace hooks no longer trusted; they will not run.');
+  }
   async steer(text: string): Promise<void> {
     if (!this.snapshot) throw new Error('Choose a session first.');
     const result = await call<{ state: string }>(
@@ -208,6 +295,99 @@ export class OperatorClient extends EventEmitter {
     await this.refresh();
     this.report('Reverted the reviewed local edit. Conversation history is preserved.');
   }
+  async checkpoints(): Promise<import('./turn-rewind.js').TurnCheckpoint[]> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    return (
+      await call<{ checkpoints: import('./turn-rewind.js').TurnCheckpoint[] }>(
+        this.socket,
+        `/v1/sessions/${this.snapshot.id}/checkpoints`,
+      )
+    ).checkpoints;
+  }
+  async rewindReview(
+    attempt: string,
+    mode: import('./turn-rewind.js').RewindMode,
+  ): Promise<import('./turn-rewind.js').RewindReview> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    return call(
+      this.socket,
+      `/v1/sessions/${this.snapshot.id}/rewind?attempt=${encodeURIComponent(attempt)}&mode=${mode}`,
+    );
+  }
+  /** Returns the rewound turn's instruction so it can be edited and sent again. */
+  async rewind(review: import('./turn-rewind.js').RewindReview): Promise<string> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    const id = this.snapshot.id;
+    const result = await call<{ state: string; session_id: string; text: string }>(
+      this.socket,
+      `/v1/sessions/${id}/rewind`,
+      {
+        ...this.actor(),
+        request_id: randomUUID(),
+        attempt_id: review.attempt_id,
+        mode: review.mode,
+        review_digest: review.digest,
+      },
+    );
+    if (result.state !== 'completed')
+      throw new Error('Rewind outcome is uncertain; inspect files before continuing.');
+    if (result.session_id !== id) await this.open(result.session_id);
+    else await this.refresh();
+    this.report(
+      (review.mode === 'conversation'
+        ? 'Conversation'
+        : review.mode === 'files'
+          ? 'Files'
+          : 'Files and conversation') +
+        ` rewound to before turn ${review.turn}.` +
+        (result.session_id !== id ? ' The earlier conversation stays as its own session.' : ''),
+    );
+    return result.text;
+  }
+  async changeReview(): Promise<import('./turn-rewind.js').ChangeReview | null> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    return (
+      await call<{ review: import('./turn-rewind.js').ChangeReview | null }>(
+        this.socket,
+        `/v1/sessions/${this.snapshot.id}/review`,
+      )
+    ).review;
+  }
+  async changeHunks(
+    review: import('./turn-rewind.js').ChangeReview,
+    path: string,
+  ): Promise<import('./turn-checkpoints.js').CheckpointHunk[]> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    const q = new URLSearchParams({ path, base: review.base, current: review.current });
+    return (
+      await call<{ hunks: import('./turn-checkpoints.js').CheckpointHunk[] }>(
+        this.socket,
+        `/v1/sessions/${this.snapshot.id}/review/hunks?${q}`,
+      )
+    ).hunks;
+  }
+  async changeAct(
+    review: import('./turn-rewind.js').ChangeReview,
+    action: 'accept' | 'revert',
+    path: string,
+    hunk?: import('./turn-checkpoints.js').CheckpointHunk,
+  ): Promise<import('./turn-rewind.js').ChangeReview | null> {
+    if (!this.snapshot) throw new Error('Choose a session first.');
+    return (
+      await call<{ review: import('./turn-rewind.js').ChangeReview | null }>(
+        this.socket,
+        `/v1/sessions/${this.snapshot.id}/review`,
+        {
+          ...this.actor(),
+          action,
+          path,
+          base: review.base,
+          current: review.current,
+          ...(hunk ? { hunk } : {}),
+        },
+      )
+    ).review;
+  }
   async fork(): Promise<void> {
     if (!this.snapshot) throw new Error('Choose a session first.');
     const session = await call<Session>(this.socket, `/v1/sessions/${this.snapshot.id}/fork`, {
@@ -291,15 +471,15 @@ export class OperatorClient extends EventEmitter {
     this.snapshot = await call<SessionSnapshot>(this.socket, `/v1/sessions/${id}/snapshot`);
     if (!options.observe) {
       try {
-        this.lease = await acquireControl(this.socket, id, this.clientId, options.takeover);
+        this.lease = await this.acquireOrWait(id, options.takeover);
       } catch (error) {
         if (
           !(error instanceof ServiceError) ||
-          !['control_conflict', 'control_required'].includes(error.code)
+          !['control_conflict', 'control_required', 'control_busy'].includes(error.code)
         )
           throw error;
         this.notice =
-          'Another client has control. You are observing; use Take control to take over.';
+          'Another terminal is using this session and still renews its control. You are observing; press ctrl+k and choose Take control to take it over.';
       }
     }
     if (this.lease) await call(this.socket, `/v1/sessions/${id}/resume`, this.actor());
@@ -313,7 +493,26 @@ export class OperatorClient extends EventEmitter {
     this.watcher = this.watch(id, generation);
     this.changed();
   }
-  private actor(): { client_id: string; token: string } {
+  /** Acquire control. A lease left by a terminal that was killed lapses within its short TTL, so
+   * wait that out once instead of opening as an observer; a live terminal renews and keeps it. */
+  private async acquireOrWait(id: string, takeover?: boolean): Promise<ControlLease> {
+    try {
+      return await acquireControl(this.socket, id, this.clientId, takeover);
+    } catch (error) {
+      if (takeover || !(error instanceof ServiceError) || error.code !== 'control_busy')
+        throw error;
+      const snapshot = await call<SessionSnapshot>(this.socket, `/v1/sessions/${id}/snapshot`);
+      const wait = snapshot.control.expires_at - Date.now();
+      if (wait <= 0 || wait > CONTROL_LAPSE_MS) throw error;
+      this.notice = `Waiting ${Math.ceil(wait / 1000)} s for the previous terminal's control to lapse…`;
+      this.changed();
+      await new Promise((done) => setTimeout(done, wait + 250));
+      const lease = await acquireControl(this.socket, id, this.clientId);
+      this.notice = 'You have control: the previous terminal had stopped.';
+      return lease;
+    }
+  }
+  actor(): { client_id: string; token: string } {
     if (!this.lease) throw new Error('Take control before sending an instruction.');
     return { client_id: this.clientId, token: this.lease.token };
   }
@@ -358,10 +557,10 @@ export class OperatorClient extends EventEmitter {
     await job;
     this.changed();
   }
-  async submit(text: string, continues?: string): Promise<string> {
+  async submit(text: string, continues?: string, confirmSensitive = false): Promise<string> {
     this.actor();
     if (!this.snapshot || !this.outbox) throw new Error('Open a session first.');
-    const record = this.outbox.enqueue(text, this.snapshot.revision, continues);
+    const record = this.outbox.enqueue(text, this.snapshot.revision, continues, confirmSensitive);
     this.notice = 'Instruction saved locally. Delivering…';
     this.changed();
     try {
@@ -374,6 +573,8 @@ export class OperatorClient extends EventEmitter {
         'Delivery pending. The saved instruction will be retried: ' + (error as Error).message;
     }
     await this.refresh().catch(() => {});
+    // A failed worker cannot take the instruction: say so instead of "accepted".
+    this.notice = sessionFailure(this.snapshot) ?? this.notice;
     this.changed();
     return record.request_id;
   }
@@ -469,6 +670,19 @@ export class OperatorClient extends EventEmitter {
     this.notice = 'Reviewed context admitted. Tool permissions are unchanged.';
     await this.refresh();
   }
+  /** Switch this session's model or thinking level between turns; the conversation carries on. */
+  async switchRoute(route: import('./provider-config.js').ProviderRoute): Promise<void> {
+    if (!this.snapshot) throw new Error('Open a session first.');
+    await call(this.socket, `/v1/sessions/${this.snapshot.id}/route`, {
+      ...this.actor(),
+      route: {
+        provider: route.provider === 'salaam-proof' ? 'offline' : route.provider,
+        ...(route.provider === 'salaam-proof' ? {} : { model: route.model }),
+        ...(route.reasoning === undefined ? {} : { reasoning: route.reasoning }),
+      },
+    });
+    await this.refresh();
+  }
   async decide(approval: Approval, decision: 'approve' | 'deny'): Promise<void> {
     if (!this.outbox) throw new Error('Open a session first.');
     this.outbox.enqueueDecision(
@@ -572,6 +786,13 @@ export class OperatorClient extends EventEmitter {
           optional<ToolActivity[]>(`/v1/sessions/${id}/activity`),
         ]);
         if (generation !== this.generation) return;
+        const before =
+          this.snapshot?.id === snapshot.id ? this.snapshot.project_instructions : null;
+        const after = snapshot.project_instructions;
+        if (before && after && after.revision > before.revision)
+          this.notice = after.files.length
+            ? 'Project instructions changed · reloaded ' + instructionsLabel(after)
+            : 'Project instructions removed';
         this.snapshot = snapshot;
         this.health = health;
         this.commands = commands ?? [];
@@ -616,6 +837,7 @@ export class OperatorClient extends EventEmitter {
         (event: DurableEvent) => {
           if (event.seq <= cursor || generation !== this.generation) return;
           cursor = event.seq;
+          this.emit('durable', event);
           if (
             [
               'attempt.completed',
@@ -692,3 +914,12 @@ export class OperatorClient extends EventEmitter {
     await this.leave();
   }
 }
+
+/** What went wrong when a session's worker has failed, for the status line and the Changes tab. */
+export function sessionFailure(
+  s: { state: string; error: string | null } | undefined,
+): string | undefined {
+  if (!s) return undefined;
+  if (s.state !== 'unhealthy' && !(s.state === 'exited' && s.error)) return undefined;
+  return `Session stopped: ${s.error ?? 'the worker is not healthy'}. Fix it, then /new or ctrl+n for a fresh session.`;
+}

package/src/tui-commands.ts

@@ -17,15 +17,11 @@ export const SLASH_COMMANDS: readonly SlashDefinition[] = [
   command('help', 'Show commands and their execution type', ['commands'], '[command]'),
   command('exit', 'Detach; preserve the session and running work', ['quit', 'q']),
   command('keys', 'Show keyboard shortcuts', ['hotkeys']),
-  command('model', 'Choose provider and model for a new session', ['models'], '[provider/model]'),
-  command('provider', 'Choose a provider for a new session', [], '[provider]'),
-  command('thinking', 'Choose reasoning effort for a new session', [], '[level]'),
-  command(
-    'coding',
-    'New local coding session with reviewed edits and unsandboxed commands',
-    [],
-    '[workspace]',
-  ),
+  command('model', 'Switch this session’s provider and model', ['models'], '[provider/model]'),
+  command('provider', 'Switch this session’s provider', [], '[provider]'),
+  command('thinking', 'Switch this session’s reasoning effort', [], '[level]'),
+  command('coding', 'New local coding session with reviewed edits and commands', [], '[workspace]'),
+  command('init', 'Draft an AGENTS.md for this repository; the edit asks for approval'),
   command('new', 'Create a session in a workspace', [], '[workspace]'),
   command('sessions', 'Switch or resume a session', ['resume'], '[session-id]'),
   command('name', 'Set a durable session label', ['rename'], '<name>'),
@@ -39,9 +35,30 @@ export const SLASH_COMMANDS: readonly SlashDefinition[] = [
     [],
     '<text>',
   ),
-  command('diff', 'Review workspace changes'),
+  command('diff', 'Review workspace changes file by file'),
+  command(
+    'commit',
+    'Draft a commit of the current work; staging and the commit each ask (uses provider credits)',
+    [],
+    undefined,
+    'model',
+  ),
+  command('branch', 'Switch to a branch, creating it if needed', [], '<name>', 'model'),
+  command(
+    'pr',
+    'Push this branch and open a pull request; both always ask, except in YOLO',
+    [],
+    '[base]',
+    'model',
+  ),
   command('tools', 'Inspect available capabilities and recorded tool activity'),
   command('permissions', 'Configure local permissions independently of task progression'),
+  command('mode', 'Cycle review → accept edits → auto (shift+tab)'),
+  command(
+    'full-access',
+    'Turn full access on or off: commands run without the OS sandbox; dangerous ones still ask',
+  ),
+  command('yolo', 'Turn YOLO on (type yolo to confirm) or off: no sandbox and no approvals'),
   command('approvals', 'Review exact pending approval requests'),
   command('context', 'Inspect session context, facts and usage'),
   command('usage', 'Show recorded usage and unknown observations'),
@@ -50,6 +67,7 @@ export const SLASH_COMMANDS: readonly SlashDefinition[] = [
   command('export', 'Export full durable conversation as Markdown; never overwrite', [], '[path]'),
   command('settings', 'Choose terminal appearance and model settings'),
   command('fork', 'Fork an idle local conversation; keep the same workspace'),
+  command('rewind', 'Rewind files, conversation or both to before an earlier turn', [], '[turn]'),
   command(
     'undo',
     'Review and revert the last completed local edit; retain conversation history',
@@ -80,6 +98,19 @@ export const SLASH_COMMANDS: readonly SlashDefinition[] = [
   command('agents', 'Inspect native/external worker profiles and child work'),
   command('progression', 'Choose manual or bounded task progression; permissions stay separate'),
   command('tasks', 'Open durable task actions'),
+  command(
+    'classifier',
+    'Pick the small-model command reviewer for this session, or turn it off',
+    [],
+    '[name|on|off]',
+  ),
+  command(
+    'hooks',
+    'Show your hooks and this workspace’s; trust or revoke the workspace file',
+    [],
+    '[trust|revoke]',
+  ),
+  command('jobs', 'Show background commands and their output, or stop one', ['bg'], '[stop <id>]'),
 ];
 export const SLASH_COMPLETIONS = SLASH_COMMANDS.flatMap((c) =>
   [c.name, ...c.aliases].map((name) => ({ name, description: c.description })),
@@ -125,3 +156,11 @@ export function slashHelp(name?: string): string {
     )
     .join('\n');
 }
+
+/** What /init asks the agent to do. The write goes through the session's normal edit approval. */
+export const INIT_INSTRUCTION = [
+  'Draft an AGENTS.md for this repository.',
+  'First read the tree and the files that define how it is built and tested (package manifests, build and CI configuration, README, existing contributor docs, any CLAUDE.md).',
+  'Then write AGENTS.md at the repository root: a short overview, the exact commands to build, test, lint and format, the code layout, and conventions a contributor must follow.',
+  'Keep it under 150 lines, state only what the files show, and if AGENTS.md already exists, propose improvements to it instead of replacing it.',
+].join(' ');

package/src/tui-composer.ts

@@ -0,0 +1,124 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/**
+ * Composer behaviour for the trial-polish batch (operator approval 2026-10-31): Ctrl+C in steps,
+ * reverse history search, persisted history that never keeps secret-looking lines, and `!command`.
+ */
+
+/** What Ctrl+C does now: stop a running turn, else clear typed text, else arm, else leave. */
+export type CtrlCAction = 'interrupt' | 'clear' | 'arm' | 'exit';
+export const CTRL_C_WINDOW_MS = 2000;
+
+export function ctrlCAction(input: {
+  running: boolean;
+  text: string;
+  armedAt: number | undefined;
+  now: number;
+}): CtrlCAction {
+  if (input.running) return 'interrupt';
+  if (input.text !== '') return 'clear';
+  if (input.armedAt !== undefined && input.now - input.armedAt <= CTRL_C_WINDOW_MS) return 'exit';
+  return 'arm';
+}
+
+const SECRET_PATTERNS: RegExp[] = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+  /\b(sk|rk|pk)-[A-Za-z0-9_-]{16,}/,
+  /\bsk-ant-[A-Za-z0-9_-]{8,}/,
+  /\bgh[pousr]_[A-Za-z0-9]{20,}/,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}/,
+  /\bxox[abprs]-[A-Za-z0-9-]{10,}/,
+  /\bAKIA[0-9A-Z]{16}\b/,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\./,
+  /\b(password|passwd|secret|token|api[_-]?key|authorization)\s*[:=]\s*\S{6,}/i,
+  /\bbearer\s+[A-Za-z0-9._~+/-]{16,}/i,
+  /[A-Za-z0-9+_-]{48,}={0,2}/,
+];
+
+/** True when the text looks like it carries a credential; such text is never written to history. */
+export function looksSecret(text: string): boolean {
+  return SECRET_PATTERNS.some((p) => p.test(text));
+}
+
+export const HISTORY_LIMIT = 500;
+export const HISTORY_ENTRY_LIMIT = 8192;
+
+/** Where this user's composer history lives: $XDG_STATE_HOME/salaam/history.json, or nowhere when
+ * SALAAM_HISTORY=off (history then lasts only for this terminal). */
+export function historyPath(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  if (env.SALAAM_HISTORY === 'off') return undefined;
+  const base = env.XDG_STATE_HOME || join(env.HOME || homedir(), '.local', 'state');
+  return join(base, 'salaam', 'history.json');
+}
+
+/** Per-user composer history, newest last, bounded, and without secret-looking entries. */
+export class ComposerHistory {
+  entries: string[] = [];
+  constructor(private readonly path: string | undefined) {
+    try {
+      if (path && existsSync(path)) {
+        const raw: unknown = JSON.parse(readFileSync(path, 'utf8'));
+        if (Array.isArray(raw))
+          this.entries = raw
+            .filter((e): e is string => typeof e === 'string')
+            .filter((e) => keepable(e))
+            .slice(-HISTORY_LIMIT);
+      }
+    } catch {
+      this.entries = [];
+    }
+  }
+  /** Adds a sent message. Returns false when it was not kept (blank, too long, or secret-looking). */
+  add(text: string): boolean {
+    if (!keepable(text)) return false;
+    this.entries = this.entries.filter((e) => e !== text);
+    this.entries.push(text);
+    if (this.entries.length > HISTORY_LIMIT) this.entries = this.entries.slice(-HISTORY_LIMIT);
+    this.save();
+    return true;
+  }
+  private save(): void {
+    if (!this.path) return;
+    try {
+      mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+      const tmp = this.path + '.tmp';
+      writeFileSync(tmp, JSON.stringify(this.entries), { mode: 0o600 });
+      chmodSync(tmp, 0o600);
+      renameSync(tmp, this.path);
+    } catch {
+      // History is a convenience; failing to save never blocks sending.
+    }
+  }
+}
+
+function keepable(text: string): boolean {
+  return text.trim() !== '' && text.length <= HISTORY_ENTRY_LIMIT && !looksSecret(text);
+}
+
+/**
+ * Reverse-incremental search: the newest entry older than `before` (an index into `entries`,
+ * newest last) that contains the query, case-insensitively. Returns its index or -1.
+ */
+export function searchHistory(entries: string[], query: string, before: number): number {
+  const q = query.toLowerCase();
+  for (let i = Math.min(before, entries.length) - 1; i >= 0; i--)
+    if (entries[i]!.toLowerCase().includes(q)) return i;
+  return -1;
+}
+
+/** The status-line text while searching, matching readline's wording. */
+export function searchPrompt(query: string, match: string | undefined): string {
+  const shown = match === undefined ? '' : match.replace(/\s+/g, ' ').slice(0, 120);
+  return match === undefined && query !== ''
+    ? `(failing reverse-i-search)\`${query}': · esc cancels`
+    : `(reverse-i-search)\`${query}': ${shown} · enter keeps · ctrl+r older · esc cancels`;
+}
+
+/**
+ * `!command` from the composer. The TUI never runs it itself: it becomes an instruction for the
+ * model to run exactly this command through salaam_local, so it takes the same approval path,
+ * session mode, sandbox and danger check as any model command. Returns undefined for other text.
+ */
+export { shellPassthrough } from './shell-passthrough.js';