@aiwayds/dsh-tui-pi 0.28.0 → 1.0.0

package/lib/clipboard.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Clipboard helper for the ask-user "Type something." sentinel editor.
+ *
+ * The editor only ever needs to push free-text into the system clipboard
+ * (Ctrl+Shift+C) and read it back (right-click → paste). Terminal-side
+ * paste is already handled by the bracketed-paste path in `handleCustomInput`
+ * (see ask-user.ts); this module is the bridge to a real OS clipboard.
+ *
+ * Strategy:
+ * - `writeClipboard` writes the OSC 52 "set primary clipboard" sequence so a
+ *   host terminal that follows the convention picks the text up without
+ *   touching the OS. The sequence is capped at 64 KiB to keep the terminal
+ *   from being spammed with a multi-MB escape run for a pathological paste;
+ *   a >64 KiB OSC 52 is skipped and the local command alone is relied on.
+ *   In parallel, the best-matching local command for the platform is tried
+ *   (`pbcopy` / `wl-copy` / `xclip` / `xsel` / `clip`). Whichever path lands
+ *   first resolves `true`; the local failure is swallowed (the OSC 52 path
+ *   may still succeed, the next call may not, we never want a thrown error
+ *   to interrupt the user's keystroke).
+ * - `readClipboard` is a fall-back ladder. WAYLAND-aware first
+ *   (`wl-paste` when `WAYLAND_DISPLAY` is set), then the X11 ladder
+ *   (`xclip` → `xsel`), then macOS `pbpaste`, then Windows PowerShell.
+ *   The same command is not retried within a single process: when a binary
+ *   is missing (`ENOENT`) the platform is cached as "unavailable" and the
+ *   read is short-circuited to `null` for the remainder of the run.
+ *
+ * Every command runs through `execFile` (no shell, parameter-array argv,
+ * bounded timeout, large-enough buffer). The text path itself is raw —
+ * the ask-user side (which is the only in-tree caller) sanitizes the
+ * payload through `sanitizePastedText` before it lands in the editor
+ * buffer. Splitting the sanitize to the call site means a future caller
+ * of `readClipboard` (e.g. a feature that streams the clipboard into
+ * the chat composer) gets a faithful copy of what the OS gave us, and
+ * the editor gets its one sanitization pass.
+ *
+ * Everything is injectable through `ClipboardImpl` so the module is fully
+ * unit-testable without spawning real clipboard processes.
+ */
+/**
+ * execFile envelope. The result is `{ stdout }` on success; for write
+ * commands the caller passes a non-null `stdinPayload` that is piped in
+ * before the process exits. A `null` payload skips the stdin pipe (read
+ * commands).
+ */
+export type ExecFileFn = (file: string, args: readonly string[], options: {
+    timeout: number;
+    maxBuffer: number;
+    windowsHide: boolean;
+}, stdinPayload: string | null) => Promise<{
+    stdout: string;
+}>;
+/**
+ * Subset of the platform the resolver reads. Pulled out so tests can fake
+ * darwin/linux/win32 without touching `process.platform` / `process.env`.
+ */
+export interface ClipboardEnv {
+    platform: NodeJS.Platform;
+    waylandDisplay: string | undefined;
+    display: string | undefined;
+}
+/** All I/O the helper needs: command execution + stdout writing. */
+export interface ClipboardImpl {
+    execFile: ExecFileFn;
+    write: (chunk: string) => void;
+    env: ClipboardEnv;
+}
+/** Default impl: real process, real env. */
+export declare const defaultImpl: ClipboardImpl;
+/**
+ * Pick the write ladder for a platform. The ladder is tried SERIALLY in
+ * order — the helper short-circuits on the first rung that exits cleanly
+ * and treats a missing binary (`ENOENT`) as "try the next rung". This
+ * mirrors the read-side ladder and avoids two problems the old parallel
+ * shape had on a real Wayland + XWayland desktop:
+ *   1. `wl-copy` (Wayland) and `xclip` (X11) write the same `CLIPBOARD`
+ *      selection through different protocols; spawning them concurrently
+ *      races the two ends and the loser's payload can win.
+ *   2. `wl-copy` forks a background helper that lingers after the
+ *      `execFile` resolves; running it in parallel with every other
+ *      rung accumulated helpers with each Ctrl+Shift+C.
+ */
+export declare function writeCommandsForPlatform(env: ClipboardEnv): readonly {
+    cmd: string;
+    args: readonly string[];
+}[];
+/** Read-ladder resolver: returns the commands to try in order. */
+export declare function readCommandsForPlatform(env: ClipboardEnv): readonly {
+    cmd: string;
+    args: readonly string[];
+}[];
+/**
+ * Copy `text` to the system clipboard.
+ *
+ * Returns `true` when either the OSC 52 path succeeded AND we wrote a small
+ * enough buffer, OR any local command exited cleanly. Returns `false`
+ * when every path failed. Errors are swallowed; the helper must never
+ * throw from a key handler.
+ */
+export declare function writeClipboard(text: string, impl?: ClipboardImpl): Promise<boolean>;
+/**
+ * Read the system clipboard and return its text. The payload is the raw
+ * stdout of whichever rung landed first — the ask-user side sanitizes
+ * it through `sanitizePastedText` before the editor buffer sees it, so
+ * a future caller of this helper gets a faithful copy of what the OS
+ * gave us. Returns `null` when no read path succeeds or the platform
+ * has been cached as "unavailable" (no command found on the ladder).
+ */
+export declare function readClipboard(impl?: ClipboardImpl): Promise<string | null>;
+/**
+ * Test seam: drop the cached "platform has no read command" state. Tests
+ * inject a different `ClipboardImpl` per case, so the cache can be left
+ * full from a previous run; the seam keeps the test order independent.
+ */
+export declare function __resetClipboardUnavailableForTest(): void;

package/lib/clipboard.js

@@ -0,0 +1,236 @@
+/**
+ * Clipboard helper for the ask-user "Type something." sentinel editor.
+ *
+ * The editor only ever needs to push free-text into the system clipboard
+ * (Ctrl+Shift+C) and read it back (right-click → paste). Terminal-side
+ * paste is already handled by the bracketed-paste path in `handleCustomInput`
+ * (see ask-user.ts); this module is the bridge to a real OS clipboard.
+ *
+ * Strategy:
+ * - `writeClipboard` writes the OSC 52 "set primary clipboard" sequence so a
+ *   host terminal that follows the convention picks the text up without
+ *   touching the OS. The sequence is capped at 64 KiB to keep the terminal
+ *   from being spammed with a multi-MB escape run for a pathological paste;
+ *   a >64 KiB OSC 52 is skipped and the local command alone is relied on.
+ *   In parallel, the best-matching local command for the platform is tried
+ *   (`pbcopy` / `wl-copy` / `xclip` / `xsel` / `clip`). Whichever path lands
+ *   first resolves `true`; the local failure is swallowed (the OSC 52 path
+ *   may still succeed, the next call may not, we never want a thrown error
+ *   to interrupt the user's keystroke).
+ * - `readClipboard` is a fall-back ladder. WAYLAND-aware first
+ *   (`wl-paste` when `WAYLAND_DISPLAY` is set), then the X11 ladder
+ *   (`xclip` → `xsel`), then macOS `pbpaste`, then Windows PowerShell.
+ *   The same command is not retried within a single process: when a binary
+ *   is missing (`ENOENT`) the platform is cached as "unavailable" and the
+ *   read is short-circuited to `null` for the remainder of the run.
+ *
+ * Every command runs through `execFile` (no shell, parameter-array argv,
+ * bounded timeout, large-enough buffer). The text path itself is raw —
+ * the ask-user side (which is the only in-tree caller) sanitizes the
+ * payload through `sanitizePastedText` before it lands in the editor
+ * buffer. Splitting the sanitize to the call site means a future caller
+ * of `readClipboard` (e.g. a feature that streams the clipboard into
+ * the chat composer) gets a faithful copy of what the OS gave us, and
+ * the editor gets its one sanitization pass.
+ *
+ * Everything is injectable through `ClipboardImpl` so the module is fully
+ * unit-testable without spawning real clipboard processes.
+ */
+import { execFile as execFileCb } from 'node:child_process';
+import { Buffer } from 'node:buffer';
+/** Max UTF-8 byte length we accept into the OSC 52 write sequence. */
+const OSC52_MAX_BYTES = 65536;
+/**
+ * Default `execFile` wrapper built on the real `node:child_process`. The
+ * callback form gives us stdin for write commands (pbcopy / wl-copy / xclip
+ * / xsel / clip all consume the text on stdin); a `null` payload skips the
+ * stdin pipe entirely (read commands) and returns the collected stdout.
+ */
+function makeDefaultExecFile() {
+    return (file, args, options, stdinPayload) => new Promise((resolve, reject) => {
+        const child = execFileCb(file, [...args], options, (error, stdout) => {
+            if (error === null)
+                resolve({ stdout });
+            else
+                reject(error);
+        });
+        if (stdinPayload !== null) {
+            // A child that exists but exits before draining stdin (e.g. xclip
+            // printing "Can't open display" on Linux without an X server) raises
+            // an uncaught EPIPE on the stream; swallow it here so the helper
+            // keeps its best-effort "never throw" contract.
+            child.stdin?.on('error', () => { });
+            child.stdin?.end(stdinPayload);
+        }
+    });
+}
+/** Default impl: real process, real env. */
+export const defaultImpl = {
+    execFile: makeDefaultExecFile(),
+    write: chunk => { process.stdout.write(chunk); },
+    env: {
+        platform: process.platform,
+        waylandDisplay: process.env.WAYLAND_DISPLAY,
+        display: process.env.DISPLAY,
+    },
+};
+/**
+ * Cache of platforms whose read-binary ladder is fully missing: we still
+ * retry the write path every call (a copy without a way to read it back is
+ * still useful), but a read that would just re-spawn a missing ENOENT
+ * short-circuits to `null` so the right-click path stays snappy.
+ */
+const readUnavailable = new Set();
+/**
+ * Pick the write ladder for a platform. The ladder is tried SERIALLY in
+ * order — the helper short-circuits on the first rung that exits cleanly
+ * and treats a missing binary (`ENOENT`) as "try the next rung". This
+ * mirrors the read-side ladder and avoids two problems the old parallel
+ * shape had on a real Wayland + XWayland desktop:
+ *   1. `wl-copy` (Wayland) and `xclip` (X11) write the same `CLIPBOARD`
+ *      selection through different protocols; spawning them concurrently
+ *      races the two ends and the loser's payload can win.
+ *   2. `wl-copy` forks a background helper that lingers after the
+ *      `execFile` resolves; running it in parallel with every other
+ *      rung accumulated helpers with each Ctrl+Shift+C.
+ */
+export function writeCommandsForPlatform(env) {
+    if (env.platform === 'darwin') {
+        return [{ cmd: 'pbcopy', args: [] }];
+    }
+    if (env.platform === 'win32') {
+        return [{ cmd: 'clip', args: [] }];
+    }
+    // Linux and friends: ONE rung per session, picked from the env. WAYLAND
+    // wins over X11 outright (a Wayland session that also exposes $DISPLAY
+    // for XWayland apps still has its native clipboard on `wl-copy`; the
+    // X11 rung would be the XWayland clipboard, a different selection).
+    // X11 falls back from xclip to xsel when xclip is not installed.
+    if (env.waylandDisplay !== undefined && env.waylandDisplay !== '') {
+        return [{ cmd: 'wl-copy', args: [] }];
+    }
+    if (env.display !== undefined && env.display !== '') {
+        return [
+            { cmd: 'xclip', args: ['-selection', 'clipboard'] },
+            { cmd: 'xsel', args: ['--clipboard', '--input'] },
+        ];
+    }
+    return [];
+}
+/** Read-ladder resolver: returns the commands to try in order. */
+export function readCommandsForPlatform(env) {
+    if (env.platform === 'darwin') {
+        return [{ cmd: 'pbpaste', args: [] }];
+    }
+    if (env.platform === 'win32') {
+        return [{ cmd: 'powershell.exe', args: ['-NoProfile', '-command', 'Get-Clipboard'] }];
+    }
+    const ladder = [];
+    if (env.waylandDisplay !== undefined && env.waylandDisplay !== '') {
+        ladder.push({ cmd: 'wl-paste', args: ['--no-newline'] });
+    }
+    if (env.display !== undefined && env.display !== '') {
+        ladder.push({ cmd: 'xclip', args: ['-o', '-selection', 'clipboard'] });
+    }
+    ladder.push({ cmd: 'xsel', args: ['--clipboard', '--output'] });
+    return ladder;
+}
+/**
+ * Copy `text` to the system clipboard.
+ *
+ * Returns `true` when either the OSC 52 path succeeded AND we wrote a small
+ * enough buffer, OR any local command exited cleanly. Returns `false`
+ * when every path failed. Errors are swallowed; the helper must never
+ * throw from a key handler.
+ */
+export async function writeClipboard(text, impl = defaultImpl) {
+    let osc52Ok = false;
+    // Cap is on UTF-8 byte length, not on the JS string length (which is
+    // a UTF-16 code-unit count): 65 536 CJK characters are ~192 KiB in
+    // UTF-8, and the terminal would still be spammed with a multi-MB
+    // escape run even though `text.length` looked in-budget. The base64
+    // step then doubles that again, so `Buffer.byteLength` is the right
+    // pre-encode gate.
+    if (Buffer.byteLength(text, 'utf8') <= OSC52_MAX_BYTES) {
+        const payload = Buffer.from(text, 'utf8').toString('base64');
+        try {
+            impl.write(`\x1b]52;c;${payload}\x07`);
+            osc52Ok = true;
+        }
+        catch { /* terminal may have closed — give up on this path */ }
+    }
+    const ladder = writeCommandsForPlatform(impl.env);
+    const localOk = await runWriteLadder(ladder, text, impl);
+    return osc52Ok || localOk;
+}
+/**
+ * Read the system clipboard and return its text. The payload is the raw
+ * stdout of whichever rung landed first — the ask-user side sanitizes
+ * it through `sanitizePastedText` before the editor buffer sees it, so
+ * a future caller of this helper gets a faithful copy of what the OS
+ * gave us. Returns `null` when no read path succeeds or the platform
+ * has been cached as "unavailable" (no command found on the ladder).
+ */
+export async function readClipboard(impl = defaultImpl) {
+    if (readUnavailable.has(impl.env.platform))
+        return null;
+    const ladder = readCommandsForPlatform(impl.env);
+    for (const { cmd, args } of ladder) {
+        try {
+            const { stdout } = await impl.execFile(cmd, args, {
+                timeout: 5000,
+                maxBuffer: 1 << 20,
+                windowsHide: true,
+            }, null);
+            return stdout;
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === 'ENOENT') {
+                // Binary missing on this ladder rung; try the next.
+                continue;
+            }
+            // Any other failure (nonzero exit, timeout, signal) — give up.
+            return null;
+        }
+    }
+    // The whole ladder was missing — cache the platform and bail.
+    readUnavailable.add(impl.env.platform);
+    return null;
+}
+/**
+ * Run the write ladder SERIALLY against the same text payload. Resolve
+ * `true` as soon as one rung exits cleanly; treat a missing binary
+ * (`ENOENT`) as "try the next rung" and any other failure as
+ * terminal. The serial order keeps Wayland and X11 from racing on the
+ * same `CLIPBOARD` selection, and avoids the wl-copy helper-process
+ * leak that parallel `Promise.all` caused.
+ */
+async function runWriteLadder(ladder, text, impl) {
+    for (const { cmd, args } of ladder) {
+        try {
+            await impl.execFile(cmd, args, {
+                timeout: 5000,
+                maxBuffer: 1 << 20,
+                windowsHide: true,
+            }, text);
+            return true;
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === 'ENOENT')
+                continue; // binary missing on this rung; try the next.
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * Test seam: drop the cached "platform has no read command" state. Tests
+ * inject a different `ClipboardImpl` per case, so the cache can be left
+ * full from a previous run; the seam keeps the test order independent.
+ */
+export function __resetClipboardUnavailableForTest() {
+    readUnavailable.clear();
+}
+//# sourceMappingURL=clipboard.js.map

package/lib/clipboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.js","sourceRoot":"","sources":["../src/clipboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,QAAQ,IAAI,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,sEAAsE;AACtE,MAAM,eAAe,GAAG,KAAK,CAAA;AAgC7B;;;;;GAKG;AACH,SAAS,mBAAmB;IAC1B,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,CAAC,IAAI,OAAO,CAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAChG,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;YACnE,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;;gBAClC,MAAM,CAAC,KAAK,CAAC,CAAA;QACpB,CAAC,CAAC,CAAA;QACF,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;YAC1B,kEAAkE;YAClE,qEAAqE;YACrE,iEAAiE;YACjE,gDAAgD;YAChD,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAqD,CAAC,CAAC,CAAA;YACrF,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,YAAY,CAAC,CAAA;QAChC,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,4CAA4C;AAC5C,MAAM,CAAC,MAAM,WAAW,GAAkB;IACxC,QAAQ,EAAE,mBAAmB,EAAE;IAC/B,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA,CAAC,CAAC;IAC/C,GAAG,EAAE;QACH,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe;QAC3C,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO;KAC7B;CACF,CAAA;AAED;;;;;GAKG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,EAAmB,CAAA;AAElD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAiB;IACxD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAA;IACtC,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC7B,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAA;IACpC,CAAC;IACD,wEAAwE;IACxE,uEAAuE;IACvE,qEAAqE;IACrE,oEAAoE;IACpE,iEAAiE;IACjE,IAAI,GAAG,CAAC,cAAc,KAAK,SAAS,IAAI,GAAG,CAAC,cAAc,KAAK,EAAE,EAAE,CAAC;QAClE,OAAO,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAA;IACvC,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,GAAG,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;QACpD,OAAO;YACL,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,YAAY,EAAE,WAAW,CAAC,EAAE;YACnD,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,aAAa,EAAE,SAAS,CAAC,EAAE;SAClD,CAAA;IACH,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,uBAAuB,CAAC,GAAiB;IACvD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAA;IACvC,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC7B,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC,YAAY,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE,CAAC,CAAA;IACvF,CAAC;IACD,MAAM,MAAM,GAA+C,EAAE,CAAA;IAC7D,IAAI,GAAG,CAAC,cAAc,KAAK,SAAS,IAAI,GAAG,CAAC,cAAc,KAAK,EAAE,EAAE,CAAC;QAClE,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,cAAc,CAAC,EAAE,CAAC,CAAA;IAC1D,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,GAAG,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;QACpD,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,WAAW,CAAC,EAAE,CAAC,CAAA;IACxE,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,aAAa,EAAE,UAAU,CAAC,EAAE,CAAC,CAAA;IAC/D,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY,EAAE,OAAsB,WAAW;IAClF,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,qEAAqE;IACrE,mEAAmE;IACnE,iEAAiE;IACjE,oEAAoE;IACpE,oEAAoE;IACpE,mBAAmB;IACnB,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,eAAe,EAAE,CAAC;QACvD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;QAC5D,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,aAAa,OAAO,MAAM,CAAC,CAAA;YACtC,OAAO,GAAG,IAAI,CAAA;QAChB,CAAC;QAAC,MAAM,CAAC,CAAC,qDAAqD,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,MAAM,GAAG,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACjD,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;IACxD,OAAO,OAAO,IAAI,OAAO,CAAA;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAsB,WAAW;IACnE,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAA;IACvD,MAAM,MAAM,GAAG,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAChD,KAAK,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE;gBAChD,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,CAAC,IAAI,EAAE;gBAClB,WAAW,EAAE,IAAI;aAClB,EAAE,IAAI,CAAC,CAAA;YACR,OAAO,MAAM,CAAA;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,GAAI,KAAuC,EAAE,IAAI,CAAA;YAC3D,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACtB,oDAAoD;gBACpD,SAAQ;YACV,CAAC;YACD,+DAA+D;YAC/D,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IACD,8DAA8D;IAC9D,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IACtC,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,cAAc,CAC3B,MAA2D,EAC3D,IAAY,EACZ,IAAmB;IAEnB,KAAK,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE;gBAC7B,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,CAAC,IAAI,EAAE;gBAClB,WAAW,EAAE,IAAI;aAClB,EAAE,IAAI,CAAC,CAAA;YACR,OAAO,IAAI,CAAA;QACb,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,GAAI,KAAuC,EAAE,IAAI,CAAA;YAC3D,IAAI,IAAI,KAAK,QAAQ;gBAAE,SAAQ,CAAC,6CAA6C;YAC7E,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kCAAkC;IAChD,eAAe,CAAC,KAAK,EAAE,CAAA;AACzB,CAAC"}

package/lib/index.js

@@ -35,7 +35,11 @@ import { reloadPlugin } from "./reload.js";
 import { runSessionRetentionOnce } from "./retention.js";
 import { setNoticeSink } from "./notice-bridge.js";
 import { collectStartupSummary, formatResumeCommand, parseResumeArg, resolveProfileName, } from "./startup-info.js";
-import { inspectPersistedSession, pickPersistedSession, showSessionInfo } from "./sessions.js";
+import { inspectPersistedSession, pickPersistedSession, sessionLogRoot, showSessionInfo } from "./sessions.js";
+import { isCorruptLogError, locateSessionLog, repairFailureNotice, repairSessionLog, } from "./log-repair.js";
+import { openRepairConfirmDialog } from "./repair-dialog.js";
+import { WriterLockedError } from "./writer-lock.js";
+import { emitNotice } from "./notice-bridge.js";
 import { applySubagentPolicy } from "./subagent-policy.js";
 import { openSubagentViewer } from "./subagent-viewer.js";
 import { commandUsagePath, CommandUsageTracker } from "./usage.js";
@@ -601,7 +605,26 @@ export function apply(ctx) {
                 liveWidgets.renderAgents(agents);
             },
         };
-        const bridge = new DshSessionBridge(ctx, bridgeCallbacks);
+        const bridgeCallbacksWithTakeover = {
+            ...bridgeCallbacks,
+            onRemotePromotable: async (idRaw) => {
+                // Queued follow-ups won the writer-lock race at an idle boundary:
+                // take over EXACTLY like a manual /resume, then flush the queue.
+                const resumed = await bridge.resume(SessionId(idRaw));
+                refreshPermissionPreset();
+                renderer.clear();
+                liveWidgets.clear();
+                const session = resumed.agent.session;
+                const adopted = 'adopted' in resumed && resumed.adopted === true;
+                bridge.replay(adopted ? session.events : session.events.filter(event => event.seq < session.firstLiveSeq));
+                for (const text of bridge.takePendingRemoteFollowups()) {
+                    await bridge.prompt(text);
+                }
+                emitNotice('Write lock acquired — follow-ups sent.');
+                ui.requestRender();
+            },
+        };
+        const bridge = new DshSessionBridge(ctx, bridgeCallbacksWithTakeover);
         bridgeRef = bridge;
         // Subagent fine-grained control, all in-process (see subagent-policy.ts):
         // a tools.guard denies spawn-tool calls once `maxAgents` children run
@@ -963,6 +986,112 @@ export function apply(ctx) {
             }
             if (picked.kind === 'cancelled')
                 return { kind: 'success', text: 'Resume cancelled.' };
+            // Narrowed shared handle for the closures below (const narrowing
+            // propagates into async closures; `picked`'s does not).
+            const target = picked;
+            // The selected row's resume path: swap the live agent for the target
+            // and rebuild transcript + stats from the stored events. Shared by the
+            // direct hit and the post-repair re-entry so both behave identically
+            // (including the WriterLockedError read-only fallback).
+            const resumeAndReplay = async () => {
+                let resumed;
+                try {
+                    resumed = await bridge.resume(target.id);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (error instanceof WriterLockedError) {
+                        // Single-writer guard fired: another process drives this session.
+                        // Rather than a dead end, degrade to a READ-ONLY view synced from
+                        // its persisted log — final replies arrive (poll-delayed, without
+                        // streaming detail); input is refused until /resume or /new.
+                        try {
+                            await bridge.watchRemote(target.id);
+                            refreshPermissionPreset();
+                            renderer.clear();
+                            liveWidgets.clear();
+                            ui.requestRender();
+                            return {
+                                kind: 'success',
+                                text: `Watching ${clipToWidth(String(target.id), 8)} (read-only · driven by pid ${error.holder.pid}). /resume or /new to switch.`,
+                            };
+                        }
+                        catch (watchError) {
+                            return {
+                                kind: 'error',
+                                text: `Cannot watch ${clipToWidth(String(target.id), 8)} read-only: ${watchError instanceof Error ? watchError.message : String(watchError)}`,
+                            };
+                        }
+                    }
+                    return {
+                        kind: 'error',
+                        text: `Resume failed: ${message} — the previous session was closed; the next prompt starts a new one.`,
+                    };
+                }
+                // Seed the badge cache for the resumed session (its pin event may have
+                // been emitted before the bridge's session-id filter re-bound).
+                refreshPermissionPreset();
+                // Clear BEFORE replay: the renderer's local-echo dedupe must not see
+                // replayed user messages next to a stale prompt echo. The live widget
+                // drops the previous session's todos too (its agents already went via
+                // the bridge's onLive([]) on resume reset).
+                renderer.clear();
+                liveWidgets.clear();
+                // Replay seed history only: events at or above firstLiveSeq were
+                // published in-process and arrive again through the session/event
+                // subscription (replaying them would double-count stats and echo).
+                // Seeds entered through construction never published — replaying them
+                // exactly once covers the stored log with zero overlap, zero gap.
+                const session = resumed.agent.session;
+                // Adopted live sessions (attach arm): EVERY event in the log was
+                // published before this surface started tracking it — the firehose
+                // dropped all of them, so replay unfiltered or the transcript misses
+                // everything the other surface did. Cold resumes keep the firstLiveSeq
+                // filter (seeded history replays once; live events re-arrive).
+                const adopted = 'adopted' in resumed && resumed.adopted === true;
+                bridge.replay(adopted ? session.events : session.events.filter(event => event.seq < session.firstLiveSeq));
+                ui.requestRender();
+                return {
+                    kind: 'success',
+                    text: `Resumed ${clipToWidth(String(target.id), 8)} · ${session.events.length} events.`,
+                };
+            };
+            // Corrupt-log branch: the repair rewrites user data on disk, so it is
+            // gated behind an explicit confirmation dialog — it never runs
+            // silently, and Cancel falls back to the plain failure text.
+            const offerCorruptedLogRepair = async (message) => {
+                // Locate BEFORE asking (feishu-surface order): a log that cannot be
+                // grounded on disk gives the dialog nothing to confirm.
+                const persistence = ctx.get('sessionPersistence');
+                const logPath = await locateSessionLog(persistence, String(target.id), sessionLogRoot());
+                if (logPath === undefined) {
+                    return {
+                        kind: 'error',
+                        text: `repair failed: cannot locate the log of ${clipToWidth(String(target.id), 8)} on disk — log untouched`,
+                    };
+                }
+                if (await openRepairConfirmDialog(ui.tui, ui.theme, refocusEditor) !== 'repair') {
+                    return {
+                        kind: 'error',
+                        text: `Cannot resume ${clipToWidth(String(target.id), 8)}: ${message}`,
+                    };
+                }
+                // repairSessionLog maps its own failures to results; the catch is a
+                // defensive floor so the dispatch never sees an exception.
+                let notice;
+                try {
+                    notice = repairFailureNotice(await repairSessionLog(logPath));
+                }
+                catch (error) {
+                    const detail = error instanceof Error ? error.message : String(error);
+                    notice = `repair failed: ${detail} — log untouched`;
+                }
+                if (notice !== undefined)
+                    return { kind: 'error', text: notice };
+                // A verified-clean log now sits under the canonical name — re-enter
+                // the selected row's resume path.
+                return resumeAndReplay();
+            };
             // Validate the target log before tearing down the current agent: a
             // corrupt log must leave the live session untouched.
             try {
@@ -970,46 +1099,12 @@ export function apply(ctx) {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
+                if (isCorruptLogError(message)) {
+                    return offerCorruptedLogRepair(message);
+                }
                 return { kind: 'error', text: `Cannot resume ${clipToWidth(String(picked.id), 8)}: ${message}` };
             }
-            let resumed;
-            try {
-                resumed = await bridge.resume(picked.id);
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                return {
-                    kind: 'error',
-                    text: `Resume failed: ${message} — the previous session was closed; the next prompt starts a new one.`,
-                };
-            }
-            // Seed the badge cache for the resumed session (its pin event may have
-            // been emitted before the bridge's session-id filter re-bound).
-            refreshPermissionPreset();
-            // Clear BEFORE replay: the renderer's local-echo dedupe must not see
-            // replayed user messages next to a stale prompt echo. The live widget
-            // drops the previous session's todos too (its agents already went via
-            // the bridge's onLive([]) on resume reset).
-            renderer.clear();
-            liveWidgets.clear();
-            // Replay seed history only: events at or above firstLiveSeq were
-            // published in-process and arrive again through the session/event
-            // subscription (replaying them would double-count stats and echo).
-            // Seeds entered through construction never published — replaying them
-            // exactly once covers the stored log with zero overlap, zero gap.
-            const session = resumed.agent.session;
-            // Adopted live sessions (attach arm): EVERY event in the log was
-            // published before this surface started tracking it — the firehose
-            // dropped all of them, so replay unfiltered or the transcript misses
-            // everything the other surface did. Cold resumes keep the firstLiveSeq
-            // filter (seeded history replays once; live events re-arrive).
-            const adopted = 'adopted' in resumed && resumed.adopted === true;
-            bridge.replay(adopted ? session.events : session.events.filter(event => event.seq < session.firstLiveSeq));
-            ui.requestRender();
-            return {
-                kind: 'success',
-                text: `Resumed ${clipToWidth(String(picked.id), 8)} · ${session.events.length} events.`,
-            };
+            return resumeAndReplay();
         };
         commands.registerLocal('resume', resumeHandler);
         ctx.effect(() => ctx.commands.register({
@@ -1527,7 +1622,7 @@ export function apply(ctx) {
             // runs, the dialog decides steer vs follow-up — Esc cancels and the
             // draft goes back into the editor untouched. Idle → direct send (the
             // two primitives are equivalent there: both wake a fresh turn).
-            if (decideSubmitPath(bridge.isRunning()) === 'dialog') {
+            if (decideSubmitPath(bridge.isRunning() && !bridge.isReadOnlyView()) === 'dialog') {
                 const route = await openSubmitRouteDialog(ui.tui, ui.theme, text, refocusEditor);
                 if (route === undefined) {
                     // Review S1: restore the RAW submitted text — restoring the trimmed
@@ -1546,8 +1641,11 @@ export function apply(ctx) {
             // editor for text that never ran.
             liveWidgets.setLastRequest(line);
             renderer.renderPromptEcho(line);
+            const wasWatching = bridge.isReadOnlyView();
             try {
                 await bridge.prompt(line);
+                if (wasWatching)
+                    emitNotice('Queued follow-up — sends automatically once the write lock frees up.');
             }
             catch (error) {
                 // Buffered notice: the failure line is the only on-screen record and