@deepseek-harness-tui/dsh-tui 0.5.2 → 0.5.3

package/README.md

@@ -95,6 +95,12 @@ TUI 启动后会在后台检查 npm 是否有新版本；发现更新时会提
 | `?` | 快捷键菜单 |
 | `Shift+↑` | 消息选择模式（Enter 展开单条） |
 
+**macOS 修饰键**：上表中 Windows/Linux 的 `Ctrl+<键>` 在 macOS 上同时可用 `⌘<键>`
+（如 `⌘V` 粘贴、`⌘O` 展开详情、`⌘Enter` 立即发送）；仅 `Ctrl+C` / `Ctrl+D`
+（中断/退出）保持 Ctrl 不变，避免与 macOS 系统级 `⌘C` 复制等肌肉记忆冲突。
+`⌘` 需终端支持扩展键盘协议（iTerm2 / kitty / WezTerm / ghostty / tmux）；
+macOS 自带 Terminal.app 会自行消费 `⌘` 快捷键，请继续使用 `Ctrl`。
+
 **鼠标（`fullscreen: true` 全屏模式；默认关，profile 补丁层覆盖开启）**
 
 | 操作 | 功能 |

package/lib/types/approvals.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Approval store — the UI-side answerer half of the DSH approval seam
+ * (`ctx.approval`). The harness's permission layer asks
+ * `ApprovalService.request()`, which dispatches an `approval/request`
+ * waterfall; the listener registered in plugin.ts parks the request here,
+ * surfaces one ask at a time to the TUI (Claude Code style permission
+ * prompt), and settles the harness promise when the user decides, the
+ * asker's abort signal fires, or the plugin tears down.
+ *
+ * Queue semantics mirror QuestionStore: parallel tool calls can trigger
+ * several asks before any answer is given, so asks are drained FIFO.
+ * Outcomes are the protocol's closed set — `'allowed-once'` and
+ * `'rejected'` from the panel, `'cancelled'` on abort/teardown; there is
+ * no allow-always or feedback channel in the protocol.
+ */
+import type { ApprovalOutcome, ApprovalRequest } from '@deepseek-ai/dsh-user-approval';
+/** What the TUI renders while an approval is pending. */
+export interface ApprovalSnapshot {
+    /** Stable key so the panel remounts (fresh focus state) per request. */
+    readonly key: string;
+    readonly toolName: string;
+    /** The asker's human-readable explanation, when given. */
+    readonly reason?: string;
+    /** The gated command, recovered from the paired tool/call event. */
+    readonly command?: string;
+}
+/**
+ * Approval store: parks asks from the harness's approval seam, surfaces
+ * one at a time to the TUI, and settles each ask when the user decides or
+ * the ask is withdrawn. The TUI subscribes for re-renders and decides via
+ * {@link ApprovalStore.decide}.
+ */
+export declare class ApprovalStore {
+    private readonly queue;
+    private active;
+    private readonly listeners;
+    private seq;
+    /**
+     * Cached snapshot: useSyncExternalStore requires a stable reference while
+     * nothing changed (a fresh object per call would loop re-renders).
+     */
+    private snapshotCache;
+    /**
+     * Subscribe to store changes (useSyncExternalStore contract).
+     * @param listener - Called after every mutation that changes the snapshot.
+     * @returns An unsubscribe function removing the listener.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * The approval the TUI should render now, or null when idle.
+     * @returns The cached snapshot; the reference is stable between mutations.
+     */
+    getSnapshot(): ApprovalSnapshot | null;
+    private emit;
+    /** Rebuild the cached snapshot after any mutation of active. */
+    private rebuildSnapshot;
+    /**
+     * Answerer entry point — called by the `approval/request` waterfall
+     * listener when the ask concerns the agent this TUI owns.
+     * @param req - The approval request (agent, tool, callId, reason, signal).
+     * @returns A promise settling with the user's decision, or `'cancelled'`
+     *   when the ask is withdrawn or the plugin tears down.
+     */
+    park(req: ApprovalRequest): Promise<ApprovalOutcome>;
+    /** Advance to the next queued ask, if any. */
+    private startNext;
+    /**
+     * The user decided on the current approval; settles it and drains the
+     * next queued ask if any. No-op when nothing is pending.
+     * @param outcome - `'allowed-once'` or `'rejected'`.
+     */
+    decide(outcome: 'allowed-once' | 'rejected'): void;
+    /**
+     * Settle the active and all queued asks (plugin teardown). The panel
+     * unmounts as the snapshot clears.
+     * @param outcome - The outcome every pending ask resolves with.
+     */
+    settleAll(outcome: ApprovalOutcome): void;
+}
+//# sourceMappingURL=approvals.d.ts.map

