dsh-ssh-tui 0.8.3 → 0.8.4-rc.2

package/lib/input-reader.js

@@ -0,0 +1,415 @@
+/**
+ * The input Reader: bytes in, framed input units out.
+ *
+ * This module owns everything between the wire and "here is what arrived":
+ *
+ *   - **byte decoding** — a UTF-8 code point split across two reads is one
+ *     character, not two replacement glyphs (`StringDecoder`)
+ *   - **device-reply filtering** — the `CSI row;col R` answers the link probe asks
+ *     for are not typing; the guard strips them and holds a possible tail for
+ *     `INPUT_HOLD_MS` so `ESC [ 1` + `7;1R` cannot become `[17;1R` in the draft
+ *   - **escape assembly** — a sequence may arrive in pieces (`ESC`, then `[A`;
+ *     `ESC[`, then `5~`), so a read that could still grow is held for
+ *     {@link ESCAPE_HOLD_MS} and released as what it turned out to be
+ *   - **paste framing** — `ESC[200~ … ESC[201~` markers, the payload between them,
+ *     and the console-without-bracketed-paste fallback (a burst carrying more than
+ *     one line break in one read is a paste, not repeated Enter presses)
+ *   - **unit classification** — whether a read is one complete terminal unit, a
+ *     burst of typing, paste traffic, or a device reply (shape only: this module
+ *     does not know which key does what)
+ *
+ * It owns **no** semantics. It does not look at `screen`, `dialog`, the composer or
+ * the workspace, does not consult the keymap, and never mutates owner state: the
+ * frames it emits are the input to the caller's routing, not a decision about it.
+ * That is the boundary the contract freezes (`docs/decisions/input-reader.md`,
+ * AD-21) — the same input bytes must produce the same frames, and the caller must
+ * be able to prove it (`tests/input-reader.test.mjs` compares the frames and the
+ * consumer calls against traces captured before this module existed).
+ *
+ * The two hold windows are deliberately separate and must not be merged:
+ * `INPUT_HOLD_MS` (30 ms, in the guard) guards a **reply** and hands the bytes back
+ * as input when the window passes; {@link ESCAPE_HOLD_MS} (60 ms, here) guards a
+ * **keystroke** and turns what it held into an Escape or into text. One is a filter
+ * with a fallback, the other an assembly step with two possible readings.
+ *
+ * @module dsh-ssh-tui/input-reader
+ */
+import { StringDecoder } from 'node:string_decoder';
+import { isEscapePrefix, parseCursorPositionReply } from './paint.js';
+import { TerminalInputGuard } from './terminal-input.js';
+/**
+ * How long a read that could still grow into a sequence is held.
+ *
+ * The window is what makes a lone `ESC` (the reader pressed Escape) different from
+ * the first byte of a sequence the terminal is still sending. W-1 moved the timer,
+ * not the number: changing it changes how Escape feels, and that is a separate
+ * decision with its own evidence.
+ */
+export const ESCAPE_HOLD_MS = 60;
+/** Whether `text` is exactly one complete terminal unit (shape, not meaning). */
+const COMPLETE_CSI = /^\x1b\[[0-9;?<]*[ -/]*[@-~]$/u;
+const COMPLETE_SS3 = /^\x1bO[@-~]$/u;
+/** The same shapes, anchored at the start: one complete unit of a longer read. */
+const COMPLETE_CSI_AT = /^\x1b\[[0-9;?<]*[ -/]*[@-~]/u;
+const COMPLETE_SS3_AT = /^\x1bO[@-~]/u;
+/**
+ * `ESC` plus one printable character: the Alt chord.
+ *
+ * Not `[ -~]` alone: a terminal can send Alt with any character it can encode, and the
+ * chord has to reach the Alt branch in one piece or its character leaks as text.
+ */
+const ALT_CHORD_AT = /^\x1b(?!\[|O)[^\x00-\x1f\x7f]/u;
+const PASTE_MARKERS = ['\x1b[200~', '\x1b[201~'];
+/**
+ * How long a paste may sit with half a marker before the reader gives up on it.
+ *
+ * This is a watchdog, not a key hold: a paste is a stream, and its close marker may
+ * arrive in a second chunk after a slow terminal, a ConPTY or a loaded runner — on
+ * Windows CI the gap was over 200 ms, and expiring that early typed the marker's tail
+ * into the draft and left the session inside the paste. So the window is generous.
+ * When it does expire the reader does not just release the tail as payload, it
+ * **leaves the paste**: a paste that never closed must not keep the keyboard as its
+ * payload for the rest of the session.
+ */
+export const PASTE_MARKER_HOLD_MS = 2_000;
+/**
+ * The length of the longest suffix of `text` that is a *proper* prefix of a paste
+ * marker (0 when there is none) — what a read cut in half leaves behind.
+ */
+function pasteMarkerSuffix(text) {
+    const longest = Math.max(...PASTE_MARKERS.map(marker => marker.length)) - 1;
+    for (let length = Math.min(longest, text.length); length > 0; length -= 1) {
+        const suffix = text.slice(text.length - length);
+        if (PASTE_MARKERS.some(marker => marker.startsWith(suffix)))
+            return length;
+    }
+    return 0;
+}
+export class InputReader {
+    options;
+    decoder = new StringDecoder('utf8');
+    guard;
+    /** A read that may still grow (escape assembly). */
+    held = '';
+    holdTimer;
+    /** Inside `ESC[200~ … ESC[201~`. */
+    inPaste = false;
+    /**
+     * The tail of a read that ended *inside* a paste marker (`…ESC[20`), waiting for
+     * its other half.
+     */
+    pasteTail = '';
+    pasteTailTimer;
+    constructor(options) {
+        this.options = options;
+        this.guard = new TerminalInputGuard(text => this.options.onRead(text), undefined, 
+        // The filter must not mistake a paste's close marker for half a cursor reply.
+        { isPasteTraffic: text => this.isPasteTraffic(text) });
+    }
+    /** One read of bytes: decode it, drop device replies, hand the rest on. */
+    push(chunk) {
+        const decoded = this.decoder.write(chunk);
+        if (decoded === '')
+            return;
+        this.guard.push(decoded);
+    }
+    /** The read with any held prefix in front of it. The hold window is over. */
+    assemble(text) {
+        const combined = this.held + text;
+        this.held = '';
+        this.cancelHold();
+        return combined;
+    }
+    /**
+     * The frames of one read, whichever kind it is.
+     *
+     * A read is what the terminal happened to send, not what the reader pressed: a
+     * fast typist, a slow link or ConPTY can put several keys in one read. This is the
+     * one place that decides where one unit ends and the next begins; everything above
+     * it (Router, owners) sees complete units only, and nothing above it re-parses the
+     * bytes (AD-20 §4.4, §6).
+     */
+    read(text) {
+        const combined = this.pasteTail === '' ? text : `${this.pasteTail}${text}`;
+        if (this.pasteTail !== '') {
+            this.pasteTail = '';
+            this.cancelPasteTail();
+        }
+        if (!this.isPasteTraffic(combined))
+            return this.units(combined);
+        const { frames, tail } = this.framePaste(combined);
+        this.pasteTail = tail;
+        // Armed for the whole paste, not just for a held tail: a terminal can swallow the
+        // close marker outright (ConPTY drops a partial CSI), and a paste that never says
+        // it ended must not keep the keyboard as its payload.
+        if (this.inPaste || tail !== '')
+            this.armPasteTail();
+        else
+            this.cancelPasteTail();
+        return frames;
+    }
+    /**
+     * Frame one paste read, holding back a marker it cut in half.
+     *
+     * A terminal writes bytes, not reads: `ESC[201~` can arrive as `…ESC[20` and `1~`.
+     * Framed naively, the first read swallows `ESC[20` as payload and the second one
+     * carries no marker at all — so `inPaste` never clears and **every later key is
+     * pasted text**: Esc stops closing a dialog, `/exit` stops exiting. Found by
+     * `scripts/tui-paste-probe.mjs` on CI, where the pty chunked the write exactly
+     * there. The fix is the same rule the escape ladder already uses — a read that
+     * could still grow is held, and released as payload if its other half never comes.
+     */
+    framePaste(combined) {
+        const keep = pasteMarkerSuffix(combined);
+        if (keep === 0)
+            return { frames: this.frames(combined), tail: '' };
+        const body = combined.slice(0, combined.length - keep);
+        return { frames: this.frames(body), tail: combined.slice(combined.length - keep) };
+    }
+    armPasteTail() {
+        this.cancelPasteTail();
+        this.pasteTailTimer = setTimeout(() => {
+            this.pasteTailTimer = undefined;
+            const pending = this.pasteTail;
+            this.pasteTail = '';
+            // Its other half never came. Those bytes are what the reader pasted, and the
+            // paste they belonged to is over: leaving `inPaste` set here is what turned a
+            // slow (or swallowed) marker into a session that ignored every key.
+            if (pending !== '')
+                this.options.onFrame({ kind: this.inPaste ? 'paste' : 'literal', text: pending });
+            this.inPaste = false;
+        }, this.options.pasteMarkerHoldMs ?? PASTE_MARKER_HOLD_MS);
+    }
+    cancelPasteTail() {
+        if (this.pasteTailTimer !== undefined)
+            clearTimeout(this.pasteTailTimer);
+        this.pasteTailTimer = undefined;
+    }
+    /**
+     * One non-paste read, split into complete units.
+     *
+     * The rules, and why each one exists:
+     *
+     *   - **A complete CSI/SS3 sequence is one unit.** `ESC [ 5 ~ ESC [ 5 ~` is two page
+     *     keys, not one unnameable read (G-1). A sequence the read cuts short stays one
+     *     piece: `hold()` has already claimed it if it could still grow, and a trailing
+     *     `ESC [` must reach the hold again rather than be split into `ESC` + `[`.
+     *   - **An Alt chord is one unit.** `ESC` plus exactly one printable character is
+     *     Alt+that key, so `ESC 1 x` is the chord Alt+1 *and then* `x` — never the text
+     *     `1x` (G-3), and never a chord that swallows the character behind it.
+     *   - **A control byte is one unit, CR/LF pair as one Enter.** `\x10\x10` is two
+     *     presses of a rebound key (G-2/G-8), and Windows' CRLF is one key.
+     *   - **A run of ordinary characters is one unit.** Splitting typing per character
+     *     would make a pasted `yes` answer a confirm dialog character by character,
+     *     which is the boundary W-0 pinned (`yes-typed-at-dialog`). Keymap lookup on a
+     *     whole run is still exactly what a run means: text.
+     *   - **A burst the paste heuristic claims stays whole.** A console without
+     *     bracketed paste sends a paste as ordinary bytes with line breaks in them;
+     *     that read has to reach the paste path intact (`looksLikePasteBurst`).
+     */
+    units(text) {
+        if (InputReader.looksLikePasteBurst(text))
+            return [{ kind: 'burst', text }];
+        const frames = [];
+        let index = 0;
+        while (index < text.length) {
+            const char = text[index];
+            if (char === '\x1b') {
+                const rest = text.slice(index);
+                const sequence = COMPLETE_CSI_AT.exec(rest)?.[0] ?? COMPLETE_SS3_AT.exec(rest)?.[0];
+                if (sequence !== undefined) {
+                    frames.push({ kind: 'key', sequence });
+                    index += sequence.length;
+                    continue;
+                }
+                // Something that could still grow into a sequence — `ESC [ 5` with its final
+                // byte in the next read, a mouse report cut in half — goes on as one piece, so
+                // the hold below claims exactly what it claimed before: splitting it here would
+                // turn the head of a sequence into an Alt chord and type its tail as text.
+                if (isEscapePrefix(rest)) {
+                    frames.push({ kind: 'key', sequence: rest });
+                    index += rest.length;
+                    continue;
+                }
+                const chord = ALT_CHORD_AT.exec(rest)?.[0];
+                if (chord !== undefined) {
+                    frames.push({ kind: 'key', sequence: chord });
+                    index += chord.length;
+                    continue;
+                }
+                // A lone ESC, or something that cannot grow: its own unit, and the hold decides.
+                frames.push({ kind: 'key', sequence: '\x1b' });
+                index += 1;
+                continue;
+            }
+            if (char === '\r' || char === '\n') {
+                const next = text[index + 1];
+                frames.push({ kind: 'key', sequence: char === '\n' ? '\n' : '\r' });
+                index += (char === '\r' && next === '\n') || (char === '\n' && next === '\r') ? 2 : 1;
+                continue;
+            }
+            if (char < ' ' || char === '\x7f') {
+                frames.push({ kind: 'key', sequence: char });
+                index += 1;
+                continue;
+            }
+            let end = index;
+            while (end < text.length && text[end] >= ' ' && text[end] !== '\x7f' && text[end] !== '\x1b')
+                end += 1;
+            frames.push({ kind: 'burst', text: text.slice(index, end) });
+            index = end;
+        }
+        return frames;
+    }
+    /**
+     * Whether a read is paste traffic: inside a paste, or carrying a marker.
+     *
+     * Asked before anything else, exactly as the inline check it replaces was: while
+     * inside a paste, CR/LF are literal characters rather than submit.
+     */
+    isPasteTraffic(combined) {
+        return this.inPaste || combined.includes('\x1b[200~') || combined.includes('\x1b[201~');
+    }
+    /**
+     * The frames of one paste read, in order: payload inside the markers as `paste`,
+     * everything outside them as `literal` (which is what the inline version typed
+     * directly, without a keymap lookup).
+     *
+     * Only complete markers are handled here: `framePaste` holds back a read that ends
+     * inside one, because a marker whose two halves land in two reads would otherwise
+     * leave the reader inside the paste for the rest of the session.
+     */
+    frames(combined) {
+        const frames = [];
+        let index = 0;
+        while (index < combined.length) {
+            if (combined.startsWith('\x1b[200~', index)) {
+                this.inPaste = true;
+                index += 6;
+                continue;
+            }
+            if (combined.startsWith('\x1b[201~', index)) {
+                this.inPaste = false;
+                index += 6;
+                continue;
+            }
+            let end = index;
+            while (end < combined.length
+                && !combined.startsWith('\x1b[200~', end)
+                && !combined.startsWith('\x1b[201~', end)) {
+                end += 1;
+            }
+            if (end > index) {
+                const part = combined.slice(index, end);
+                frames.push(this.inPaste ? { kind: 'paste', text: part } : { kind: 'literal', text: part });
+                index = end;
+            }
+            else {
+                index += 1;
+            }
+        }
+        return frames;
+    }
+    /**
+     * Keep a read that could still grow into a sequence.
+     * @returns true when it was held (the caller stops there), false when the read is
+     *   complete as it stands.
+     */
+    hold(combined) {
+        if (!isEscapePrefix(combined))
+            return false;
+        this.held = combined;
+        this.cancelHold();
+        this.holdTimer = setTimeout(() => {
+            this.holdTimer = undefined;
+            const pending = this.held;
+            this.held = '';
+            this.releaseHold(pending);
+        }, ESCAPE_HOLD_MS);
+        return true;
+    }
+    /**
+     * Whether one read is a paste from a console that cannot say so.
+     *
+     * A burst carrying more than one line break is not a human pressing Enter twice —
+     * they cannot press it twice inside one read. This is the fallback's one rule, and
+     * it lives here so every caller applies the same one.
+     */
+    static looksLikePasteBurst(text) {
+        let breaks = 0;
+        for (let index = 0; index < text.length; index += 1) {
+            const char = text[index];
+            if (char === '\r' && text[index + 1] !== '\n')
+                breaks += 1;
+            else if (char === '\n' && text[index - 1] !== '\r')
+                breaks += 1;
+            if (breaks > 1)
+                return true;
+        }
+        return false;
+    }
+    /** Whether a complete read is a device reply rather than input. */
+    isDeviceReply(text) {
+        return parseCursorPositionReply(text) !== undefined;
+    }
+    /** Classify one complete read by shape. */
+    classify(text) {
+        if (this.isDeviceReply(text))
+            return { kind: 'reply', sequence: text };
+        if (text === '\x1b')
+            return { kind: 'key', sequence: text };
+        if (text.length === 1) {
+            const code = text.codePointAt(0) ?? 0;
+            return code < 0x20 || code === 0x7f ? { kind: 'key', sequence: text } : { kind: 'burst', text };
+        }
+        if (COMPLETE_CSI.test(text) || COMPLETE_SS3.test(text))
+            return { kind: 'key', sequence: text };
+        return { kind: 'burst', text };
+    }
+    /**
+     * Hand over a held reply tail now.
+     *
+     * The guard releases on its own window; this is for a caller that already knows
+     * the tail is stale — `scripts/bench-b2.mjs` drives keystrokes faster than the
+     * hold, and a measurement that waited for the window would be measuring the wait.
+     */
+    releaseReplyTail() {
+        this.guard.release();
+    }
+    /** Drop the holds and the reply filter (display detached, teardown). */
+    stop() {
+        this.cancelHold();
+        this.cancelPasteTail();
+        this.pasteTail = '';
+        this.guard.stop();
+    }
+    cancelHold() {
+        if (this.holdTimer !== undefined)
+            clearTimeout(this.holdTimer);
+        this.holdTimer = undefined;
+    }
+    /**
+     * What a held read turned out to be.
+     *
+     * Verbatim from the inline timer it replaces: a lone `ESC` is the Escape key, an
+     * `ESC O` without its final byte is Alt+O, an escape sequence that never completed
+     * is consumed silently (its `ESC` must not read as a cancel), and anything else is
+     * typed. The last branch is unreachable for the shapes `isEscapePrefix` accepts —
+     * it is kept because "unreachable today" is not a reason to change a release.
+     */
+    releaseHold(pending) {
+        if (pending === '\x1b') {
+            this.options.onFrame({ kind: 'escape' });
+            return;
+        }
+        if (pending === '\x1bO') {
+            this.options.onFrame({ kind: 'literal', text: 'O' });
+            return;
+        }
+        if (pending.startsWith('\x1b[') || pending.startsWith('\x1bO'))
+            return;
+        if (pending !== '')
+            this.options.onFrame({ kind: 'literal', text: pending });
+    }
+}
+//# sourceMappingURL=input-reader.js.map

package/lib/input-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-reader.js","sourceRoot":"","sources":["../src/input-reader.ts"],"names":[],"mappings":"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"}

package/lib/input-router.js

@@ -0,0 +1,82 @@
+/**
+ * The InputRouter: one unit in, exactly one owner out.
+ *
+ * W-1 taught the TUI *what arrived* (`InputFrame`). This module answers the other
+ * question — *who takes it* — and it is the only place that may. The four owners
+ * (Screen, Surface, Composer, Workspace) each have an adapter in `tui.ts`; an
+ * adapter may read its own state, but it may not decide cross-owner ownership
+ * again, and it may not hand a unit on to the next owner when it does not use it
+ * (AD-20 §4.3, §4.5 F-1/F-6).
+ *
+ * The decision is a pure function of `(unit kind, unit, ownership snapshot)`: no
+ * app state is read or written, nothing is painted, no transcript row is pushed,
+ * and the snapshot is a plain object the caller keeps and overwrites, so a
+ * keystroke costs no allocation (W-2 is a hot-path migration).
+ *
+ * The rules are the ones `tui.ts` already applied inline, moved here verbatim —
+ * including one asymmetry that is **recorded debt, not a decision**:
+ *
+ *   1. `Ctrl+L` is handled by the Screen when a Screen is up and by the Composer
+ *      otherwise; the repaint has two implementations and W-2 does not merge them
+ *      (AD-20 §6: only a test that proves both owners repaint identically may).
+ *      W-3b.2 owns that one.
+ *
+ * W-3b.1 closed the other asymmetry this module used to record:
+ * `SURFACE_COMPOSER_KEYS` sent `Home`/`End`/`Delete`/kitty-`Ctrl+Shift+C` to the
+ * composer while a Surface was up. The Surface owns them now, like every other unit,
+ * and its adapter decides what they mean — the field it borrowed, or nothing.
+ *
+ * @module dsh-ssh-tui/input-router
+ */
+const PAGE_UP = '\x1b[5~';
+const PAGE_DOWN = '\x1b[6~';
+const ARROW_UP = '\x1b[A';
+const ARROW_DOWN = '\x1b[B';
+const SGR_MOUSE = /^\x1b\[<\d+;\d+;\d+[Mm]$/u;
+export class InputRouter {
+    /** The one cross-owner decision. One unit in, one owner out. */
+    route(kind, unit, view) {
+        // A Screen replaces the workspace and owns the keyboard outright (AD-20 §4.3,
+        // priority 3). This single line is why no Screen event can reach the composer
+        // behind it: the owners below are never consulted.
+        if (view.screenKind !== undefined)
+            return 'screen';
+        // Paste is text: the field that owns the keyboard takes it. A Screen already
+        // terminated the paste above (it does not fall through to a field behind it), and
+        // a Surface without a field refuses it in its own adapter — the decision is still
+        // "the Surface", never the composer behind it (AD-20 §4.3, priority 1).
+        if (kind === 'paste')
+            return view.surfaceKind !== undefined ? 'surface' : 'composer';
+        // A Surface owns everything while it is up — including the composer's own editing
+        // sequences: `Home`/`End`/`Delete` and the kitty copy key are the Surface's units
+        // since W-3b.1, and its adapter edits the field it borrowed or drops them. The
+        // composer behind it is not the field on screen, so nothing here hands a unit to it
+        // by default.
+        if (view.surfaceKind !== undefined) {
+            if (kind === 'control' && unit === '\x0c')
+                return 'composer';
+            return 'surface';
+        }
+        return this.composerOrWorkspace(kind, unit, view);
+    }
+    /**
+     * With nothing layered over the workspace, the Composer owns text and its editing
+     * keys, and the Workspace owns the transcript: the mouse, the page keys, and the
+     * focus ring — which an arrow reaches only while the field is empty and there is a
+     * card to land on (otherwise the same arrow browses history, and history is the
+     * composer's).
+     */
+    composerOrWorkspace(kind, unit, view) {
+        if (kind !== 'sequence')
+            return 'composer';
+        if (SGR_MOUSE.test(unit))
+            return 'workspace';
+        if (unit === PAGE_UP || unit === PAGE_DOWN)
+            return 'workspace';
+        if (unit === ARROW_UP || unit === ARROW_DOWN) {
+            return view.composerEmpty && view.workspaceCards ? 'workspace' : 'composer';
+        }
+        return 'composer';
+    }
+}
+//# sourceMappingURL=input-router.js.map

package/lib/input-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-router.js","sourceRoot":"","sources":["../src/input-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAoCH,MAAM,OAAO,GAAG,SAAS,CAAA;AACzB,MAAM,SAAS,GAAG,SAAS,CAAA;AAC3B,MAAM,QAAQ,GAAG,QAAQ,CAAA;AACzB,MAAM,UAAU,GAAG,QAAQ,CAAA;AAC3B,MAAM,SAAS,GAAG,2BAA2B,CAAA;AAE7C,MAAM,OAAO,WAAW;IACtB,gEAAgE;IAChE,KAAK,CAAC,IAAc,EAAE,IAAY,EAAE,IAAuB;QACzD,8EAA8E;QAC9E,8EAA8E;QAC9E,mDAAmD;QACnD,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAA;QAClD,6EAA6E;QAC7E,kFAAkF;QAClF,kFAAkF;QAClF,wEAAwE;QACxE,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAA;QACpF,kFAAkF;QAClF,kFAAkF;QAClF,+EAA+E;QAC/E,oFAAoF;QACpF,cAAc;QACd,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACnC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM;gBAAE,OAAO,UAAU,CAAA;YAC5D,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,OAAO,IAAI,CAAC,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;IACnD,CAAC;IAED;;;;;;OAMG;IACK,mBAAmB,CAAC,IAAc,EAAE,IAAY,EAAE,IAAuB;QAC/E,IAAI,IAAI,KAAK,UAAU;YAAE,OAAO,UAAU,CAAA;QAC1C,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,WAAW,CAAA;QAC5C,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,WAAW,CAAA;QAC9D,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YAC7C,OAAO,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAA;QAC7E,CAAC;QACD,OAAO,UAAU,CAAA;IACnB,CAAC;CACF"}

package/lib/preset-rows.js

@@ -255,10 +255,16 @@ export function duplicatePatchRows(rows) {
     }
     return duplicates;
 }
-/** Whether a patch already declares one roster row, by id or by module name. */
+/**
+ * Whether a patch already addresses one roster row, by id or by module name.
+ *
+ * Every kind counts: an override or a disable targets the row just as an insert
+ * does. A repair must leave an intentional `- id: present` / `disabled: true`
+ * alone instead of mounting the same id a second time; the later entry would
+ * either collide with it or silently undo the user's choice.
+ */
 export function patchNamesRow(rows, row) {
-    return rows.some(candidate => (candidate.kind === 'insert' && candidate.id === row.id)
-        || candidate.name === row.name);
+    return rows.some(candidate => candidate.id === row.id || candidate.name === row.name);
 }
 /** The roster rows a patch does not declare yet. */
 export function missingRosterRows(rows, candidates = ROSTER_ROWS) {
@@ -287,12 +293,20 @@ function normalizeEnd(text) {
  * @param missing - the roster rows to mount; defaults to the 0.1.5 set.
  * @param generation - which host line the profile boots on.
  * @returns the new text, or `undefined` when nothing has to change.
+ * @throws when `existing` is not valid YAML; appending to a broken patch would
+ * make it longer without making it bootable.
  */
 export function planRosterRepair(existing, missing = ROSTER_ROWS, generation = 'legacy') {
     const analysis = analyzePatch(existing);
-    const toAdd = analysis.parseable
-        ? missing.filter(row => !patchNamesRow(analysis.rows, row))
-        : [...missing];
+    // A patch the loader cannot parse is the one case where appending a fresh
+    // block is not a repair: `/mode fix` and the first-run repair would turn a
+    // user's malformed override into a file that still cannot boot, while
+    // claiming they had been fixed. Leave it to `/doctor`, which reports the
+    // parser error, and refuse the write rather than making the file longer.
+    if (!analysis.parseable) {
+        throw new Error(`profile patch does not parse; refusing to add rows: ${analysis.error ?? 'unknown YAML error'}`);
+    }
+    const toAdd = missing.filter(row => !patchNamesRow(analysis.rows, row));
     if (toAdd.length === 0)
         return undefined;
     const entry = `${rosterPatchHeader(generation)}${rosterEntriesText(toAdd)}`;
@@ -394,41 +408,73 @@ export function planDuplicateRepair(existing) {
 /**
  * Mount the roster in one profile, unless it is already composed.
  *
- * Idempotent: a profile whose patch already names the roster row (one bundling
- * `@deepseek-ai/dsh-web-app`, for example) is left untouched. The write is a
- * plain whole-file replace because the file is small and read once at boot; a
+ * Idempotent: a profile whose patch already addresses the roster row (one
+ * bundling `@deepseek-ai/dsh-web-app`, for example) is left untouched. An
+ * existing file is backed up before the small whole-file replace; a
  * half-written patch would only be seen by the next launch.
  * @param home - the harness home carrying `profiles/`.
  * @param profile - the profile to patch.
  * @param missing - the rows to mount; defaults to the 0.1.5 set.
  * @param generation - which host line the profile boots on.
+ * @param stamp - filename-safe backups stamp, injectable for tests.
  * @returns `present` when the row already exists, else `written`.
+ * @throws when the existing patch cannot be read, is not valid YAML, or cannot
+ * be backed up; a file that cannot be preserved is not overwritten.
  */
-export async function ensureRosterRows(home, profile, missing = ROSTER_ROWS, generation = 'legacy') {
+export async function ensureRosterRows(home, profile, missing = ROSTER_ROWS, generation = 'legacy', stamp) {
     const path = rosterPatchPath(home, profile);
-    let existing = PATCH_TEMPLATE;
+    let existing;
     try {
         existing = await readFile(path, 'utf8');
     }
-    catch {
-        // Missing file: start from the template the launcher would have written.
+    catch (error) {
+        // Only a missing file means "start from the template". EACCES, EISDIR,
+        // EIO and every other read failure must abort the repair: treating them as
+        // absence would overwrite a profile the process could not read.
+        if (!isEnoent(error)) {
+            throw new Error(`cannot read profile patch ${path}; refusing to repair: ${errorMessage(error)}`, { cause: error });
+        }
     }
-    const repair = planRosterRepair(existing, missing, generation);
+    const repair = planRosterRepair(existing ?? PATCH_TEMPLATE, missing, generation);
     if (repair === undefined)
         return 'present';
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, repair.text, 'utf8');
+    if (existing === undefined) {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, repair.text, 'utf8');
+    }
+    else {
+        // The same rule `/doctor --fix` follows: a file the user owns is backed up
+        // before it is replaced, and a failed backup aborts the write.
+        await writePatchWithBackup(path, repair.text, stamp);
+    }
     return 'written';
 }
+/** A filesystem error's code, when it has one. */
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+/** A human-readable message for a caught filesystem error. */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Whether a read failure means the file is absent, and nothing else. */
+function isEnoent(error) {
+    return errorCode(error) === 'ENOENT';
+}
 /**
  * Write a repaired patch next to a copy of the previous content.
  *
- * `/doctor` changes a file the user owns, so the old text is kept beside it
- * before anything is replaced. A file that does not exist yet needs no backup.
+ * `/doctor` and the automatic repair change a file the user owns, so the old
+ * text is kept beside it before anything is replaced. A source that vanished
+ * between the read and the copy needs no backup; any other backup failure
+ * aborts before the write, leaving the original untouched.
  * @param path - the patch file to replace.
  * @param text - the new content.
  * @param stamp - filename-safe timestamp for the backup, injectable for tests.
  * @returns the backup path, or `undefined` when there was nothing to back up.
+ * @throws when the backup cannot be written; the destination is not touched.
  */
 export async function writePatchWithBackup(path, text, stamp = new Date().toISOString().replace(/[:.]/gu, '-')) {
     let backup;
@@ -436,7 +482,12 @@ export async function writePatchWithBackup(path, text, stamp = new Date().toISOS
         backup = `${path}.bak-${stamp}`;
         await copyFile(path, backup);
     }
-    catch {
+    catch (error) {
+        if (!isEnoent(error)) {
+            throw new Error(`cannot back up profile patch ${path}; refusing to write: ${errorMessage(error)}`, { cause: error });
+        }
+        // The source disappeared after the caller read it. There is no user content
+        // left to preserve, so the repair may create the file fresh.
         backup = undefined;
     }
     await mkdir(dirname(path), { recursive: true });