@cluesmith/codev 3.3.3 → 3.3.4

package/dist/terminal/session-screen.js

@@ -69,6 +69,10 @@ export class SessionScreen {
     // parses asynchronously and processes writes FIFO, so awaiting the LATEST write's
     // callback guarantees every earlier write is parsed too — the flush {@link read} needs.
     pending = Promise.resolve();
+    // Chunk counters backing {@link hasUnparsedOutput}: `feed` numbers each chunk, its parse
+    // callback records the number. Equal means the grid shows every byte fed so far.
+    fedSeq = 0;
+    parsedSeq = 0;
     disposed = false;
     constructor(cols, rows) {
         this._cols = cols;
@@ -90,7 +94,20 @@ export class SessionScreen {
     feed(data) {
         if (this.disposed)
             return;
-        this.pending = new Promise((resolve) => this.term.write(data, () => resolve()));
+        // Number every chunk and record the number its parse callback completes, so a synchronous
+        // caller can tell whether the grid is CURRENT (Issue #1664, CMAP round 2 — codex). xterm
+        // parses asynchronously and FIFO, so `parsedSeq !== fedSeq` means bytes have been fed that
+        // the grid does not show yet — and a composer redraw hiding in them is invisible to
+        // {@link peek}.
+        const seq = ++this.fedSeq;
+        this.pending = new Promise((resolve) => this.term.write(data, () => {
+            this.parsedSeq = seq;
+            resolve();
+        }));
+    }
+    /** Have bytes been fed that the grid has not parsed yet? See {@link feed} and {@link peek}. */
+    get hasUnparsedOutput() {
+        return this.parsedSeq !== this.fedSeq;
     }
     /**
      * Resize the mirror to match the live session (Spec 1313: the gate renders at the
@@ -110,11 +127,14 @@ export class SessionScreen {
      * `await this.pending` drains every byte fed up to this call into the grid, so the returned
      * buffer reflects AT LEAST the output counted by `ringBuffer.bytesWritten` at the moment the
      * caller sampled its change-token (xterm parses writes FIFO but may run ahead into later queued
-     * writes, so the buffer can reflect *more* — never less). That lower bound is the property the
-     * delivery path's token-before/after TOCTOU relies on: the caller MUST read the returned buffer
-     * with no intervening `await` (the classifier is synchronous), so no `feed` can interleave the
-     * read; any output that landed during THIS flush already advanced `bytesWritten`, so the caller's
-     * post-classify token re-check trips (→ hold) and nothing is delivered onto it.
+     * writes, so the buffer can reflect *more* — never less). The caller MUST read the returned
+     * buffer with no intervening `await` (the classifier is synchronous), so no `feed` can
+     * interleave the read.
+     *
+     * Issue #1664 retired the `bytesWritten` re-check this note used to point at — the delivery
+     * path no longer holds on whole-screen output, because a working agent always has some. What
+     * covers output landing after the flush is now {@link peek}, which refuses to answer at all
+     * while any fed byte is still unparsed.
      *
      * After {@link dispose} the term is freed and its parse callback may never fire, so this returns
      * the current view WITHOUT awaiting `pending` — a disposed screen has no coherent frame, the
@@ -127,6 +147,32 @@ export class SessionScreen {
         await this.pending;
         return { term: this.term, cols: this._cols, rows: this._rows };
     }
+    /**
+     * The live buffer WITHOUT flushing the parser (Issue #1664) — the synchronous counterpart of
+     * {@link read}, for a caller that cannot await.
+     *
+     * The delivery path's in-lock precheck runs inside the per-terminal submission lock,
+     * immediately before the first byte, and is synchronous by contract; it re-reads the composer
+     * region there to confirm the screen it measured is still the screen it is about to write
+     * onto. Awaiting a parse callback in that position is not available to it.
+     *
+     * `null` when the grid is not CURRENT — any byte fed but not yet parsed, or a disposed mirror
+     * (CMAP round 2 — codex). Without that, this would hand back a grid missing exactly the
+     * composer redraw the caller is checking for: output arriving after the stable sample and
+     * immediately before the in-lock precheck is queued for parsing, absent from the buffer, and
+     * the fingerprint would compare EQUAL and permit the write — the corruption race #1521 is
+     * about, which the retired `bytesWritten` comparison used to catch. Refusing to answer is the
+     * fail-safe direction: every caller treats `null` as "the composer moved" and holds, and the
+     * hold is self-clearing on the next pass a parse-turn later.
+     *
+     * This is why `peek()` is not simply "read without awaiting": a synchronous caller cannot
+     * flush, so the only honest answers are a coherent frame or none.
+     */
+    peek() {
+        if (this.disposed || this.hasUnparsedOutput)
+            return null;
+        return { term: this.term, cols: this._cols, rows: this._rows };
+    }
     /**
      * Serialize the current screen state (both buffers, colors/attrs, cursor, alt-screen
      * mode, plus up to {@link SCREEN_SCROLLBACK} lines of history) back into a terminal

package/dist/terminal/session-screen.js.map

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

package/dist/terminal/terminal-replies.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Terminal REPLY stripping for the delivery gate's input signal (Issue #1473).
+ *
+ * The render gate needs to know when a HUMAN has put something on a session's line, so a
+ * gated delivery never lands on a composer somebody has started typing into. The only
+ * server-side observation point is {@link PtySession.write}'s external branch — every live
+ * client (the web terminal, the VS Code webview, mobile, the raw
+ * `POST /api/terminals/:id/write` route) funnels through it.
+ *
+ * But that stream is not keystrokes. xterm forwards terminal REPLIES — DA, DSR, CPR,
+ * XTWINOPS, DECRPM, DECRQSS, OSC colour queries, focus reports — through the very same
+ * `onData` event as typed characters, because from the client's point of view they are all
+ * "bytes to send upstream". The web client strips a few of them, but ONLY while
+ * `rc.initialPhase` is true (`Terminal.tsx`) — for a session's entire steady-state life that
+ * filter is off, and the VS Code webview and mobile clients never had one at all. (`afx
+ * attach` is not in scope either way: it writes the shellper socket directly, so neither its
+ * keystrokes nor its replies ever pass through `PtySession.write()` — see arch.md §5.)
+ * Counting a reply as human input would produce a hold with nobody at the keyboard, and
+ * worse, a SELF-TRIP: our own delivery write repaints the TUI, the TUI queries geometry, the
+ * browser answers, and the answer reads as a keystroke that blocks the next delivery. So the
+ * filter is a precondition of the whole design, and it lives here — server-side, where every
+ * client is covered, rather than in one cooperative client.
+ *
+ * SIGNAL-ONLY. Nothing here changes what reaches the PTY: the caller still writes the full
+ * chunk verbatim, because the application ASKED for the reply and blocks waiting on it.
+ * Swallowing a DA reply would hang every attached terminal.
+ *
+ * ## Failure directions
+ *
+ * - **Over-strip** (a real keystroke eaten from the signal) → that keystroke goes uncounted,
+ *   which is exactly today's behaviour, so never a regression — but it silently re-opens the
+ *   race this issue exists to close, which is why the survival tests below are the strict half.
+ * - **Under-strip** (a reply counted as input) → a spurious `busy:recent-input` hold that
+ *   clears on the next settle. Fail-safe, and now visible rather than silent.
+ *
+ * The filter is **chunk-local**: it sees exactly the string one `write()` was handed, so a
+ * reply that arrives split across two calls (a short socket read, a coalescing client) matches
+ * no pattern in either half and is under-stripped. That is the fail-safe direction — a hold
+ * that clears itself a settle later — and it is why no pattern here is written to span calls:
+ * buffering across chunks to catch it would put a real keystroke's arrival at the mercy of the
+ * NEXT chunk, which is the over-strip direction, and that one is silent.
+ *
+ * ## The table is derived from a PINNED dependency
+ *
+ * Every pattern below was read out of `@xterm/xterm@{@link XTERM_REPLY_TABLE_VERSION}`'s
+ * bundle — each `triggerDataEvent` call site that emits a reply rather than a keystroke. A
+ * version bump is therefore a REVIEW TRIGGER for this file: a newly-answered query (kitty
+ * keyboard, XTVERSION) becomes an uncounted-reply hold until its shape is added here. Two
+ * patterns below are pre-emptive for that reason and match nothing stock xterm 5.5 emits.
+ *
+ * ## Case sensitivity is load-bearing
+ *
+ * `ESC[C` is Right-arrow and `ESC[1;5C` is Ctrl-Right. The CSI family pattern keys on a
+ * LOWERCASE final byte set (`c`/`n`/`t`/`y`); an `i` flag on it would strip every arrow key,
+ * Home/End and shift-Tab out of the signal. No pattern here carries `i`, and
+ * `terminal-replies.test.ts` pins the survival of those exact sequences.
+ */
+/**
+ * The `@xterm/xterm` version whose emission sites this table was enumerated from. Bumping the
+ * dependency past it means re-reading its `triggerDataEvent` call sites; a test asserts this
+ * constant against the installed package's version so the bump cannot pass silently.
+ */
+export declare const XTERM_REPLY_TABLE_VERSION = "5.5.0";
+/**
+ * Every recognized terminal reply in `data`, in the order the patterns match them.
+ *
+ * Diagnostics only — {@link stripTerminalReplies} does the real work and never calls this. It
+ * backs the `AF_LOG_INPUT_SIGNAL` trace, whose whole purpose is to let a human SEE which bytes
+ * were treated as a reply and which survived as input, rather than infer it from a hold that
+ * did or did not happen.
+ */
+export declare function terminalReplyMatches(data: string): string[];
+/**
+ * Render a byte run so it can be read in a log line: ESC as `\e`, other C0 controls and DEL as
+ * `\xNN`, everything else literal.
+ *
+ * Printing raw ESC to a terminal log would make the log itself move the cursor and repaint —
+ * the diagnostic would corrupt the thing it is diagnosing, and the reply bytes under
+ * investigation would be the ones that vanished.
+ */
+export declare function escapeBytes(data: string): string;
+/**
+ * The human-input residue of one upstream chunk: `data` with every recognized terminal reply
+ * removed. Returns `''` when the chunk was nothing but replies — the caller reads that as "no
+ * human input here" and leaves the gate's input signal untouched.
+ *
+ * Pure and allocation-cheap; called on every keystroke, so the common case (plain text with
+ * no ESC at all) short-circuits before touching a regex.
+ *
+ * The short-circuit does NOT cover a bracketed paste: `ESC[200~ … ESC[201~` always contains
+ * ESC, so a pasted body — up to the 1 MiB a `/write` request body may carry — runs every
+ * pattern's `replace` over its full length. This is an EXTERNAL paste only (a human pasting
+ * into the browser terminal, or a caller POSTing one to `/api/terminals/:id/write`); a mail
+ * delivery's own bracketed paste (Issue #1567) is written with origin `'delivery'` and never
+ * reaches this function at all, so no long send pays the scan. Left as is deliberately: an
+ * external paste is a rare, human-paced event next to the per-keystroke path this function is
+ * tuned for, and any length guard cheap enough to be worth adding would have to decide where a
+ * reply may legitimately sit inside the payload — which is the over-strip direction, the
+ * silent one.
+ */
+export declare function stripTerminalReplies(data: string): string;
+//# sourceMappingURL=terminal-replies.d.ts.map

package/dist/terminal/terminal-replies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-replies.d.ts","sourceRoot":"","sources":["../../src/terminal/terminal-replies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,UAAU,CAAC;AAqDjD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAM3D;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAShD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQzD"}

package/dist/terminal/terminal-replies.js

@@ -0,0 +1,181 @@
+/**
+ * Terminal REPLY stripping for the delivery gate's input signal (Issue #1473).
+ *
+ * The render gate needs to know when a HUMAN has put something on a session's line, so a
+ * gated delivery never lands on a composer somebody has started typing into. The only
+ * server-side observation point is {@link PtySession.write}'s external branch — every live
+ * client (the web terminal, the VS Code webview, mobile, the raw
+ * `POST /api/terminals/:id/write` route) funnels through it.
+ *
+ * But that stream is not keystrokes. xterm forwards terminal REPLIES — DA, DSR, CPR,
+ * XTWINOPS, DECRPM, DECRQSS, OSC colour queries, focus reports — through the very same
+ * `onData` event as typed characters, because from the client's point of view they are all
+ * "bytes to send upstream". The web client strips a few of them, but ONLY while
+ * `rc.initialPhase` is true (`Terminal.tsx`) — for a session's entire steady-state life that
+ * filter is off, and the VS Code webview and mobile clients never had one at all. (`afx
+ * attach` is not in scope either way: it writes the shellper socket directly, so neither its
+ * keystrokes nor its replies ever pass through `PtySession.write()` — see arch.md §5.)
+ * Counting a reply as human input would produce a hold with nobody at the keyboard, and
+ * worse, a SELF-TRIP: our own delivery write repaints the TUI, the TUI queries geometry, the
+ * browser answers, and the answer reads as a keystroke that blocks the next delivery. So the
+ * filter is a precondition of the whole design, and it lives here — server-side, where every
+ * client is covered, rather than in one cooperative client.
+ *
+ * SIGNAL-ONLY. Nothing here changes what reaches the PTY: the caller still writes the full
+ * chunk verbatim, because the application ASKED for the reply and blocks waiting on it.
+ * Swallowing a DA reply would hang every attached terminal.
+ *
+ * ## Failure directions
+ *
+ * - **Over-strip** (a real keystroke eaten from the signal) → that keystroke goes uncounted,
+ *   which is exactly today's behaviour, so never a regression — but it silently re-opens the
+ *   race this issue exists to close, which is why the survival tests below are the strict half.
+ * - **Under-strip** (a reply counted as input) → a spurious `busy:recent-input` hold that
+ *   clears on the next settle. Fail-safe, and now visible rather than silent.
+ *
+ * The filter is **chunk-local**: it sees exactly the string one `write()` was handed, so a
+ * reply that arrives split across two calls (a short socket read, a coalescing client) matches
+ * no pattern in either half and is under-stripped. That is the fail-safe direction — a hold
+ * that clears itself a settle later — and it is why no pattern here is written to span calls:
+ * buffering across chunks to catch it would put a real keystroke's arrival at the mercy of the
+ * NEXT chunk, which is the over-strip direction, and that one is silent.
+ *
+ * ## The table is derived from a PINNED dependency
+ *
+ * Every pattern below was read out of `@xterm/xterm@{@link XTERM_REPLY_TABLE_VERSION}`'s
+ * bundle — each `triggerDataEvent` call site that emits a reply rather than a keystroke. A
+ * version bump is therefore a REVIEW TRIGGER for this file: a newly-answered query (kitty
+ * keyboard, XTVERSION) becomes an uncounted-reply hold until its shape is added here. Two
+ * patterns below are pre-emptive for that reason and match nothing stock xterm 5.5 emits.
+ *
+ * ## Case sensitivity is load-bearing
+ *
+ * `ESC[C` is Right-arrow and `ESC[1;5C` is Ctrl-Right. The CSI family pattern keys on a
+ * LOWERCASE final byte set (`c`/`n`/`t`/`y`); an `i` flag on it would strip every arrow key,
+ * Home/End and shift-Tab out of the signal. No pattern here carries `i`, and
+ * `terminal-replies.test.ts` pins the survival of those exact sequences.
+ */
+/**
+ * The `@xterm/xterm` version whose emission sites this table was enumerated from. Bumping the
+ * dependency past it means re-reading its `triggerDataEvent` call sites; a test asserts this
+ * constant against the installed package's version so the bump cannot pass silently.
+ */
+export const XTERM_REPLY_TABLE_VERSION = '5.5.0';
+/**
+ * Sequences a terminal emulator sends UPSTREAM in answer to the application, never as a
+ * human action. Anchored one shape at a time — never a blanket "starts with ESC[" — so a
+ * keystroke can only be eaten by a pattern that names its exact form.
+ *
+ * What each covers, in xterm 5.5.0's own emission order:
+ *
+ *   1. The CSI answer family, keyed on a lowercase final byte:
+ *      - DA1  `ESC[?1;2c`, `ESC[?6c`            (`sendDeviceAttributesPrimary`)
+ *      - DA2  `ESC[>0;276;0c`, `ESC[>85;95;0c`, `ESC[>83;40003;0c`
+ *      - DSR  `ESC[0n`                          (`deviceStatus`, param 5)
+ *      - XTWINOPS `ESC[4;h;wt`, `ESC[6;h;wt`, `ESC[8;rows;colst`
+ *      - DECRPM `ESC[?2004$y`, `ESC[1;2$y`      (`_reportMode`)
+ *      No key sequence xterm can produce ends in `c`, `n`, `t` or `y` — its key finals are
+ *      `~ A B C D F H I O Z R M m`, all outside this class.
+ *   2. CPR `ESC[12;40R` and DECXCPR `ESC[?12;40R` — TWO params, not three. (An earlier
+ *      three-param pattern would have missed both.)
+ *   3. The kitty-keyboard query answer, for a fork that grows one. Its literal `?` is what
+ *      keeps it off real kitty-ENCODED keystrokes, which carry no `?`.
+ *   4. Focus in/out `ESC[I` / `ESC[O`. Stripped deliberately: a focus report cannot change
+ *      composer CONTENT, whereas a click that could carries its own mouse report — which is
+ *      preserved (see below). So this costs no coverage and stops an alt-tab holding mail.
+ *   5. DECRQSS `ESC P 1 $ r … ESC \` (`requestStatusString`).
+ *   6. XTVERSION `ESC P > | … ESC \` — pre-emptive; stock 5.5.0 never answers it.
+ *   7. OSC colour reports `ESC ] 10;rgb:…` / `ESC ] 4;12;rgb:…`, terminated by ST or BEL.
+ *
+ * NOT stripped, on purpose:
+ *
+ *   - **Mouse reports** (`ESC[<0;10;5M`, `ESC[<0;10;5m`, and the X10 `ESC[M` + 3 bytes). These
+ *     are built from a DOM event by the mouse ENCODERS and pushed through the generic data
+ *     path — they are a human ACTION that can change the composer (a click moves the cursor,
+ *     a middle-click pastes, a drag selects), not a parser answer. Stripping them would
+ *     re-open the race for every mouse-driven TUI. Motion tracking can be chatty, but that
+ *     only holds delivery while the mouse is actually moving, and it clears one settle after
+ *     it stops — the fail-safe direction.
+ *   - **Bracketed paste markers** (`ESC[200~` / `ESC[201~`). A paste is human input.
+ *
+ * Content-blind by construction: a reply-SHAPED byte run inside a bracketed paste is stripped
+ * from the signal while the surrounding pasted text still counts. Intended (over-strip is the
+ * safe direction) and pinned by a test.
+ */
+const TERMINAL_REPLY_PATTERNS = [
+    /\x1b\[[?>=]?[0-9;]*\$?[cnty]/g,
+    /\x1b\[\??[0-9]+;[0-9]+R/g,
+    /\x1b\[\?[0-9;]*u/g,
+    /\x1b\[[IO]/g,
+    /\x1bP[0-9]\$r[^\x1b]*\x1b\\/g,
+    /\x1bP>\|[^\x1b]*\x1b\\/g,
+    /\x1b\][0-9;]+;rgb:[0-9a-fA-F/]+(?:\x07|\x1b\\)/g,
+];
+/**
+ * Every recognized terminal reply in `data`, in the order the patterns match them.
+ *
+ * Diagnostics only — {@link stripTerminalReplies} does the real work and never calls this. It
+ * backs the `AF_LOG_INPUT_SIGNAL` trace, whose whole purpose is to let a human SEE which bytes
+ * were treated as a reply and which survived as input, rather than infer it from a hold that
+ * did or did not happen.
+ */
+export function terminalReplyMatches(data) {
+    const found = [];
+    for (const pattern of TERMINAL_REPLY_PATTERNS) {
+        for (const m of data.matchAll(pattern))
+            found.push(m[0]);
+    }
+    return found;
+}
+/**
+ * Render a byte run so it can be read in a log line: ESC as `\e`, other C0 controls and DEL as
+ * `\xNN`, everything else literal.
+ *
+ * Printing raw ESC to a terminal log would make the log itself move the cursor and repaint —
+ * the diagnostic would corrupt the thing it is diagnosing, and the reply bytes under
+ * investigation would be the ones that vanished.
+ */
+export function escapeBytes(data) {
+    let out = '';
+    for (const ch of data) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (ch === '\x1b')
+            out += '\\e';
+        else if (code < 0x20 || code === 0x7f)
+            out += `\\x${code.toString(16).padStart(2, '0')}`;
+        else
+            out += ch;
+    }
+    return out;
+}
+/**
+ * The human-input residue of one upstream chunk: `data` with every recognized terminal reply
+ * removed. Returns `''` when the chunk was nothing but replies — the caller reads that as "no
+ * human input here" and leaves the gate's input signal untouched.
+ *
+ * Pure and allocation-cheap; called on every keystroke, so the common case (plain text with
+ * no ESC at all) short-circuits before touching a regex.
+ *
+ * The short-circuit does NOT cover a bracketed paste: `ESC[200~ … ESC[201~` always contains
+ * ESC, so a pasted body — up to the 1 MiB a `/write` request body may carry — runs every
+ * pattern's `replace` over its full length. This is an EXTERNAL paste only (a human pasting
+ * into the browser terminal, or a caller POSTing one to `/api/terminals/:id/write`); a mail
+ * delivery's own bracketed paste (Issue #1567) is written with origin `'delivery'` and never
+ * reaches this function at all, so no long send pays the scan. Left as is deliberately: an
+ * external paste is a rare, human-paced event next to the per-keystroke path this function is
+ * tuned for, and any length guard cheap enough to be worth adding would have to decide where a
+ * reply may legitimately sit inside the payload — which is the over-strip direction, the
+ * silent one.
+ */
+export function stripTerminalReplies(data) {
+    if (!data.includes('\x1b'))
+        return data;
+    let out = data;
+    for (const pattern of TERMINAL_REPLY_PATTERNS) {
+        out = out.replace(pattern, '');
+        if (out === '')
+            return '';
+    }
+    return out;
+}
+//# sourceMappingURL=terminal-replies.js.map

package/dist/terminal/terminal-replies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-replies.js","sourceRoot":"","sources":["../../src/terminal/terminal-replies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,OAAO,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,uBAAuB,GAAsB;IACjD,+BAA+B;IAC/B,0BAA0B;IAC1B,mBAAmB;IACnB,aAAa;IACb,8BAA8B;IAC9B,yBAAyB;IACzB,iDAAiD;CAClD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,uBAAuB,EAAE,CAAC;QAC9C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,EAAE,KAAK,MAAM;YAAE,GAAG,IAAI,KAAK,CAAC;aAC3B,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,GAAG,IAAI,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;;YACpF,GAAG,IAAI,EAAE,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,OAAO,IAAI,uBAAuB,EAAE,CAAC;QAC9C,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC/B,IAAI,GAAG,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cluesmith/codev",
-  "version": "3.3.3",
+  "version": "3.3.4",
   "description": "Codev CLI - AI-assisted software development framework",
   "type": "module",
   "bin": {
@@ -35,9 +35,9 @@
     "open": "^10.1.0",
     "tree-kill": "^1.2.2",
     "ws": "^8.18.0",
-    "@cluesmith/codev-core": "3.3.3",
-    "@cluesmith/codev-sdk": "3.3.3",
-    "@cluesmith/codev-types": "3.3.3"
+    "@cluesmith/codev-core": "3.3.4",
+    "@cluesmith/codev-types": "3.3.4",
+    "@cluesmith/codev-sdk": "3.3.4"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",

package/scripts/forge/github/pr-list.sh

@@ -7,5 +7,9 @@
 # as objects (users carry `login`; teams carry `slug`/`name` and no `login`), so
 # `.login // empty` keeps user reviewers and drops team reviewers — matching the
 # `reviewRequests: string[]` contract in PrListItem (forge-contracts.ts).
-exec gh pr list --json number,title,url,reviewDecision,body,createdAt,author,reviewRequests,isDraft \
-  | jq '[.[] | .reviewRequests = [.reviewRequests[].login // empty]]'
+#
+# Not `gh … | jq`: POSIX sh has no pipefail, so the caller would see jq's exit
+# status and a rate-limited gh would look like a successful empty list (#1645).
+# forge-executable: gh
+out="$(gh pr list --json number,title,url,reviewDecision,body,createdAt,author,reviewRequests,isDraft)" || exit 1
+printf '%s' "$out" | jq '[.[] | .reviewRequests = [.reviewRequests[].login // empty]]'

package/scripts/forge/github/pr-search.sh

@@ -1,7 +1,9 @@
 #!/bin/sh
 # Forge concept: pr-search (GitHub via gh CLI)
 # Input: CODEV_SEARCH_QUERY
-# Output: JSON [{number, headRefName, baseRefName}]
+# Output: JSON [{number, headRefName, baseRefName, state}]
 # --state all is required so the search includes merged/closed PRs; without it
 # `gh pr list` defaults to --state open and post-merge lookups return nothing (#759).
-exec gh pr list --state all --search "$CODEV_SEARCH_QUERY" --json number,headRefName,baseRefName
+# `state` (OPEN/MERGED/CLOSED) lets consumers that only want open PRs filter
+# client-side — the spawn collision guard must ignore merged/closed ones (#1637).
+exec gh pr list --state all --search "$CODEV_SEARCH_QUERY" --json number,headRefName,baseRefName,state

package/scripts/forge/gitlab/issue-search.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-search (GitLab via glab CLI)
+# forge-executable: glab
 #
 # ⚠️ UNVERIFIED — mirrors gitlab/issue-list.sh (raw `glab ... --output json`,
 #    no field normalization) plus a state flag and a `body` field surfaced from

package/scripts/forge/gitlab/pr-search.sh

@@ -1,5 +1,38 @@
 #!/bin/sh
-# Forge concept: pr-search (GitLab via glab CLI)
+# Forge concept: pr-search (GitLab via glab CLI — merge requests)
+# Output: JSON [{number, headRefName, baseRefName, state, ...glab fields}]
+#
+# ⚠️ UNVERIFIED — `glab` is not available in the authoring environment (#920);
+#    written against glab's documented `mr list --output json` shape (confirmed
+#    against the field mappings already documented in gitlab/pr-list.sh and
+#    gitlab/pr-exists.sh). Smoke-test before relying on it.
+#
 # --all is required so the search includes merged/closed MRs; without it
 # `glab mr list` defaults to opened only and post-merge lookups return nothing (#759).
-exec glab mr list --all --search "$CODEV_SEARCH_QUERY" --output json
+#
+# Maps glab's GitLab-shaped fields into the forge-neutral PrSearchItem contract
+# (forge-contracts.ts); `. + {…}` is non-destructive for keys we don't touch:
+#   iid           -> number        (the MR number glab mr view/merge expects)
+#   source_branch -> headRefName
+#   target_branch -> baseRefName
+# Without this the spawn guard's message reads `PR #undefined` and consult's
+# findPRForIssue can't resolve the MR's base branch on GitLab.
+#
+# glab reports state lowercase (opened/merged/closed/locked); normalize to the
+# GitHub convention (OPEN/MERGED/CLOSED) so consumers filter with one comparison.
+# The spawn collision guard keys off state === "OPEN" to ignore merged MRs (#1637).
+# `locked` (a transient merging state) maps to OPEN too: the guard should err
+# toward the recoverable --force prompt, never silently skip a live collision.
+#
+# Not `glab … | jq`: POSIX sh has no pipefail, so the caller would see jq's exit
+# status and a failed glab would look like a successful empty list (#1645).
+# The capture-then-pipe shape hides `glab` from extractExecutable's first-line
+# heuristic (it lands on the `printf` builtin), so declare the backend explicitly
+# — same as github/pr-list.sh (#1645).
+# forge-executable: glab
+out="$(glab mr list --all --search "$CODEV_SEARCH_QUERY" --output json)" || exit 1
+printf '%s' "$out" | jq 'map(.
+  + {number: .iid}
+  + {headRefName: .source_branch}
+  + {baseRefName: .target_branch}
+  + {state: ((.state // "") | ascii_downcase as $s | if $s == "opened" or $s == "locked" then "OPEN" else ($s | ascii_upcase) end)})'

package/scripts/forge/linear/auth-status.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: auth-status (Linear via GraphQL API)
+# forge-executable: curl
 # Output: exit code (0 = authenticated)
 set -e
 

package/scripts/forge/linear/issue-comment.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-comment (Linear via GraphQL API)
+# forge-executable: curl
 # Input: CODEV_ISSUE_ID, CODEV_COMMENT_BODY
 # Output: exit code only
 set -e

package/scripts/forge/linear/issue-list.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-list (Linear via GraphQL API)
+# forge-executable: curl
 # Input: CODEV_LINEAR_TEAM (team key, e.g. "ENG")
 # Output: JSON [{number, title, url, labels, createdAt, author, assignees}]
 set -e

package/scripts/forge/linear/issue-search.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-search (Linear via GraphQL API)
+# forge-executable: curl
 #
 # ⚠️ UNVERIFIED — mirrors linear/issue-list.sh with `description` added to the
 #    query (mapped to `body`) and the state filter parameterized. No Linear

package/scripts/forge/linear/issue-view.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-view (Linear via GraphQL API)
+# forge-executable: curl
 # Input: CODEV_ISSUE_ID (e.g. "ENG-123")
 # Output: JSON {title, body, state, url, author, createdAt, assignees, labels, milestone, comments[]}
 #

package/scripts/forge/linear/recently-closed.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: recently-closed (Linear via GraphQL API)
+# forge-executable: curl
 # Input: CODEV_LINEAR_TEAM, CODEV_SINCE_DATE (optional, ISO date)
 # Output: JSON [{number, title, url, labels, createdAt, closedAt}]
 set -e

package/scripts/forge/linear/user-identity.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: user-identity (Linear via GraphQL API)
+# forge-executable: curl
 # Output: plain text display name
 set -e
 

package/skeleton/.claude/skills/generate-image/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-image
-description: AI image generation via Gemini, or Atlas Cloud with `-p atlas`. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires GEMINI_API_KEY or GOOGLE_API_KEY, or ATLASCLOUD_API_KEY when using `-p atlas`.
+description: AI image generation via Gemini with optional async providers. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires the API key for the selected provider.
 ---
 
 # generate-image - AI Image Generation
@@ -22,7 +22,7 @@ Note: this is a `codev` subcommand, not standalone.
 -r, --resolution <res>     Resolution: 1K, 2K, 4K (default: 1K)
 -a, --aspect <ratio>       Aspect ratio (default: 1:1)
 --ref <image>              Reference image (repeatable, max 14)
--p, --provider <name>      Provider: gemini (default) or atlas
+-p, --provider <name>      Provider name (default: gemini)
 ```
 
 ## Aspect ratios
@@ -64,3 +64,20 @@ Measured differences on that path:
   than silently ignoring the images.
 - The model returns JPEG, so the output file is named after its actual bytes
   instead of writing JPEG into the default `output.png`.
+
+## MuAPI provider
+
+`-p muapi` uses MuAPI's Nano Banana Pro endpoint with the same aspect-ratio and
+resolution controls. Set `MUAPI_API_KEY` (or `MU_API_KEY`) using the [MuAPI
+access keys page](https://muapi.ai/access-keys). Reference images are uploaded
+to MuAPI and sent to the edit endpoint; returned media is downloaded only over
+HTTPS.
+
+```bash
+codev generate-image "A sunset over mountains" -p muapi -a 16:9
+codev generate-image "Keep the subject, change the lighting" -p muapi --ref subject.png
+```
+
+The provider submits a job, polls the [MuAPI image API](https://muapi.ai/ai-image-api),
+and writes the returned image locally. Polling and individual requests are
+bounded, and the API key is never sent to the returned media host.

package/skeleton/.codex/skills/generate-image/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-image
-description: AI image generation via Gemini, or Atlas Cloud with `-p atlas`. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires GEMINI_API_KEY or GOOGLE_API_KEY, or ATLASCLOUD_API_KEY when using `-p atlas`.
+description: AI image generation via Gemini with optional async providers. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires the API key for the selected provider.
 ---
 
 # generate-image - AI Image Generation
@@ -22,7 +22,7 @@ Note: this is a `codev` subcommand, not standalone.
 -r, --resolution <res>     Resolution: 1K, 2K, 4K (default: 1K)
 -a, --aspect <ratio>       Aspect ratio (default: 1:1)
 --ref <image>              Reference image (repeatable, max 14)
--p, --provider <name>      Provider: gemini (default) or atlas
+-p, --provider <name>      Provider name (default: gemini)
 ```
 
 ## Aspect ratios
@@ -64,3 +64,20 @@ Measured differences on that path:
   than silently ignoring the images.
 - The model returns JPEG, so the output file is named after its actual bytes
   instead of writing JPEG into the default `output.png`.
+
+## MuAPI provider
+
+`-p muapi` uses MuAPI's Nano Banana Pro endpoint with the same aspect-ratio and
+resolution controls. Set `MUAPI_API_KEY` (or `MU_API_KEY`) using the [MuAPI
+access keys page](https://muapi.ai/access-keys). Reference images are uploaded
+to MuAPI and sent to the edit endpoint; returned media is downloaded only over
+HTTPS.
+
+```bash
+codev generate-image "A sunset over mountains" -p muapi -a 16:9
+codev generate-image "Keep the subject, change the lighting" -p muapi --ref subject.png
+```
+
+The provider submits a job, polls the [MuAPI image API](https://muapi.ai/ai-image-api),
+and writes the returned image locally. Polling and individual requests are
+bounded, and the API key is never sent to the returned media host.