package/lib/types/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../src/approvals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA;AAGtF,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AA0CD;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAClD,OAAO,CAAC,GAAG,CAAI;IACf;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAgC;IAErD;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C;;;OAGG;IACH,WAAW,IAAI,gBAAgB,GAAG,IAAI;IAItC,OAAO,CAAC,IAAI;IAIZ,gEAAgE;IAChE,OAAO,CAAC,eAAe;IAOvB;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IA8BpD,8CAA8C;IAC9C,OAAO,CAAC,SAAS;IAOjB;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,cAAc,GAAG,UAAU,GAAG,IAAI;IAUlD;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;CAQ1C"}

package/lib/types/approvals.js

@@ -0,0 +1,170 @@
+/**
+ * Approval store — the UI-side answerer half of the DSH approval seam
+ * (`ctx.approval`). The harness's permission layer asks
+ * `ApprovalService.request()`, which dispatches an `approval/request`
+ * waterfall; the listener registered in plugin.ts parks the request here,
+ * surfaces one ask at a time to the TUI (Claude Code style permission
+ * prompt), and settles the harness promise when the user decides, the
+ * asker's abort signal fires, or the plugin tears down.
+ *
+ * Queue semantics mirror QuestionStore: parallel tool calls can trigger
+ * several asks before any answer is given, so asks are drained FIFO.
+ * Outcomes are the protocol's closed set — `'allowed-once'` and
+ * `'rejected'` from the panel, `'cancelled'` on abort/teardown; there is
+ * no allow-always or feedback channel in the protocol.
+ */
+const COMMAND_CLIP = 500;
+/**
+ * Recover the gated command from the session log: the approval request
+ * links to an already-presented tool call via `callId`, so the arguments
+ * are not duplicated on the request. Mirrors the web client's `commandOf`.
+ * @param req - The pending approval request.
+ * @returns The `command` argument when present, else the raw arguments
+ *   string (clipped), else undefined when the call cannot be found.
+ */
+function commandOf(req) {
+    if (req.callId === undefined)
+        return undefined;
+    const events = req.agent.session.events;
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const event = events[i];
+        if (event.type !== 'tool/call')
+            continue;
+        if (String(event.data.callId) !== String(req.callId))
+            continue;
+        const raw = event.data.arguments;
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed !== null && typeof parsed === 'object' && 'command' in parsed) {
+                const command = parsed.command;
+                if (typeof command === 'string')
+                    return command;
+            }
+        }
+        catch {
+            // Not JSON — fall through to the raw string.
+        }
+        return raw.length <= COMMAND_CLIP ? raw : `${raw.slice(0, COMMAND_CLIP)}…`;
+    }
+    return undefined;
+}
+/**
+ * Approval store: parks asks from the harness's approval seam, surfaces
+ * one at a time to the TUI, and settles each ask when the user decides or
+ * the ask is withdrawn. The TUI subscribes for re-renders and decides via
+ * {@link ApprovalStore.decide}.
+ */
+export class ApprovalStore {
+    queue = [];
+    active;
+    listeners = new Set();
+    seq = 0;
+    /**
+     * Cached snapshot: useSyncExternalStore requires a stable reference while
+     * nothing changed (a fresh object per call would loop re-renders).
+     */
+    snapshotCache = null;
+    /**
+     * Subscribe to store changes (useSyncExternalStore contract).
+     * @param listener - Called after every mutation that changes the snapshot.
+     * @returns An unsubscribe function removing the listener.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * The approval the TUI should render now, or null when idle.
+     * @returns The cached snapshot; the reference is stable between mutations.
+     */
+    getSnapshot() {
+        return this.snapshotCache;
+    }
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+    /** Rebuild the cached snapshot after any mutation of active. */
+    rebuildSnapshot() {
+        const pending = this.active;
+        this.snapshotCache = pending === undefined
+            ? null
+            : { key: pending.key, ...pending.snapshot };
+    }
+    /**
+     * Answerer entry point — called by the `approval/request` waterfall
+     * listener when the ask concerns the agent this TUI owns.
+     * @param req - The approval request (agent, tool, callId, reason, signal).
+     * @returns A promise settling with the user's decision, or `'cancelled'`
+     *   when the ask is withdrawn or the plugin tears down.
+     */
+    park(req) {
+        return new Promise(resolve => {
+            const command = commandOf(req);
+            const pending = {
+                key: String(++this.seq),
+                snapshot: {
+                    toolName: req.toolName,
+                    ...(req.reason !== undefined ? { reason: req.reason } : {}),
+                    ...(command !== undefined ? { command } : {}),
+                },
+                resolve,
+                onAbort: () => {
+                    if (this.active === pending) {
+                        this.active = undefined;
+                        this.rebuildSnapshot();
+                        pending.resolve('cancelled');
+                        this.startNext();
+                        return;
+                    }
+                    const at = this.queue.indexOf(pending);
+                    if (at >= 0)
+                        this.queue.splice(at, 1);
+                    pending.resolve('cancelled');
+                },
+            };
+            req.signal?.addEventListener('abort', pending.onAbort, { once: true });
+            this.queue.push(pending);
+            this.startNext();
+        });
+    }
+    /** Advance to the next queued ask, if any. */
+    startNext() {
+        if (this.active !== undefined || this.queue.length === 0)
+            return;
+        this.active = this.queue.shift();
+        this.rebuildSnapshot();
+        this.emit();
+    }
+    /**
+     * The user decided on the current approval; settles it and drains the
+     * next queued ask if any. No-op when nothing is pending.
+     * @param outcome - `'allowed-once'` or `'rejected'`.
+     */
+    decide(outcome) {
+        const pending = this.active;
+        if (pending === undefined)
+            return;
+        this.active = undefined;
+        this.rebuildSnapshot();
+        pending.resolve(outcome);
+        this.startNext();
+        this.emit();
+    }
+    /**
+     * Settle the active and all queued asks (plugin teardown). The panel
+     * unmounts as the snapshot clears.
+     * @param outcome - The outcome every pending ask resolves with.
+     */
+    settleAll(outcome) {
+        const active = this.active;
+        this.active = undefined;
+        this.rebuildSnapshot();
+        active?.resolve(outcome);
+        for (const pending of this.queue.splice(0))
+            pending.resolve(outcome);
+        this.emit();
+    }
+}

