@north-light/crouter 0.3.176 → 0.3.178

package/dist/api/client.d.ts

@@ -33,7 +33,7 @@ export interface CrtrClientOptions {
      *  autostart is on; after it resolves, the client polls `/healthz` and retries
      *  the original request once. Absent → a cold socket throws `daemon_unavailable`. */
     onColdSocket?: () => Promise<void>;
-    /** Injected cold-start diagnostic (issue #516). Called ONLY when the bounded
+    /** Injected cold-start diagnostic. Called ONLY when the bounded
      *  `/healthz` poll times out after `onColdSocket`, so the caller can attach
      *  operator-useful context (e.g. a bounded tail of crtrd's stderr log) to the
      *  `daemon_unavailable` error instead of it staying a bare message. Must
@@ -43,7 +43,7 @@ export interface CrtrClientOptions {
     /** Bounded window (ms) to poll `/healthz` after `onColdSocket` resolves
      *  before giving up with `daemon_unavailable`. Defaults to
      *  `HEALTHZ_POLL_WINDOW_MS`. This must NOT silently drift from whatever
-     *  window actually governs "did the daemon start" (issue #508 follow-up):
+     *  window actually governs "did the daemon start":
      *  `onColdSocket` is fire-and-forget, so this poll is the ONLY deadline that
      *  determines whether the CLI reports success. A caller whose `onColdSocket`
      *  hook triggers a differently-windowed startup verifier (e.g. the CLI's
@@ -253,8 +253,8 @@ export declare class CrtrClient {
     private handleColdSocket;
 }
 /** Compose the cold-start `/healthz`-timeout `daemon_unavailable` message,
- *  appending the injected diagnostic (issue #516) when one is present instead
- *  of discarding the real startup failure behind a bare message. Exported (not
+ *  appending the injected diagnostic when one is present instead of discarding
+ *  the real startup failure behind a bare message. Exported (not
  *  from the package's public `index.ts` surface, which is dependency-light by
  *  design) purely so the regression test can assert the composition without
  *  waiting out the real poll window. */

package/dist/api/client.js

@@ -655,8 +655,8 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /** Compose the cold-start `/healthz`-timeout `daemon_unavailable` message,
- *  appending the injected diagnostic (issue #516) when one is present instead
- *  of discarding the real startup failure behind a bare message. Exported (not
+ *  appending the injected diagnostic when one is present instead of discarding
+ *  the real startup failure behind a bare message. Exported (not
  *  from the package's public `index.ts` surface, which is dependency-light by
  *  design) purely so the regression test can assert the composition without
  *  waiting out the real poll window. */

package/dist/api/dto/lifecycle.d.ts

@@ -3,7 +3,7 @@ import type { NodeIdDTO, NodeStatusDTO } from './common.js';
 export interface ReviveRequest {
     /** Resume the saved conversation (true) vs a fresh launch (false). */
     resume?: boolean;
-    /** Clear the finalization latch before reviving (#339 `--reopen` gate). The
+    /** Clear the finalization latch before reviving (the `--reopen` gate). The
      *  latch clear is a canvas write, so the gate is enforced server-side: with
      *  `reopen:false` (default) a finalized node is REJECTED (`node_finalized`);
      *  with `reopen:true` a node that is NOT finalized is rejected

package/dist/api/dto/reports.d.ts

@@ -20,7 +20,7 @@ export interface PushReportResultDTO {
     /** Present (and true) only for a `final` push whose reporting node owned a
      *  managed worktree with zero commits ahead of its base and no uncommitted
      *  changes: the server auto-dropped it instead of blocking on `node worktree
-     *  close` (#327/#333). A worktree with real unlanded work instead blocks with
+     *  close`. A worktree with real unlanded work instead blocks with
      *  an `open_managed_worktree` error. */
     worktree_auto_dropped?: boolean;
     /** Present only alongside `worktree_auto_dropped`: the checkout path dropped. */

package/dist/clients/attach/__tests__/frame-selection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clients/attach/__tests__/frame-selection.test.js

@@ -0,0 +1,84 @@
+// Mouse drag-select copies out of the PHYSICAL frame rows, which carry SGR
+// color, OSC-8 link boundaries, pi-tui's APC cursor marker, and wide glyphs. A
+// column is a terminal cell, never a string index — get that wrong and the copy
+// silently slices mid-escape or off-by-N, with the highlight still looking right
+// on screen.
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { highlightCells, rowCells, sliceCells } from '../ansi-cells.js';
+import { createFrameSelection } from '../session/selection.js';
+const CURSOR_MARKER = '\x1b_pi-cursor\x1b\\';
+const LINK = (uri, text) => `\x1b]8;;${uri}\x07${text}\x1b]8;;\x07`;
+test('cells are counted as the terminal counts them', () => {
+    assert.equal(rowCells('plain'), 5);
+    assert.equal(rowCells('\x1b[31mred\x1b[0m'), 3);
+    assert.equal(rowCells(LINK('file:///tmp/a.ts', 'a.ts')), 4);
+    assert.equal(rowCells(`ab${CURSOR_MARKER}cd`), 4);
+    assert.equal(rowCells('日本'), 4);
+});
+test('a slice returns the plain text under those cells', () => {
+    assert.equal(sliceCells('\x1b[31mhello\x1b[0m world', 0, 5), 'hello');
+    assert.equal(sliceCells('\x1b[31mhello\x1b[0m world', 6, 11), 'world');
+    assert.equal(sliceCells(`src/${LINK('file:///tmp/a.ts', 'a.ts')}:12`, 0, 8), 'src/a.ts');
+    assert.equal(sliceCells(`ab${CURSOR_MARKER}cd`, 0, 4), 'abcd');
+    // A wide glyph belongs to the cell it starts at and is never split in half.
+    assert.equal(sliceCells('日本語', 2, 4), '本');
+});
+test('highlighting restyles without changing what the row says', () => {
+    const row = '\x1b[31mhello\x1b[0m world';
+    const painted = highlightCells(row, 0, 5, 80);
+    assert.equal(sliceCells(painted, 0, rowCells(row)), 'hello world');
+    assert.equal(rowCells(painted), rowCells(row));
+    assert.ok(painted.includes('\x1b[7m'));
+    // A reset inside the span would drop the highlight, so inverse is re-asserted.
+    assert.equal(highlightCells(row, 0, 11, 80).split('\x1b[7m').length - 1, 2);
+});
+test('the cursor marker survives a highlight that starts on its cell', () => {
+    const painted = highlightCells(`ab${CURSOR_MARKER}cd`, 2, 4, 80);
+    assert.ok(painted.includes(CURSOR_MARKER));
+    assert.equal(sliceCells(painted, 0, 4), 'abcd');
+});
+test('a short row pads so a multi-row selection reads as one block, never past the pane', () => {
+    assert.equal(rowCells(highlightCells('ab', 0, 6, 80)), 6);
+    // Padding past the pane width would wrap the row and break the frame's row count.
+    assert.equal(rowCells(highlightCells('ab', 0, 6, 4)), 4);
+});
+test('a press that never moves stays a click, so file links still open', () => {
+    const selection = createFrameSelection({ frame: () => ['src/a.ts'], width: () => 40 });
+    selection.begin(3, 1);
+    assert.deepEqual(selection.release(), { kind: 'click', column: 3, row: 1 });
+    assert.equal(selection.active(), false);
+});
+test('a drag across rows selects terminal-style: to the edge, then whole rows', () => {
+    const frame = ['first row', '\x1b[32msecond row\x1b[0m', 'third row'];
+    const selection = createFrameSelection({ frame: () => frame, width: () => 40 });
+    selection.begin(7, 1);
+    assert.equal(selection.extend(5, 3), true);
+    // Same cell twice is not a change — no wasted render.
+    assert.equal(selection.extend(5, 3), false);
+    const painted = selection.apply(frame);
+    assert.equal(painted.length, 3);
+    assert.ok(painted[0].includes('\x1b[7m'));
+    assert.equal(sliceCells(painted[1], 0, rowCells(frame[1])), 'second row');
+    assert.equal(selection.active(), true);
+    assert.equal(selection.clear(), true);
+    assert.equal(selection.active(), false);
+});
+test('a backwards drag selects the same span as a forwards one', () => {
+    const frame = ['abcdef', 'ghijkl'];
+    const forwards = createFrameSelection({ frame: () => frame, width: () => 6 });
+    forwards.begin(3, 1);
+    forwards.extend(4, 2);
+    const backwards = createFrameSelection({ frame: () => frame, width: () => 6 });
+    backwards.begin(4, 2);
+    backwards.extend(3, 1);
+    assert.deepEqual(backwards.apply(frame), forwards.apply(frame));
+});
+test('an empty drag over blank rows reports nothing to copy', () => {
+    // Releasing over content would shell out to the clipboard; blank rows settle
+    // the geometry without leaving the process.
+    const selection = createFrameSelection({ frame: () => ['', '', ''], width: () => 40 });
+    selection.begin(2, 1);
+    selection.extend(5, 3);
+    assert.deepEqual(selection.release(), { kind: 'selection', notice: 'Nothing to copy — selection is empty' });
+});

package/dist/clients/attach/__tests__/group-activity.test.js

@@ -30,7 +30,7 @@ async function summarizedGroup(messages, key) {
         stats: {},
         state: { isStreaming: false },
         toolGroupSummaries: {
-            [key]: { bullets: ['broker recap'], nodesSpawned: 0, filesEdited: 0 },
+            [key]: { bullets: ['broker recap'], nodesSpawned: 0, filesDeleted: 0 },
         },
     });
     const group = internals.groups.find((candidate) => candidate.key === key);
@@ -70,7 +70,7 @@ test('a folded recap carries paths and counts, never diff or write payload bodie
         bashMode: tone('bashMode'), bashModeAlt: tone('bashModeAlt'),
     };
     const recap = new GroupRecapComponent();
-    recap.setRecap({ bullets: ['finished'], nodesSpawned: 0, filesEdited: 2 }, 2, { memories: [{ action: 'read', name: 'alpha', path: '/tmp/memories/alpha.md' }], files: recorder.activity().files }, true, palette);
+    recap.setRecap({ bullets: ['finished'], nodesSpawned: 0, filesDeleted: 2 }, 2, { memories: [{ action: 'read', name: 'alpha', path: '/tmp/memories/alpha.md' }], files: recorder.activity().files }, true, palette);
     const text = recap.render(120).join('\n');
     assert.match(text, /overwritten\.ts/, 'the recap still names what changed');
     assert.doesNotMatch(text, /sensitive-old-diff|sensitive-new-diff|sensitive-write-payload/, 'payload bodies never leak into a recap');

package/dist/clients/attach/ansi-cells.d.ts

@@ -0,0 +1,31 @@
+/** Read one terminal control sequence so non-printing ANSI never takes a cell.
+ *  `undefined` means the sequence runs off the end of the row. */
+export declare function readEscape(line: string, start: number): {
+    text: string;
+    end: number;
+} | undefined;
+/** One printable grapheme, with the escape sequences that preceded it. */
+export type RowGlyph = {
+    /** The grapheme itself, with no ANSI attached. */
+    text: string;
+    /** 0-indexed terminal cell this grapheme starts at. */
+    cell: number;
+    /** Cells occupied — 2 for a wide grapheme, 0 for a zero-width one. */
+    width: number;
+};
+/** Walk `line` as the terminal does, calling `onGlyph` per printable grapheme
+ *  and `onEscape` per control sequence, in row order. Returns the cell count. */
+export declare function walkRow(line: string, visit: {
+    onGlyph?: (glyph: RowGlyph) => void;
+    onEscape?: (escape: string) => void;
+}): number;
+/** Cells the row occupies on screen. */
+export declare function rowCells(line: string): number;
+/** Plain text of cells `[from, to)` — every escape, link boundary, and cursor
+ *  marker dropped, exactly what a terminal copies out of that span. */
+export declare function sliceCells(line: string, from: number, to: number): string;
+/** Reverse-video cells `[from, to)`, re-asserting inverse after any SGR inside
+ *  the span (a reset there would otherwise drop the highlight mid-selection).
+ *  A short row is padded with spaces so a multi-row selection reads as one
+ *  block, never past `maxCells`. */
+export declare function highlightCells(line: string, from: number, to: number, maxCells: number): string;

package/dist/clients/attach/ansi-cells.js

@@ -0,0 +1,120 @@
+// ansi-cells.ts — cell arithmetic over a rendered terminal row.
+//
+// A composed frame row mixes printable graphemes with SGR colors, OSC-8 link
+// boundaries, and pi-tui's APC cursor marker. Anything that addresses a row by
+// terminal column — link hit tests, mouse selection — has to walk it the way the
+// terminal does: escapes take no cell, wide graphemes take two. Both the attach
+// session and the renderers need that walk, so it lives at the client root
+// rather than inside either peer.
+import stringWidth from 'string-width';
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+const INVERSE_ON = '\x1b[7m';
+const INVERSE_OFF = '\x1b[27m';
+/** Read one terminal control sequence so non-printing ANSI never takes a cell.
+ *  `undefined` means the sequence runs off the end of the row. */
+export function readEscape(line, start) {
+    const kind = line[start + 1];
+    if (kind === undefined)
+        return undefined;
+    // OSC, APC, DCS, and PM are string controls terminated by BEL or ST. pi-tui's
+    // cursor marker uses APC, so it must consume no display cells here.
+    if (kind === ']' || kind === '_' || kind === 'P' || kind === '^') {
+        const bel = line.indexOf('\x07', start + 2);
+        const st = line.indexOf('\x1b\\', start + 2);
+        const end = bel === -1 ? st : st === -1 ? bel : Math.min(bel, st);
+        if (end === -1)
+            return undefined;
+        return { text: line.slice(start, end + (end === bel ? 1 : 2)), end: end + (end === bel ? 1 : 2) };
+    }
+    if (kind === '[') {
+        let end = start + 2;
+        while (end < line.length && (line.charCodeAt(end) < 0x40 || line.charCodeAt(end) > 0x7e))
+            end++;
+        if (end >= line.length)
+            return undefined;
+        return { text: line.slice(start, end + 1), end: end + 1 };
+    }
+    return { text: line.slice(start, start + 2), end: start + 2 };
+}
+/** Walk `line` as the terminal does, calling `onGlyph` per printable grapheme
+ *  and `onEscape` per control sequence, in row order. Returns the cell count. */
+export function walkRow(line, visit) {
+    let cell = 0;
+    let index = 0;
+    while (index < line.length) {
+        if (line[index] === '\x1b') {
+            const escape = readEscape(line, index);
+            if (escape === undefined)
+                break;
+            visit.onEscape?.(escape.text);
+            index = escape.end;
+            continue;
+        }
+        const nextEscape = line.indexOf('\x1b', index);
+        const text = line.slice(index, nextEscape === -1 ? undefined : nextEscape);
+        for (const segment of GRAPHEMES.segment(text)) {
+            const width = stringWidth(segment.segment);
+            visit.onGlyph?.({ text: segment.segment, cell, width });
+            cell += width;
+        }
+        index = nextEscape === -1 ? line.length : nextEscape;
+    }
+    return cell;
+}
+/** Cells the row occupies on screen. */
+export function rowCells(line) {
+    return walkRow(line, {});
+}
+/** Plain text of cells `[from, to)` — every escape, link boundary, and cursor
+ *  marker dropped, exactly what a terminal copies out of that span. */
+export function sliceCells(line, from, to) {
+    let text = '';
+    walkRow(line, {
+        onGlyph: (glyph) => {
+            if (glyph.cell >= from && glyph.cell < to)
+                text += glyph.text;
+        },
+    });
+    return text;
+}
+/** Reverse-video cells `[from, to)`, re-asserting inverse after any SGR inside
+ *  the span (a reset there would otherwise drop the highlight mid-selection).
+ *  A short row is padded with spaces so a multi-row selection reads as one
+ *  block, never past `maxCells`. */
+export function highlightCells(line, from, to, maxCells) {
+    const end = Math.min(to, maxCells);
+    if (end <= from || from < 0)
+        return line;
+    let out = '';
+    let inside = false;
+    const open = () => { if (!inside) {
+        out += INVERSE_ON;
+        inside = true;
+    } };
+    const close = () => { if (inside) {
+        out += INVERSE_OFF;
+        inside = false;
+    } };
+    const cells = walkRow(line, {
+        onEscape: (escape) => {
+            out += escape;
+            // An SGR inside the span may have reset every attribute, including ours.
+            if (inside && escape.endsWith('m'))
+                out += INVERSE_ON;
+        },
+        onGlyph: (glyph) => {
+            if (glyph.cell >= from && glyph.cell < end)
+                open();
+            else
+                close();
+            out += glyph.text;
+        },
+    });
+    close();
+    if (cells < end) {
+        const gap = Math.max(0, from - cells);
+        const highlighted = end - Math.max(from, cells);
+        out += ' '.repeat(gap) + INVERSE_ON + ' '.repeat(highlighted) + INVERSE_OFF;
+    }
+    return out;
+}

package/dist/clients/attach/config.js

@@ -29,10 +29,10 @@ export function defaultAgentDir() {
 }
 /**
  * pi's `app.*` editor keybindings — VENDORED from pi `core/keybindings.ts`
- * `KEYBINDINGS` (the const is not exported; review-C1 pattern). This is the
- * subset CustomEditor's main editor consults; the selector-internal bindings
- * (`app.tree.*`, `app.models.*`, session delete/rename) are omitted because the
- * attach viewer does not open those selectors in Phase 4. Re-sync on each SDK
+ * `KEYBINDINGS` (the const is not exported). This is the subset CustomEditor's
+ * main editor consults; the selector-internal bindings (`app.tree.*`,
+ * `app.models.*`, session delete/rename) are omitted because the attach viewer
+ * does not open those selectors. Re-sync on each SDK
  * bump against `core/keybindings.js`.
  */
 const APP_KEYBINDINGS = {
@@ -148,7 +148,7 @@ export async function mirrorKittyProtocolToEditor(active) {
  * Resolve the `fd` binary path the @-mention file picker needs. pi-tui's
  * `CombinedAutocompleteProvider` only returns file suggestions when handed an
  * `fdPath` (its third ctor arg) — without it, typing `@` triggers the picker but
- * `getFuzzyFileSuggestions` returns `[]`, so the picker never appears (issue #6).
+ * `getFuzzyFileSuggestions` returns `[]`, so the picker never appears.
  * pi's own interactive mode resolves this via `ensureTool('fd')` from its
  * internal `utils/tools-manager` (checks pi's managed bin dir + system PATH,
  * downloading the binary if missing). That module is NOT on pi-coding-agent's

package/dist/clients/attach/input/clipboard-image.js

@@ -1,4 +1,4 @@
-// input/clipboard-image.ts — read the clipboard image for `crtr surface attach` (T6, review M1).
+// input/clipboard-image.ts — read the clipboard image for `crtr surface attach`.
 //
 // pi's `readClipboardImage` is NOT re-exported (it lives behind a native
 // clipboard binding + Photon worker the package gates off `.`-only exports), so
@@ -21,7 +21,7 @@
 // JPEG and picks the smaller, so it doubles as format normalization;
 // `convertToPng` is the fallback when the Photon resizer is unavailable. The
 // fallbacks (convertToPng / raw bytes) are NOT size-bounded by `resizeImage`, so
-// each is gated on the SAME MAX_BYTES base64 ceiling (review M1): over it → the
+// each is gated on the SAME MAX_BYTES base64 ceiling: over it → the
 // image is DROPPED with a user-visible note rather than shipped as an over-cap
 // frame that would overflow BROKER_READ_CAPS.maxLineBytes (24 MiB) and destroy
 // the viewer socket. The result is an `ImageContent` (pi-ai) ready to drop

package/dist/clients/attach/input/ref-autocomplete.js

@@ -94,7 +94,7 @@ export class RefAwareAutocompleteProvider {
         }));
         // Filtering above used the full slash-form `prefix` (context.prefix always
         // starts with '/' for a matched token), but the RETURNED prefix strips that
-        // leading '/' (review Major 3). pi-tui's `handleInput` (tui.select.confirm
+        // leading '/'. pi-tui's `handleInput` (tui.select.confirm
         // branch) falls through to `submitValue()` whenever `autocompletePrefix`
         // (set verbatim from this return value) starts with '/' — that's its own
         // leading-command-completion submit shortcut, and a non-leading ref

package/dist/clients/attach/input/titled-editor.d.ts

@@ -91,7 +91,7 @@ export declare class TitledEditor extends CustomEditor {
      *  The base `Editor` resolves newLine against `getKeybindings()` on ITS pi-tui
      *  instance, which in a non-deduped install is a DIFFERENT module than the one
      *  carrying crtr's `alt+enter` override — so the override can silently never
-     *  reach it and Alt+Enter falls through to submit (issue #11). crtr's `km` (the
+     *  reach it and Alt+Enter falls through to submit. crtr's `km` (the
      *  same manager CustomEditor matches `app.*` against) always carries the
      *  override, so matching the chord here makes the newline behavior independent
      *  of cross-instance keybinding mirroring. Skipped while the autocomplete popup
@@ -159,8 +159,8 @@ export declare class TitledEditor extends CustomEditor {
     paneFocused: boolean;
     /** Canonical names the broker currently resolves — the exact-membership set
      *  a candidate ref token must be in to render as a resolved highlight.
-     *  Empty by default (no decoration) until the caller (T3, out of scope for
-     *  this wave) supplies the broker-supplied inventory. */
+     *  Empty by default (no decoration) until the caller supplies the
+     *  broker-supplied inventory. */
     private resolvedRefNames;
     /** Command names the VIEWER dispatches ENTIRELY locally (never reach the
      *  engine as prose) — checked against the TRIMMED leading-name rule
@@ -169,15 +169,14 @@ export declare class TitledEditor extends CustomEditor {
      *  `locallyConsumedCommandNames()` from `slash/dispatch.ts` — independent
      *  of `remote` and of the broker's `get_commands` reply (see that
      *  function's doc comment). Deliberately NEVER the merged display/
-     *  completion list (review Major 6 — `slashCommandList` is a different,
-     *  remote-filtered, broker-augmented list, not a dispatch predicate). */
+     *  completion list (`slashCommandList` is a different, remote-filtered,
+     *  broker-augmented list, not a dispatch predicate). */
     private localCommandNames;
     /** Leading tokens the ENGINE (broker) independently consumes as a leading
      *  command/skill/template dispatch — the broker's own
-     *  `engineLeadingCommandNames` (design: inline memory references, review
-     *  Major 6), checked against the UNTRIMMED leading-name rule
-     *  (`matchesEngineLeadingCommand`, mirroring the broker's own
-     *  `isLeadingEngineCommand` — review Minor 10). Populated from each
+     *  `engineLeadingCommandNames`, checked against the UNTRIMMED leading-name
+     *  rule (`matchesEngineLeadingCommand`, mirroring the broker's own
+     *  `isLeadingEngineCommand`). Populated from each
      *  `list_memory_refs` reply, alongside `resolvedRefNames`. */
     private engineCommandNames;
     setResolvedRefNames(names: Iterable<string>): void;
@@ -192,12 +191,12 @@ export declare class TitledEditor extends CustomEditor {
      *  is simply left undecorated. Suppressed entirely (command-wide) whenever
      *  the composer's own leading token dispatches — as a LOCAL viewer command
      *  (`localCommandNames`, TRIMMED rule) or as an ENGINE-consumed leading
-     *  command/skill/template (`engineCommandNames`, UNTRIMMED rule, review
-     *  Minor 10) — the ref grammar and slash-dispatch's name charset differ, so
+     *  command/skill/template (`engineCommandNames`, UNTRIMMED rule) — the ref
+     *  grammar and slash-dispatch's name charset differ, so
      *  highlighting a ref inside a command that's about to dispatch would be
      *  misleading chrome for text the command, not memory resolution, is about
-     *  to consume. The two rules are kept deliberately SEPARATE (review Major
-     *  6) rather than collapsed into one set/predicate: they classify against
+     *  to consume. The two rules are kept deliberately SEPARATE rather than
+     *  collapsed into one set/predicate: they classify against
      *  different text (trimmed vs. raw) and different authorities (this
      *  viewer's own dispatch vs. the broker's). */
     private decorateResolvedRefs;

package/dist/clients/attach/input/titled-editor.js

@@ -401,7 +401,7 @@ function extractLeadingCommandName(text) {
     return m ? m[1] : null;
 }
 /** Mirrors the broker's `isLeadingEngineCommand` (`core/runtime/broker.ts`)
- *  leading-token rule EXACTLY for classification purposes (review Minor 10):
+ *  leading-token rule EXACTLY for classification purposes:
  *  the RAW, un-trimmed `text` must itself start with `/` — no `.trim()` — for
  *  ANY token to be a candidate, matching the broker's own untrimmed
  *  `text.startsWith('/')` checks byte-for-byte (space-based name split,
@@ -447,7 +447,7 @@ export class TitledEditor extends CustomEditor {
     constructor(tui, theme, keybindings, options) {
         super(tui, theme, keybindings, options);
         this.km = keybindings;
-        // Preserve raw (untrimmed) submit text end-to-end (review Major 4). The base
+        // Preserve raw (untrimmed) submit text end-to-end. The base
         // `Editor.submitValue()` — private in the `.d.ts` (blocking a normal TS
         // `override`), hence the structural cast, same pattern as the other private-
         // internals casts throughout this file (`scrollOffset`, `historyIndex`,
@@ -497,7 +497,7 @@ export class TitledEditor extends CustomEditor {
      *  The base `Editor` resolves newLine against `getKeybindings()` on ITS pi-tui
      *  instance, which in a non-deduped install is a DIFFERENT module than the one
      *  carrying crtr's `alt+enter` override — so the override can silently never
-     *  reach it and Alt+Enter falls through to submit (issue #11). crtr's `km` (the
+     *  reach it and Alt+Enter falls through to submit. crtr's `km` (the
      *  same manager CustomEditor matches `app.*` against) always carries the
      *  override, so matching the chord here makes the newline behavior independent
      *  of cross-instance keybinding mirroring. Skipped while the autocomplete popup
@@ -655,8 +655,8 @@ export class TitledEditor extends CustomEditor {
     paneFocused = true;
     /** Canonical names the broker currently resolves — the exact-membership set
      *  a candidate ref token must be in to render as a resolved highlight.
-     *  Empty by default (no decoration) until the caller (T3, out of scope for
-     *  this wave) supplies the broker-supplied inventory. */
+     *  Empty by default (no decoration) until the caller supplies the
+     *  broker-supplied inventory. */
     resolvedRefNames = new Set();
     /** Command names the VIEWER dispatches ENTIRELY locally (never reach the
      *  engine as prose) — checked against the TRIMMED leading-name rule
@@ -665,15 +665,14 @@ export class TitledEditor extends CustomEditor {
      *  `locallyConsumedCommandNames()` from `slash/dispatch.ts` — independent
      *  of `remote` and of the broker's `get_commands` reply (see that
      *  function's doc comment). Deliberately NEVER the merged display/
-     *  completion list (review Major 6 — `slashCommandList` is a different,
-     *  remote-filtered, broker-augmented list, not a dispatch predicate). */
+     *  completion list (`slashCommandList` is a different, remote-filtered,
+     *  broker-augmented list, not a dispatch predicate). */
     localCommandNames = new Set();
     /** Leading tokens the ENGINE (broker) independently consumes as a leading
      *  command/skill/template dispatch — the broker's own
-     *  `engineLeadingCommandNames` (design: inline memory references, review
-     *  Major 6), checked against the UNTRIMMED leading-name rule
-     *  (`matchesEngineLeadingCommand`, mirroring the broker's own
-     *  `isLeadingEngineCommand` — review Minor 10). Populated from each
+     *  `engineLeadingCommandNames`, checked against the UNTRIMMED leading-name
+     *  rule (`matchesEngineLeadingCommand`, mirroring the broker's own
+     *  `isLeadingEngineCommand`). Populated from each
      *  `list_memory_refs` reply, alongside `resolvedRefNames`. */
     engineCommandNames = new Set();
     setResolvedRefNames(names) {
@@ -694,12 +693,12 @@ export class TitledEditor extends CustomEditor {
      *  is simply left undecorated. Suppressed entirely (command-wide) whenever
      *  the composer's own leading token dispatches — as a LOCAL viewer command
      *  (`localCommandNames`, TRIMMED rule) or as an ENGINE-consumed leading
-     *  command/skill/template (`engineCommandNames`, UNTRIMMED rule, review
-     *  Minor 10) — the ref grammar and slash-dispatch's name charset differ, so
+     *  command/skill/template (`engineCommandNames`, UNTRIMMED rule) — the ref
+     *  grammar and slash-dispatch's name charset differ, so
      *  highlighting a ref inside a command that's about to dispatch would be
      *  misleading chrome for text the command, not memory resolution, is about
-     *  to consume. The two rules are kept deliberately SEPARATE (review Major
-     *  6) rather than collapsed into one set/predicate: they classify against
+     *  to consume. The two rules are kept deliberately SEPARATE rather than
+     *  collapsed into one set/predicate: they classify against
      *  different text (trimmed vs. raw) and different authorities (this
      *  viewer's own dispatch vs. the broker's). */
     decorateResolvedRefs(lines, width) {

package/dist/clients/attach/overlays/dialogs.d.ts

@@ -19,7 +19,7 @@ export declare function isBlockingDialog(req: RpcExtensionUIRequest): boolean;
  *   `keybindings.matches(key, "app.editor.external")` for the Ctrl+G external-editor
  *   shortcut. Defaults to a fresh `KeybindingsManager(TUI_KEYBINDINGS)` — that
  *   knows the base TUI bindings but not pi's app-level `app.editor.external`, so
- *   Ctrl+G is inert until the input controller (T6) passes the app keybindings
+ *   Ctrl+G is inert until the input controller passes the app keybindings
  *   manager. `ExtensionEditorComponent` is typed against pi's CORE
  *   KeybindingsManager (a subclass of pi-tui's), so we widen via the constructor's
  *   own parameter type rather than importing the core class (type-only export).

package/dist/clients/attach/overlays/dialogs.js

@@ -1,4 +1,4 @@
-// overlays/dialogs.ts — the blocking-dialog renderer for `crtr surface attach` (T5).
+// overlays/dialogs.ts — the blocking-dialog renderer for `crtr surface attach`.
 //
 // The broker forwards an extension's user-blocking UI request as an
 // `extension_ui_request` frame (RpcExtensionUIRequest). The viewer renders it
@@ -45,7 +45,7 @@ const OVERLAY_OPTIONS = { anchor: 'center', width: '70%', maxHeight: '80%' };
  *   `keybindings.matches(key, "app.editor.external")` for the Ctrl+G external-editor
  *   shortcut. Defaults to a fresh `KeybindingsManager(TUI_KEYBINDINGS)` — that
  *   knows the base TUI bindings but not pi's app-level `app.editor.external`, so
- *   Ctrl+G is inert until the input controller (T6) passes the app keybindings
+ *   Ctrl+G is inert until the input controller passes the app keybindings
  *   manager. `ExtensionEditorComponent` is typed against pi's CORE
  *   KeybindingsManager (a subclass of pi-tui's), so we widen via the constructor's
  *   own parameter type rather than importing the core class (type-only export).

package/dist/clients/attach/overlays/help.js

@@ -135,6 +135,7 @@ export class HelpOverlay {
             muted('mouse wheel (when reporting is on)'),
             blank,
             heading('Selection and copy'),
+            { text: 'Drag with the mouse to select; releasing copies the selection to the clipboard (and the tmux buffer). Any key clears the highlight.', style: 'plain' },
             { text: 'prefix + [  tmux copy-mode selects and copies the visible screenful; it works even while mouse reporting is on.', style: 'plain' },
             { text: 'Option-drag (iTerm2, Terminal.app) or Shift-drag (Ghostty, Alacritty, xterm) makes a true terminal selection that bypasses mouse reporting.', style: 'plain' },
             { text: 'Block-copy commands copy transcript content and are not capped at one screenful.', style: 'plain' },
@@ -146,7 +147,7 @@ export class HelpOverlay {
             { text: "/copy-transcript  every copyable block's text, oldest to newest, joined by blank lines.", style: 'plain' },
             blank,
             heading('Mouse'),
-            { text: `/mouse or ${this.binding('crtr.attach.mouse.toggle')}  toggle mouse wheel scrolling. Turning it off restores tmux drag-select and copy-mode mouse.`, style: 'plain' },
+            { text: `/mouse or ${this.binding('crtr.attach.mouse.toggle')}  toggle mouse reporting — wheel scrolling and viewer drag-select. Turning it off restores tmux drag-select and copy-mode mouse.`, style: 'plain' },
             blank,
             heading('Other attach keys'),
             ...otherKeys,

package/dist/clients/attach/overlays/mcp.js

@@ -40,12 +40,13 @@
 // installed adapter (pi-mcp-adapter index.ts: "auth-start" / "auth-complete" /
 // "ui-messages"; `connect: <name>`).
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { piAgentDir } from '../../../core/runtime/package-health.js';
 import { SelectList, visibleWidth } from '@earendil-works/pi-tui';
 import { getSelectListTheme } from '@earendil-works/pi-coding-agent';
+import { readJsonOrNull } from '../../../core/fs-utils.js';
 /** Adapter metadata-cache.ts CACHE_MAX_AGE_MS — entries older than this are misses. */
 const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 /** The adapter's import-source table (pi-mcp-adapter config.ts IMPORT_PATHS).
@@ -72,14 +73,6 @@ function importPathCandidates(kind, home) {
             return [];
     }
 }
-function readJson(path) {
-    try {
-        return JSON.parse(readFileSync(path, 'utf-8'));
-    }
-    catch {
-        return null; // missing or corrupt → empty state, never a crash
-    }
-}
 /** Mirror of the adapter's validateConfig (config.ts): a source file's own
  *  servers may live under `mcpServers` OR the `mcp-servers` alias — but a
  *  non-object value invalidates the WHOLE file, dropping its `imports` too. */
@@ -130,7 +123,7 @@ function mergeServerMaps(base, next) {
 /** Read one config file: its own servers layered OVER any `imports` servers
  *  (first import wins per name, own config wins overall — adapter expandImports). */
 function readConfigSource(path, cwd, home) {
-    const raw = readJson(path);
+    const raw = readJsonOrNull(path);
     if (raw === null)
         return {};
     const { servers: own, imports } = validateConfigSource(raw);
@@ -144,7 +137,7 @@ function readConfigSource(path, cwd, home) {
             .find((candidate) => existsSync(candidate));
         if (full === undefined)
             continue;
-        const importedRaw = readJson(full);
+        const importedRaw = readJsonOrNull(full);
         if (importedRaw === null)
             continue;
         for (const [name, spec] of Object.entries(extractImportedServers(importedRaw, kind))) {
@@ -228,7 +221,7 @@ export function readMcpServers(home = homedir(), cwd = process.cwd()) {
     for (const path of sourcePaths) {
         servers = mergeServerMaps(servers, readConfigSource(path, cwd, home));
     }
-    const cache = readJson(join(agentDir, 'mcp-cache.json'));
+    const cache = readJsonOrNull(join(agentDir, 'mcp-cache.json'));
     return Object.entries(servers).map(([name, spec]) => {
         const transport = spec.type ?? (spec.url !== undefined ? 'http' : 'stdio');
         const target = spec.url ?? [spec.command, ...(spec.args ?? [])].filter(Boolean).join(' ');

package/dist/clients/attach/render/chat-view.d.ts

@@ -35,7 +35,7 @@ export interface ChatViewOptions {
     toolOutputExpanded?: boolean;
     /** Sink for footer/header-only events ChatView does not itself render
      *  (queue_update, session_info_changed, thinking_level_changed). The attach
-     *  command (T7) wires a footer here; absent → these events are no-ops. */
+     *  command wires a footer here; absent → these events are no-ops. */
     onFooterEvent?: (event: AgentSessionEvent) => void;
     /** Theme palette for the activity spinner / dim status / error lines. Absent →
      *  the module defaults (faint + ANSI red) are used. */

package/dist/clients/attach/render/chat-view.js

@@ -1,4 +1,4 @@
-// render/chat-view.ts — the render half of `crtr surface attach` (Phase 4, T5).
+// render/chat-view.ts — the render half of `crtr surface attach`.
 //
 // A direct port of pi's `InteractiveMode.handleEvent()`
 // (interactive-mode.js:2169-2462) + its rebuild path
@@ -11,7 +11,7 @@
 // Its activity state (working spinner, compaction/retry indicators) is signaled
 // to the viewer-owned fixed slot when one is supplied. It does NOT own the
 // editor, the footer, or the terminal title — those are chrome laid out by the
-// attach command (T7). Events that only affect that chrome
+// attach command. Events that only affect that chrome
 // (queue_update / session_info_changed / thinking_level_changed) are forwarded
 // to the optional `onFooterEvent` sink instead of rendered here.
 //