package/lib/types/commands.d.ts

@@ -9,7 +9,11 @@
 export interface LocalCommand {
     /** The command name without the slash, e.g. `clear`. */
     name: string;
-    /** One-line description shown in the suggestion overlay. */
+    /**
+     * One-line description shown in the suggestion overlay — the English text
+     * and the fallback for languages without a `cmd-desc-<name>` dict entry
+     * (see {@link localizedDescription}).
+     */
     description: string;
     /** Optional bracket tag shown between name and description. */
     tag?: string;
@@ -21,6 +25,15 @@ export interface LocalCommand {
  * commands merge in at runtime; locals win on name collisions.
  */
 export declare const LOCAL_COMMANDS: LocalCommand[];
+/**
+ * Resolve a command's description in the active UI language. The en text in
+ * `LOCAL_COMMANDS` (and the registry's own text for external commands) is
+ * the fallback; zh translations live in the i18n dict under
+ * `cmd-desc-<name>`. Resolved at call time — components call this during
+ * render, so a `/lang` switch repaints descriptions immediately.
+ * @param command - The command whose description to localize.
+ */
+export declare function localizedDescription(command: LocalCommand): string;
 /**
  * Parse a slash-command line into its name and the verbatim input following
  * the name (separator whitespace included) — the same split the DSH command

package/lib/types/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAA;IACnB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,YAAY,EA+CxC,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,GACX;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAIhD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,SAAS,YAAY,EAAmB,GAC7C,OAAO,CAKT;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,SAAS,YAAY,EAAmB,GAC7C,YAAY,EAAE,CAKhB"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,YAAY,EA+CxC,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAElE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,GACX;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAIhD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,SAAS,YAAY,EAAmB,GAC7C,OAAO,CAKT;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,SAAS,YAAY,EAAmB,GAC7C,YAAY,EAAE,CAKhB"}

package/lib/types/commands.js

@@ -6,6 +6,7 @@
  * `runCommand` in the Chat screen dispatches either kind, with the registry
  * handler winning for names both sides declare.
  */
+import { tOr } from './i18n.js';
 /**
  * The built-in slash commands (name + description pairs). Plugin-registered
  * commands merge in at runtime; locals win on name collisions.
@@ -58,6 +59,17 @@ export const LOCAL_COMMANDS = [
     { name: 'help', description: 'Show shortcuts and commands' },
     { name: 'exit', description: 'Exit dsh-tui' },
 ];
+/**
+ * Resolve a command's description in the active UI language. The en text in
+ * `LOCAL_COMMANDS` (and the registry's own text for external commands) is
+ * the fallback; zh translations live in the i18n dict under
+ * `cmd-desc-<name>`. Resolved at call time — components call this during
+ * render, so a `/lang` switch repaints descriptions immediately.
+ * @param command - The command whose description to localize.
+ */
+export function localizedDescription(command) {
+    return tOr(`cmd-desc-${command.name}`, command.description);
+}
 /**
  * Parse a slash-command line into its name and the verbatim input following
  * the name (separator whitespace included) — the same split the DSH command

package/lib/types/compat/sessionLog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sessionLog.d.ts","sourceRoot":"","sources":["../../../src/compat/sessionLog.ts"],"names":[],"mappings":"AA8BA,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,OAAO,GACP,aAAa,CAAA;AAkEjB;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CA6BhF;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9E"}
+{"version":3,"file":"sessionLog.d.ts","sourceRoot":"","sources":["../../../src/compat/sessionLog.ts"],"names":[],"mappings":"AAiCA,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,OAAO,GACP,aAAa,CAAA;AA4EjB;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAsChF;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9E"}

package/lib/types/compat/sessionLog.js

@@ -16,10 +16,13 @@
  * marked, and already-known events are never touched.
  *
  * Storage notes: the jsonl persistence flushes by APPENDING zstd frames, so
- * the file is a concatenation of frames; every frame is decoded, the log is
- * rewritten as one frame, and the file is swapped in atomically (tmp +
- * rename). Any decode/parse anomaly aborts the repair and resume proceeds
- * unpatched — the failure mode degrades to the pre-patch behavior.
+ * the file is a concatenation of frames. Frame layout is load-bearing: the
+ * backend asserts frame 0 holds EXACTLY the header line (listings read only
+ * that frame; `assertZstdHeaderFrame`), so the repair re-encodes each frame
+ * with its original line set — frame boundaries are preserved 1:1, and any
+ * frame whose lines were untouched is copied verbatim. Any decode/parse
+ * anomaly aborts the repair and resume proceeds unpatched — the failure
+ * mode degrades to the pre-patch behavior.
  * @module @deepseek-harness-tui/dsh-tui/compat/sessionLog
  */
 import { KNOWN_SESSION_EVENT_TYPES } from '@deepseek-ai/dsh-session';
@@ -61,11 +64,12 @@ function findSessionLogFile(sessionId) {
     return undefined;
 }
 /**
- * Decode a (possibly multi-frame) zstd jsonl log. Frames are split by magic
- * scan; any frame failing to decode or any line failing to parse throws, so
- * callers abort instead of rewriting a log they did not fully understand.
+ * Decode a (possibly multi-frame) zstd jsonl log, keeping frames separate.
+ * Frames are split by magic scan; any frame failing to decode or any line
+ * failing to parse throws, so callers abort instead of rewriting a log they
+ * did not fully understand.
  * @param buf - Raw file bytes.
- * @returns Parsed event envelopes in log order.
+ * @returns Per-frame byte spans and parsed event envelopes, in log order.
  */
 function decodeFrames(buf) {
     const offsets = [];
@@ -75,20 +79,21 @@ function decodeFrames(buf) {
     }
     if (offsets.length === 0)
         throw new Error('no zstd frame found');
-    let text = '';
-    for (let i = 0; i < offsets.length; i++) {
+    return offsets.map((start, i) => {
         const end = i + 1 < offsets.length ? offsets[i + 1] : buf.length;
-        text += zstdDecompressSync(buf.subarray(offsets[i], end)).toString('utf8');
-    }
-    return text
-        .split('\n')
-        .filter((line) => line.length > 0)
-        .map((line) => {
-        const parsed = JSON.parse(line);
-        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-            throw new Error('session log line is not an event envelope');
-        }
-        return parsed;
+        const raw = buf.subarray(start, end);
+        const text = zstdDecompressSync(raw).toString('utf8');
+        const events = text
+            .split('\n')
+            .filter((line) => line.length > 0)
+            .map((line) => {
+            const parsed = JSON.parse(line);
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                throw new Error('session log line is not an event envelope');
+            }
+            return parsed;
+        });
+        return { raw, events };
     });
 }
 /**
@@ -103,25 +108,35 @@ export function repairSessionLogForResume(sessionId) {
         const file = findSessionLogFile(sessionId);
         if (file === undefined)
             return 'unavailable';
-        const events = decodeFrames(readFileSync(file));
-        let changed = false;
-        for (const event of events) {
-            const type = event['type'];
-            // Only real log entries carry a numeric seq — the seq-less header row
-            // is parsed by a separate path that must not see an extra field.
-            if (typeof type === 'string' &&
-                typeof event['seq'] === 'number' &&
-                !KNOWN_SESSION_EVENT_TYPES.has(type) &&
-                event['ignorable'] === undefined) {
-                event['ignorable'] = true;
-                changed = true;
+        const frames = decodeFrames(readFileSync(file));
+        // Mark unknown types in place, tracking which frames actually changed:
+        // untouched frames are copied back verbatim, so the header frame keeps
+        // its exact original bytes (and the one-header-line invariant with it).
+        const dirty = new Set();
+        frames.forEach((frame, index) => {
+            for (const event of frame.events) {
+                const type = event['type'];
+                // Only real log entries carry a numeric seq — the seq-less header row
+                // is parsed by a separate path that must not see an extra field.
+                if (typeof type === 'string' &&
+                    typeof event['seq'] === 'number' &&
+                    !KNOWN_SESSION_EVENT_TYPES.has(type) &&
+                    event['ignorable'] === undefined) {
+                    event['ignorable'] = true;
+                    dirty.add(index);
+                }
             }
-        }
-        if (!changed)
+        });
+        if (dirty.size === 0)
             return 'clean';
-        const payload = events.map((event) => JSON.stringify(event)).join('\n') + '\n';
+        const parts = frames.map((frame, index) => {
+            if (!dirty.has(index))
+                return frame.raw;
+            const payload = frame.events.map((event) => JSON.stringify(event)).join('\n') + '\n';
+            return zstdCompressSync(Buffer.from(payload, 'utf8'));
+        });
         const tmp = `${file}.compat-${randomUUID()}.tmp`;
-        writeFileSync(tmp, zstdCompressSync(Buffer.from(payload, 'utf8')));
+        writeFileSync(tmp, Buffer.concat(parts));
         renameSync(tmp, file);
         return 'repaired';
     }

package/lib/types/components/CommandSuggestions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommandSuggestions.d.ts","sourceRoot":"","sources":["../../../src/components/CommandSuggestions.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAIzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAElD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,aAAa,EACb,OAAO,GACR,EAAE;IACD,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;IACjC,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,KAAK,CAAC,SAAS,CAoDlB"}
+{"version":3,"file":"CommandSuggestions.d.ts","sourceRoot":"","sources":["../../../src/components/CommandSuggestions.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAIzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAGlD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,aAAa,EACb,OAAO,GACR,EAAE;IACD,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;IACjC,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,KAAK,CAAC,SAAS,CAqDlB"}

package/lib/types/components/CommandSuggestions.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from '../ui.js';
 import { stringWidth } from '../ink/stringWidth.js';
 import { truncateToWidth } from '../ink/truncateToWidth.js';
+import { localizedDescription } from '../commands.js';
 /**
  * The slash-command suggestion overlay, ported from the leak's
  * `PromptInputFooterSuggestions.tsx` (command layout only): a name column
@@ -25,9 +26,10 @@ export function CommandSuggestions({ commands, selectedIndex, columns, }) {
             const tagText = command.tag ? `[${command.tag}] ` : '';
             const tagWidth = stringWidth(tagText);
             const descriptionWidth = Math.max(0, columns - nameWidth - tagWidth - 4);
-            const description = stringWidth(command.description) > descriptionWidth
-                ? truncateToWidth(command.description, descriptionWidth - 1) + '…'
-                : command.description;
+            const rawDescription = localizedDescription(command);
+            const description = stringWidth(rawDescription) > descriptionWidth
+                ? truncateToWidth(rawDescription, descriptionWidth - 1) + '…'
+                : rawDescription;
             return (_jsxs(Text, { wrap: "truncate", children: [_jsx(Text, { color: isSelected ? 'suggestion' : undefined, dimColor: !isSelected, children: padded }), tagText ? _jsx(Text, { dimColor: true, children: tagText }) : null, _jsx(Text, { color: isSelected ? 'suggestion' : undefined, dimColor: !isSelected, children: description })] }, command.name));
         }) }));
 }

package/lib/types/components/HelpMenu.d.ts

@@ -5,6 +5,7 @@ import type { LocalCommand } from '../commands.js';
  * (three-column shortcut layout, trimmed to the keys dsh-tui actually binds).
  * The command column lists the merged slash-command surface: built-in
  * commands plus plugin-registered ones from the DSH registry (plan/goal/…).
+ * Modifier labels follow the platform convention: ⌘ on macOS, ctrl elsewhere.
  */
 export declare function HelpMenu({ commands, }: {
     commands: readonly LocalCommand[];

package/lib/types/components/HelpMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HelpMenu.d.ts","sourceRoot":"","sources":["../../../src/components/HelpMenu.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAElD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,EACvB,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;CAClC,GAAG,KAAK,CAAC,SAAS,CA6DlB"}
+{"version":3,"file":"HelpMenu.d.ts","sourceRoot":"","sources":["../../../src/components/HelpMenu.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAIlD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,EACvB,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;CAClC,GAAG,KAAK,CAAC,SAAS,CA6DlB"}

package/lib/types/components/HelpMenu.js

@@ -1,12 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import Box from '../ink/components/Box.js';
 import Text from '../ink/components/Text.js';
+import { localizedDescription } from '../commands.js';
+import { modLabel } from '../utils/modifiers.js';
 /**
  * The `?` help menu, ported from the leak's `PromptInputHelpMenu.tsx`
  * (three-column shortcut layout, trimmed to the keys dsh-tui actually binds).
  * The command column lists the merged slash-command surface: built-in
  * commands plus plugin-registered ones from the DSH registry (plan/goal/…).
+ * Modifier labels follow the platform convention: ⌘ on macOS, ctrl elsewhere.
  */
 export function HelpMenu({ commands, }) {
-    return (_jsxs(Box, { paddingX: 2, flexDirection: "row", gap: 4, children: [_jsxs(Box, { flexDirection: "column", width: 26, flexShrink: 0, children: [_jsx(Box, { children: _jsx(Text, { dimColor: true, children: "/ for commands" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "? for this help" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "ctrl+o for verbose output" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "ctrl+t to toggle context" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "ctrl+r to search history" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "ctrl+c to interrupt" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "ctrl+d to exit" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "ctrl+l to redraw" }) })] }), _jsxs(Box, { flexDirection: "column", width: 24, flexShrink: 0, children: [_jsx(Box, { children: _jsx(Text, { dimColor: true, children: "esc to clear input" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "\u2191/\u2193 for history" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "\u2190/\u2192 to move cursor" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "ctrl+\u2190/\u2192 for word jumps" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "tab to complete command" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "shift+tab to cycle effort" }) })] }), _jsxs(Box, { flexDirection: "column", flexShrink: 1, children: [_jsx(Text, { dimColor: true, children: "commands:" }), commands.map(command => (_jsx(Box, { children: _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["/", command.name, " \u2014 ", command.description] }) }, command.name)))] })] }));
+    return (_jsxs(Box, { paddingX: 2, flexDirection: "row", gap: 4, children: [_jsxs(Box, { flexDirection: "column", width: 26, flexShrink: 0, children: [_jsx(Box, { children: _jsx(Text, { dimColor: true, children: "/ for commands" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "? for this help" }) }), _jsx(Box, { children: _jsxs(Text, { dimColor: true, children: [modLabel, "o for verbose output"] }) }), _jsx(Box, { children: _jsxs(Text, { dimColor: true, children: [modLabel, "t to toggle context"] }) }), _jsx(Box, { children: _jsxs(Text, { dimColor: true, children: [modLabel, "r to search history"] }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "ctrl+c to interrupt" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "ctrl+d to exit" }) }), _jsx(Box, { children: _jsxs(Text, { dimColor: true, children: [modLabel, "l to redraw"] }) })] }), _jsxs(Box, { flexDirection: "column", width: 24, flexShrink: 0, children: [_jsx(Box, { children: _jsx(Text, { dimColor: true, children: "esc to clear input" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "\u2191/\u2193 for history" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "\u2190/\u2192 to move cursor" }) }), _jsx(Box, { children: _jsxs(Text, { dimColor: true, children: [modLabel, "\u2190/\u2192 for word jumps"] }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "tab to complete command" }) }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "shift+tab to cycle effort" }) })] }), _jsxs(Box, { flexDirection: "column", flexShrink: 1, children: [_jsx(Text, { dimColor: true, children: "commands:" }), commands.map(command => (_jsx(Box, { children: _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["/", command.name, " \u2014 ", localizedDescription(command)] }) }, command.name)))] })] }));
 }

package/lib/types/components/PromptInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PromptInput.d.ts","sourceRoot":"","sources":["../../../src/components/PromptInput.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAMzB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAwC5C;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,IAAI,OAAO,CAAA;IAClB,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAA;IAChB,0EAA0E;IAC1E,QAAQ,EAAE,OAAO,CAAA;IACjB,YAAY,IAAI,IAAI,CAAA;IACpB;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;IACrD,6EAA6E;IAC7E,eAAe,EAAE,OAAO,CAAA;IACxB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,cAAc,CAAC,IAAI,IAAI,CAAA;IACvB,8EAA8E;IAC9E,eAAe,CAAC,IAAI,IAAI,CAAA;IACxB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,cAAc,EACd,eAAe,EACf,aAAa,GACd,EAAE,gBAAgB,qBA+xBlB"}
+{"version":3,"file":"PromptInput.d.ts","sourceRoot":"","sources":["../../../src/components/PromptInput.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAMzB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAyC5C;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,IAAI,OAAO,CAAA;IAClB,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAA;IAChB,0EAA0E;IAC1E,QAAQ,EAAE,OAAO,CAAA;IACjB,YAAY,IAAI,IAAI,CAAA;IACpB;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;IACrD,6EAA6E;IAC7E,eAAe,EAAE,OAAO,CAAA;IACxB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,cAAc,CAAC,IAAI,IAAI,CAAA;IACvB,8EAA8E;IAC9E,eAAe,CAAC,IAAI,IAAI,CAAA;IACxB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,cAAc,EACd,eAAe,EACf,aAAa,GACd,EAAE,gBAAgB,qBA+xBlB"}

package/lib/types/components/PromptInput.js

@@ -8,6 +8,7 @@ import { formatClipboardInsert, readClipboard } from '../utils/clipboard.js';
 import { filterCommands, parseCommandName } from '../commands.js';
 import { appendHistory } from '../history.js';
 import { mentionAtCaret } from '../utils/mentions.js';
+import { isMod } from '../utils/modifiers.js';
 import { CommandSuggestions } from './CommandSuggestions.js';
 import { FileSuggestions } from './FileSuggestions.js';
 import { HelpMenu } from './HelpMenu.js';
@@ -347,10 +348,10 @@ export function PromptInput({ channel, helpOpen, onToggleHelp, onRunCommand, sel
             insertAtCaret(input.replace(/\r\n/g, '\n').replace(/\r/g, '\n'));
             return;
         }
-        // Ctrl+V: raw mode hands the key to the app, so the clipboard is read
-        // here — text, or file paths when Explorer copied files (pasted files
-        // insert their paths).
-        if (key.ctrl && input === 'v') {
+        // Ctrl+V / Cmd+V: raw mode hands the key to the app, so the clipboard is
+        // read here — text, or file paths when Explorer copied files (pasted
+        // files insert their paths).
+        if (isMod(key) && input === 'v') {
             if (clipboardBusyRef.current)
                 return;
             clipboardBusyRef.current = true;
@@ -425,9 +426,9 @@ export function PromptInput({ channel, helpOpen, onToggleHelp, onRunCommand, sel
                 submitText(line);
             return;
         }
-        if (key.return && key.ctrl) {
-            // Ctrl+Enter: interrupt the running turn and process this message
-            // immediately (Windows Terminal sends CSI 13;5u / 13;1;5u).
+        if (key.return && isMod(key)) {
+            // Ctrl+Enter / Cmd+Enter: interrupt the running turn and process this
+            // message immediately (Windows Terminal sends CSI 13;5u / 13;1;5u).
             interruptSend();
             return;
         }
@@ -537,12 +538,12 @@ export function PromptInput({ channel, helpOpen, onToggleHelp, onRunCommand, sel
             setCursor(previous => Math.min(value.length, previous + 1));
             return;
         }
-        if (key.ctrl && key.leftArrow) {
+        if (isMod(key) && key.leftArrow) {
             // Jump to the previous word boundary (readline alt+b).
             setCursor(previous => wordBoundaryLeft(value, previous));
             return;
         }
-        if (key.ctrl && key.rightArrow) {
+        if (isMod(key) && key.rightArrow) {
             // Jump to the next word boundary (readline alt+f).
             setCursor(previous => wordBoundaryRight(value, previous));
             return;
@@ -572,31 +573,31 @@ export function PromptInput({ channel, helpOpen, onToggleHelp, onRunCommand, sel
             setCursor(nextLine === -1 ? value.length : nextLine);
             return;
         }
-        if (key.ctrl && input === 'a') {
+        if (isMod(key) && input === 'a') {
             const lineStart = value.lastIndexOf('\n', cursor - 1) + 1;
             setCursor(lineStart);
             return;
         }
-        if (key.ctrl && input === 'e') {
+        if (isMod(key) && input === 'e') {
             const nextLine = value.indexOf('\n', cursor);
             setCursor(nextLine === -1 ? value.length : nextLine);
             return;
         }
-        if (key.ctrl && input === 'u') {
+        if (isMod(key) && input === 'u') {
             // Delete to start of line.
             const lineStart = value.lastIndexOf('\n', cursor - 1) + 1;
             setValue(value.slice(0, lineStart) + value.slice(cursor));
             setCursor(lineStart);
             return;
         }
-        if (key.ctrl && input === 'k') {
+        if (isMod(key) && input === 'k') {
             // Delete to end of line.
             const nextLine = value.indexOf('\n', cursor);
             const end = nextLine === -1 ? value.length : nextLine;
             setValue(value.slice(0, cursor) + value.slice(end));
             return;
         }
-        if (key.ctrl && input === 'w') {
+        if (isMod(key) && input === 'w') {
             // Delete the word before the cursor (CC/readline behavior): skip
             // trailing whitespace, then the whitespace-delimited word.
             const before = value.slice(0, cursor);
@@ -678,7 +679,7 @@ export function PromptInput({ channel, helpOpen, onToggleHelp, onRunCommand, sel
             onToggleHelp();
             return;
         }
-        if (input && !key.ctrl && !key.meta && !key.tab && !key.escape) {
+        if (input && !key.ctrl && !key.meta && !key.super && !key.tab && !key.escape) {
             // Typing anything else dismisses the help menu (CC behavior).
             if (helpOpen)
                 onToggleHelp();