@aragon-agent/cli 0.6.26 → 0.6.28

package/dist/proc/terminal-plan.js

@@ -50,8 +50,21 @@ const POSIX_CANDIDATES = Object.freeze([
 ]);
 /** The env var that overrides the shell the new window runs (D-7). */
 export const ARAGON_BRANCH_SHELL_ENV = 'ARAGON_BRANCH_SHELL';
-/** `PowerShell` and `cmd` both stop being reliable far below the 32767 OS limit. */
-const BARE_POWER_SHELL_WORD_RE = /^[A-Za-z0-9._\\/:+=@-]+$/;
+/**
+ * A bare word is one PowerShell will not read as anything else.
+ *
+ * THE FIRST CHARACTER IS THE LOAD-BEARING PART (D-3). `@name` in argument position
+ * is the SPLAT operator: `& node.exe -p 'process.argv.length' @foo` hands node an
+ * EMPTY argument list, exits 0 and prints nothing (measured on Windows PowerShell
+ * 5.1, branch-terminal-powershell-fix appendix B-11). As the only word on the line
+ * it is not even parseable - `error col=1 id=SplattingNotPermitted`. Nothing after
+ * the first character can do that, which is why the class differs in the first
+ * position. `-` stays allowed there so that every flag this feature emits
+ * (`--resume`) keeps its bare form, and quoting it would change nothing except the
+ * look of the fallback line (appendix B-6 A/B, quoting is transparent to a native
+ * exe).
+ */
+const BARE_POWER_SHELL_WORD_RE = /^[A-Za-z0-9._\\/:+=\-][A-Za-z0-9._\\/:+=@\-]*$/;
 /**
  * Build the ladder for this platform, most-preferred rung first.
  *
@@ -201,9 +214,29 @@ function resolveCandidate(candidate, env) {
 function posixWindowScript(cwd, shell, command) {
     return `cd ${posixQuote(cwd)} && ${posixScript(command)} ; exec ${posixQuote(shell.path)} -i`;
 }
-/** PowerShell: the whole command as one base64(UTF-16LE) blob (D-20). */
+/**
+ * The PowerShell statement that runs the aragon command (D-1).
+ *
+ * THE LEADING `&` IS NOT DECORATION. In command position PowerShell reads a quoted
+ * string as an EXPRESSION, so `'C:\Program Files\nodejs\node.exe' <script>` is a
+ * parse error - "unexpected token ..." at column 36 - and the child is never
+ * created, while the parent still believes the window opened (K-1: `wt`/`start`
+ * forward and exit). That is exactly the report this branch exists to fix.
+ * `&` is the call operator: it takes the following word as a command name whatever
+ * its shape, and it does not change name resolution (`& 'npm.cmd'` still finds
+ * `npm` through PATH/PATHEXT, appendix B-8).
+ *
+ * `posixScript` MUST NOT be given the same treatment: in sh `&` means run in the
+ * background, so the window would reach the trailing `exec <shell> -i` immediately
+ * and the branch would start behind a prompt that looks idle (I-3 / K-1).
+ */
 export function powerShellScript(parts) {
-    return parts.map(powerShellQuote).join(' ');
+    // TOTAL, NOT THROWING (D-4): an empty argv cannot arise from
+    // `resolveAragonCommand` (T-3 pins that), and an empty script is a parse-valid
+    // no-op rather than a throw inside a key handler.
+    if (parts.length === 0)
+        return '';
+    return ['&', ...parts.map(powerShellQuote)].join(' ');
 }
 /** Bare words stay bare; everything else becomes a single-quoted literal. */
 export function powerShellQuote(value) {

package/dist/session/branch-invocation.d.ts

@@ -3,7 +3,7 @@
  *
  * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
  *
- * THIS MODULE HAS NO IO ON PURPOSE. It answers two questions and nothing else:
+ * THIS MODULE PRODUCES NO IO ITSELF. It answers two questions and nothing else:
  * "which argv pieces make up the aragon command" and "how does that sentence read
  * when printed to a human". Spawning lives in `session/branch-launch.ts`, and the
  * terminal ladder lives in `proc/terminal-plan.ts`, so the one part of this
@@ -12,6 +12,14 @@
  * `proc/readiness.ts` and `proc/classify.ts` are pure, `proc/supervisor.ts` is the
  * part that touches processes.
  *
+ * IT DOES IMPORT `proc/terminal-plan.ts` (D-5), and that is still the right
+ * direction: `session -> proc`. The manual line needs both quoting dialects, and
+ * the dialect owner is `proc/terminal-plan.ts`; putting it in `proc/` would mean
+ * `proc/` importing `session/`, which is the cycle the header above forbids.
+ * What that import brings with it is one `statSync` probe used by the PATH lookup -
+ * not a process, not a write - so "no IO on purpose" still describes this module's
+ * own behaviour.
+ *
  * NAMED `branch-invocation`, NOT `branch-command` (R-22): `commands/branch-command.ts`
  * is the command body, and two files with one basename make every import, stack
  * trace and grep ambiguous. What this module exports is an *invocation*.
@@ -28,7 +36,15 @@ export interface AragonCommandResolution {
 export interface BranchInvocation {
     /** `[...aragon.parts, '--resume', id]`. */
     parts: string[];
-    /** One line, pasteable into cmd / PowerShell / sh (quoted where needed). */
+    /**
+     * One line, for the toast and the log.
+     *
+     * NOT THE PASTEABLE FORM ON WIN32 - and the defect that produced this comment is
+     * the proof: a double-quoted command word is a string EXPRESSION to PowerShell, so
+     * pasting this line into the shell Windows Terminal opens by default yields the
+     * same `ParserError` the new window used to. `renderManualCommand(parts,
+     * platform)` is the paste-ready form; on win32 it is two labelled lines.
+     */
     command: string;
 }
 export declare const BRANCH_RESUME_FLAG = "--resume";
@@ -54,21 +70,49 @@ export declare function resolveAragonCommand(input: {
     execPath: string;
     env: Record<string, string | undefined>;
 }): AragonCommandResolution;
-/** `parts` + `--resume <id>`, plus the one-line form for toasts and manual fallback. */
+/**
+ * `parts` + `--resume <id>`, plus the ONE-LINE form for the toast and the log.
+ *
+ * The paste-ready form is NOT this field (see `BranchInvocation.command` and
+ * `renderManualCommand`): "one line for every shell" was the claim this branch
+ * disproved, and leaving it here would keep the next reader believing it.
+ */
 export declare function buildResumeInvocation(input: {
     id: string;
     aragon: AragonCommandResolution;
 }): BranchInvocation;
 /**
- * Join argv pieces into one line a human can paste into any of the three shells.
+ * Join argv pieces into one line a human can read at a glance.
  *
- * NOT A SHELL ESCAPER. This text goes to the toast, to the notice and to the
- * README, never back through a parser: the three platforms agree on what double
- * quotes mean around a path with spaces, and that is the whole requirement. The
- * real command lines are built by `proc/terminal-plan.ts`, which quotes for the
- * exact parser each rung lands in.
+ * NOT A SHELL ESCAPER, and no longer claimed to be a universal paste line: it is
+ * the RIGHT line for `cmd.exe` and for POSIX shells, and the WRONG one for
+ * PowerShell on win32 (a double-quoted command word is an expression there). Its
+ * product is what a POSIX/darwin user pastes, and what the `cmd.exe` half of the
+ * win32 manual block shows; the PowerShell half comes from `powerShellScript` via
+ * `renderManualCommand`. The real command lines are built by
+ * `proc/terminal-plan.ts`, which quotes for the exact parser each rung lands in.
  */
 export declare function joinCommandLine(parts: readonly string[]): string;
+/**
+ * The paste-ready form of the command, per platform (D-5 / D-6 / I-4).
+ *
+ * ONE LINE CANNOT BE CORRECT FOR BOTH WINDOWS PARSERS. A double-quoted command word
+ * is a string EXPRESSION to PowerShell (the defect this branch fixes) while it is
+ * exactly right for `cmd.exe`; `& 'x'` is right for PowerShell and wrong for
+ * `cmd.exe` (which keeps the single quotes and tries to run `'x'`). So Windows gets
+ * two labelled lines and the user copies the one matching the terminal they opened;
+ * POSIX and macOS keep the single line they have always printed.
+ *
+ * The first line is `powerShellScript(parts)` VERBATIM, which is what makes I-1
+ * ("one command, one artefact") testable: the fallback the user pastes is the same
+ * text the new window receives in its `-EncodedCommand` payload.
+ *
+ * @param parts argv pieces of the aragon invocation, `--resume <id>` included.
+ * @param platform the platform whose parsers the two lines have to satisfy.
+ * @returns one line off Windows; two ASCII lines labelled `PowerShell:` and
+ *   `cmd.exe   :` on win32. Both labels are 11 columns wide on purpose.
+ */
+export declare function renderManualCommand(parts: readonly string[], platform: NodeJS.Platform): string;
 /**
  * The second gate on D-9: an id is about to be concatenated into a command line.
  *

package/dist/session/branch-invocation.js

@@ -3,7 +3,7 @@
  *
  * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
  *
- * THIS MODULE HAS NO IO ON PURPOSE. It answers two questions and nothing else:
+ * THIS MODULE PRODUCES NO IO ITSELF. It answers two questions and nothing else:
  * "which argv pieces make up the aragon command" and "how does that sentence read
  * when printed to a human". Spawning lives in `session/branch-launch.ts`, and the
  * terminal ladder lives in `proc/terminal-plan.ts`, so the one part of this
@@ -12,11 +12,20 @@
  * `proc/readiness.ts` and `proc/classify.ts` are pure, `proc/supervisor.ts` is the
  * part that touches processes.
  *
+ * IT DOES IMPORT `proc/terminal-plan.ts` (D-5), and that is still the right
+ * direction: `session -> proc`. The manual line needs both quoting dialects, and
+ * the dialect owner is `proc/terminal-plan.ts`; putting it in `proc/` would mean
+ * `proc/` importing `session/`, which is the cycle the header above forbids.
+ * What that import brings with it is one `statSync` probe used by the PATH lookup -
+ * not a process, not a write - so "no IO on purpose" still describes this module's
+ * own behaviour.
+ *
  * NAMED `branch-invocation`, NOT `branch-command` (R-22): `commands/branch-command.ts`
  * is the command body, and two files with one basename make every import, stack
  * trace and grep ambiguous. What this module exports is an *invocation*.
  */
 import { isAbsolute } from 'node:path';
+import { powerShellScript } from '../proc/terminal-plan.js';
 import { isValidSessionId } from './store.js';
 export const BRANCH_RESUME_FLAG = '--resume';
 /** The env var that overrides "what executable the new window runs" (D-7 sibling). */
@@ -65,23 +74,58 @@ export function resolveAragonCommand(input) {
     }
     return { parts: ['aragon'], kind: 'bin', origin: 'aragon on PATH' };
 }
-/** `parts` + `--resume <id>`, plus the one-line form for toasts and manual fallback. */
+/**
+ * `parts` + `--resume <id>`, plus the ONE-LINE form for the toast and the log.
+ *
+ * The paste-ready form is NOT this field (see `BranchInvocation.command` and
+ * `renderManualCommand`): "one line for every shell" was the claim this branch
+ * disproved, and leaving it here would keep the next reader believing it.
+ */
 export function buildResumeInvocation(input) {
     const parts = [...input.aragon.parts, BRANCH_RESUME_FLAG, input.id];
     return { parts, command: joinCommandLine(parts) };
 }
 /**
- * Join argv pieces into one line a human can paste into any of the three shells.
+ * Join argv pieces into one line a human can read at a glance.
  *
- * NOT A SHELL ESCAPER. This text goes to the toast, to the notice and to the
- * README, never back through a parser: the three platforms agree on what double
- * quotes mean around a path with spaces, and that is the whole requirement. The
- * real command lines are built by `proc/terminal-plan.ts`, which quotes for the
- * exact parser each rung lands in.
+ * NOT A SHELL ESCAPER, and no longer claimed to be a universal paste line: it is
+ * the RIGHT line for `cmd.exe` and for POSIX shells, and the WRONG one for
+ * PowerShell on win32 (a double-quoted command word is an expression there). Its
+ * product is what a POSIX/darwin user pastes, and what the `cmd.exe` half of the
+ * win32 manual block shows; the PowerShell half comes from `powerShellScript` via
+ * `renderManualCommand`. The real command lines are built by
+ * `proc/terminal-plan.ts`, which quotes for the exact parser each rung lands in.
  */
 export function joinCommandLine(parts) {
     return parts.map(quoteForDisplay).join(' ');
 }
+/**
+ * The paste-ready form of the command, per platform (D-5 / D-6 / I-4).
+ *
+ * ONE LINE CANNOT BE CORRECT FOR BOTH WINDOWS PARSERS. A double-quoted command word
+ * is a string EXPRESSION to PowerShell (the defect this branch fixes) while it is
+ * exactly right for `cmd.exe`; `& 'x'` is right for PowerShell and wrong for
+ * `cmd.exe` (which keeps the single quotes and tries to run `'x'`). So Windows gets
+ * two labelled lines and the user copies the one matching the terminal they opened;
+ * POSIX and macOS keep the single line they have always printed.
+ *
+ * The first line is `powerShellScript(parts)` VERBATIM, which is what makes I-1
+ * ("one command, one artefact") testable: the fallback the user pastes is the same
+ * text the new window receives in its `-EncodedCommand` payload.
+ *
+ * @param parts argv pieces of the aragon invocation, `--resume <id>` included.
+ * @param platform the platform whose parsers the two lines have to satisfy.
+ * @returns one line off Windows; two ASCII lines labelled `PowerShell:` and
+ *   `cmd.exe   :` on win32. Both labels are 11 columns wide on purpose.
+ */
+export function renderManualCommand(parts, platform) {
+    if (platform !== 'win32')
+        return joinCommandLine(parts);
+    return [
+        `PowerShell: ${powerShellScript(parts)}`,
+        `cmd.exe   : ${joinCommandLine(parts)}`,
+    ].join('\n');
+}
 /** Empty and whitespace-or-quote-bearing pieces get double quotes; the rest stay bare. */
 function quoteForDisplay(part) {
     if (part.length === 0)

package/dist/session/branch-launch.d.ts

@@ -29,6 +29,15 @@ export interface BranchRequest {
 }
 export type BranchOpenResult = {
     ok: true;
+    /**
+     * The paste-ready command block for this platform (D-7).
+     *
+     * "Always present, so no failure is a dead end" is I-4 for the FAILURE arm;
+     * the success arm carries it for the mirror-image reason - "what did the
+     * window I just opened actually run" is copyable without retyping it from the
+     * toast. Same meaning as the field of the same name below: on win32 it is the
+     * two-line PowerShell / `cmd.exe` block, off win32 it is one line.
+     */
     command: string;
     shell: string;
     rung: string;

package/dist/session/branch-launch.js

@@ -22,7 +22,7 @@ import { spawn } from 'node:child_process';
 import { getLogger } from '../logging/logger.js';
 import { defaultIsExecutable, pathDirsOf, planTerminalLaunch, resolveShell, truncateTitle, } from '../proc/terminal-plan.js';
 import { BRANCH_COPY } from '../commands/branch-command.js';
-import { buildResumeInvocation, joinCommandLine, resolveAragonCommand, validateBranchId, } from './branch-invocation.js';
+import { buildResumeInvocation, renderManualCommand, resolveAragonCommand, validateBranchId, } from './branch-invocation.js';
 import { BRANCH_TERMINAL_LIMITS } from './limits.js';
 /**
  * Build the port. The only mutable state is this closure's four values, none of
@@ -41,12 +41,16 @@ export function createBranchLauncher(deps) {
     let cachedAragon = null;
     let cachedShell = null;
     /**
-     * Resolve WHAT the new window runs, and the command line built from it.
+     * Resolve WHAT the new window runs, and the two command forms built from it.
      *
      * The resolution is cached for the process (R-13 / K-14). It costs no
      * filesystem probe - the three rules are env, `argv[1]` and a literal - so the
      * cache is about identity, not speed: the value that opened the first window is
      * the value the log keeps reporting.
+     *
+     * `manual` is derived HERE from the same `parts` on purpose (D-7): one source of
+     * truth for the command means the paste block and the `-EncodedCommand` payload
+     * cannot drift apart (I-1).
      */
     function planFor(id) {
         cachedAragon ??= resolveAragonCommand({
@@ -54,9 +58,11 @@ export function createBranchLauncher(deps) {
             execPath: deps.execPath,
             env: deps.env,
         });
+        const invocation = buildResumeInvocation({ id, aragon: cachedAragon });
         return {
             aragon: cachedAragon,
-            invocation: buildResumeInvocation({ id, aragon: cachedAragon }),
+            invocation,
+            manual: renderManualCommand(invocation.parts, deps.platform),
         };
     }
     function shellFor() {
@@ -93,22 +99,25 @@ export function createBranchLauncher(deps) {
         return cooldown(command, Math.max(1, windowMs - waited));
     }
     async function openOnce(request) {
-        const { aragon, invocation } = planFor(request.id);
+        const { aragon, invocation, manual } = planFor(request.id);
         const command = invocation.command;
         // 4.5 BEFORE ANY SPAWN (R-7 / T-46): a command line that `cmd` or AppleScript
         // would truncate is worse than no command line, because the window opens and
-        // then fails in a way this process cannot see.
+        // then fails in a way this process cannot see. The MEASURED object stays the
+        // single unquoted line: it is the lower bound of every dialect (quoting only
+        // ever adds characters), so the check is conservative and needs no second
+        // source of truth.
         if (command.length > BRANCH_TERMINAL_LIMITS.maxCommandLineCells) {
             // A COMPLETE SENTENCE WITH THE FALLBACK INSIDE IT (I-4 / appendix A): the
             // over-long case is the one failure where the user most needs a command to
             // paste, so it may not report the bare reason "command line too long" - that
             // is an internal code, not an answer, and it would leave a dead end.
-            return failure('spawn-failed', BRANCH_COPY.spawnFailed('command line too long', command), command);
+            return failure('spawn-failed', BRANCH_COPY.spawnFailed('command line too long', manual), manual);
         }
         // D-9's second gate: an id is about to enter a command line.
         const invalid = validateBranchId(request.id);
         if (invalid !== null)
-            return failure('spawn-failed', invalid, command);
+            return failure('spawn-failed', invalid, manual);
         // Step 6: flush FIRST, spawn only on `ok` (I-1). `force` skips the fingerprint
         // short circuit and nothing else (D-15 / I-7).
         const flushed = deps.checkpoint({ force: true });
@@ -118,7 +127,10 @@ export function createBranchLauncher(deps) {
             // disk problem, so it must not be printed as "could not checkpoint
             // (no-identity)" - that reads like corruption. It gets `/session`'s sentence.
             const message = reason === 'no-identity' ? BRANCH_COPY.noIdentity : BRANCH_COPY.checkpointFailed(reason);
-            return failure('checkpoint-failed', message, command);
+            // The THIRD argument changes, never the sentence (parent-R-19): these two
+            // failures deliberately do NOT embed the command, because their job is to
+            // explain why nothing opened. The command still travels in `result.command`.
+            return failure('checkpoint-failed', message, manual);
         }
         const shell = shellFor();
         // Step 7: the TITLE is what gets truncated, never the id in the command line (T-47).
@@ -132,11 +144,13 @@ export function createBranchLauncher(deps) {
             command: invocation.parts,
             title,
             cwd: request.cwd,
-            manual: joinCommandLine(invocation.parts),
+            // The paste block the fallback prints, built by the same dialect owner that
+            // encodes the window script (I-1: one command, one artefact).
+            manual,
         });
         if (!planned.ok) {
             // Not cached: the next press must be allowed to find a terminal that appeared.
-            return failure('no-launcher', BRANCH_COPY.noLauncher(planned.manual), command);
+            return failure('no-launcher', BRANCH_COPY.noLauncher(planned.manual), manual);
         }
         // Step 8: walk the ladder, bounded by maxRungs (T-33).
         const rungs = planned.plans.slice(0, BRANCH_TERMINAL_LIMITS.maxRungs);
@@ -156,14 +170,14 @@ export function createBranchLauncher(deps) {
                     aragon: aragon.kind,
                     origin: aragon.origin,
                 });
-                return { ok: true, command, shell: planned.shell.path, rung: plan.rung };
+                return { ok: true, command: manual, shell: planned.shell.path, rung: plan.rung };
             }
             logger.warn('rung_failed', { rung: plan.rung, message: outcome.message });
             lastError = outcome;
         }
         // Step 9: every rung failed. `wt`'s own semantic failures land here too only if
         // the error event fired; a forwarded-but-rejected `wt` invocation does not (K-1).
-        return failure('spawn-failed', BRANCH_COPY.spawnFailed(lastError?.message ?? 'no rung available', command), command);
+        return failure('spawn-failed', BRANCH_COPY.spawnFailed(lastError?.message ?? 'no rung available', manual), manual);
     }
     /**
      * One rung, with EXACTLY ONE `'error'` LISTENER THAT IS NEVER REMOVED (R-3 / I-10).
@@ -230,7 +244,10 @@ export function createBranchLauncher(deps) {
     }
     return {
         async open(request) {
-            const blocked = gated(planFor(request.id).invocation.command);
+            // The cooldown path carries the same paste block. It never displays it, but the
+            // result type has exactly one meaning for `command` and inventing a second one
+            // for this arm is how the two forms would drift apart (D-7).
+            const blocked = gated(planFor(request.id).manual);
             if (blocked !== null)
                 return blocked;
             inFlight = true;

package/dist/tools/terminal-output.d.ts

@@ -65,6 +65,14 @@ export interface SanitizeResult {
 /**
  * Remove every escape sequence and control byte except `\t` `\n` `\r`.
  *
+ * SEQUENCE SYNTAX HAS ONE OWNER (`input/control-sequences.ts`); this function
+ * adds only the control-byte sweep a DISPLAY row wants. Both call sites in this
+ * module already cut an unfinished escape off into the carry before calling it
+ * (`partialEscapeStart`), so the shared one-shot rule for a truncated sequence
+ * is exactly what they need -- and it fixes AC-24's failure in place: the old
+ * two-byte rule consumed the `\x1b[` of an unfinished CSI and left the
+ * PARAMETERS behind, so `\x1b[31m` split across chunks rendered as `red 3`.
+ *
  * Exported for the tests, and used by `toDisplayRow` as the second line of
  * defence over a carry that ends mid-escape.
  */

package/dist/tools/terminal-output.js

@@ -22,6 +22,7 @@
  * interpreting cursor motion would mean owning a screen buffer. Neither is a
  * presentation round's job.
  */
+import { stripControlSequences } from '../input/control-sequences.js';
 /** Columns a live row may occupy before it is clipped. */
 export const LIVE_ROW_MAX_CHARS = 200;
 /** Tab stop width, matching every terminal's default. */
@@ -57,22 +58,24 @@ export const TRUNCATION_MARK = '...';
  * and holding it forever would pin the carry.
  */
 const MAX_PARTIAL_ESCAPE = 64;
-/** CSI: `\x1b[` params intermediates final. */
-const CSI = /\x1b\[[0-?]*[ -/]*[@-~]/g;
-/** OSC: `\x1b]` ... terminated by BEL or ST. */
-const OSC = /\x1b\][\s\S]*?(?:\x07|\x1b\\)/g;
-/** The two-byte forms: `\x1b` followed by one character. */
-const ESC_PAIR = /\x1b[\s\S]/g;
 /** C1, plus every C0 control except `\t` `\n` `\r`. */
 const CONTROLS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
 /**
  * Remove every escape sequence and control byte except `\t` `\n` `\r`.
  *
+ * SEQUENCE SYNTAX HAS ONE OWNER (`input/control-sequences.ts`); this function
+ * adds only the control-byte sweep a DISPLAY row wants. Both call sites in this
+ * module already cut an unfinished escape off into the carry before calling it
+ * (`partialEscapeStart`), so the shared one-shot rule for a truncated sequence
+ * is exactly what they need -- and it fixes AC-24's failure in place: the old
+ * two-byte rule consumed the `\x1b[` of an unfinished CSI and left the
+ * PARAMETERS behind, so `\x1b[31m` split across chunks rendered as `red 3`.
+ *
  * Exported for the tests, and used by `toDisplayRow` as the second line of
  * defence over a carry that ends mid-escape.
  */
 export function stripAnsi(text) {
-    return text.replace(CSI, '').replace(OSC, '').replace(ESC_PAIR, '').replace(CONTROLS, '');
+    return stripControlSequences(text).replace(CONTROLS, '');
 }
 /**
  * Index at which a trailing INCOMPLETE escape begins, or `-1`.

package/dist/ui/display-tab.d.ts

@@ -0,0 +1,51 @@
+/**
+ * TAB expansion that agrees with the TERMINAL, not with UTF-16 (fix A'-2 of
+ * paste-control-sequence-residue).
+ *
+ * WHY THIS IS A MODULE OF ITS OWN. A TAB has no width; it advances the pen to
+ * the next tab stop, so what it occupies depends on where the line currently
+ * is. That makes "one TAB" a property of a CURSOR, and the same character was
+ * being read three different ways in this package:
+ *
+ * - `ui/editor-navigation.ts` painted it at FOUR-column stops in the composer,
+ * - `entries/UserEntry.tsx` handed the raw byte to `<Text>`, so the terminal
+ *   painted it at EIGHT-column stops in the transcript,
+ * - `tools/terminal-output.ts` expanded it by UTF-16 code-unit count, so a
+ *   pasted `中文<TAB>X` table came out two columns short.
+ *
+ * A user who pastes a TAB-indented block or an Excel/Word table therefore saw
+ * the draft and the sent message disagree about their own text. One function,
+ * used by the composer AND by every renderer of stored text, is what makes the
+ * "before send" and "after send" rows character-identical.
+ *
+ * `input/` is the wrong home for it: `cli/input` may depend on `node:stream`
+ * and nothing else (`.claude-index/index.md`), and column arithmetic needs the
+ * width table. `ui/` already owns that (`selection/selection.ts` uses
+ * `string-width` for exactly this reason).
+ *
+ * Pure, React-free, Ink-free.
+ */
+/**
+ * Tab stop width, matching every terminal's default.
+ *
+ * A COPY OF `tools/terminal-output.ts`'s number, on purpose and in the same
+ * shape `composer-limits.ts` copies `budget.ts::HINT_MIN_ROWS`: importing the
+ * tools module here would point an arrow from `ui/` into `tools/` for one
+ * integer, and the two are asserted equal by a test instead. (`tools/` keeps
+ * its own expander because its rows are clipped to 200 columns before anyone
+ * looks at them, so a code-unit approximation there cannot reach a user.)
+ */
+export declare const TAB_WIDTH = 8;
+/**
+ * Expand every TAB in `text` to spaces up to the next `TAB_WIDTH` stop, given
+ * the display column the first character will be painted at.
+ *
+ * `fromColumn` is a DISPLAY column, not an offset: a caller that has already
+ * painted `中文` must pass 4. Lines are independent -- a `\n` resets the column
+ * to zero, because the terminal's pen returns to column 0.
+ *
+ * Non-ASCII text is measured with `string-width`, which is the whole point: a
+ * CJK glyph occupies two cells, and counting it as one space is what left
+ * CJK-plus-TAB tables misaligned.
+ */
+export declare function expandTabs(text: string, fromColumn?: number): string;

package/dist/ui/display-tab.js

@@ -0,0 +1,82 @@
+/**
+ * TAB expansion that agrees with the TERMINAL, not with UTF-16 (fix A'-2 of
+ * paste-control-sequence-residue).
+ *
+ * WHY THIS IS A MODULE OF ITS OWN. A TAB has no width; it advances the pen to
+ * the next tab stop, so what it occupies depends on where the line currently
+ * is. That makes "one TAB" a property of a CURSOR, and the same character was
+ * being read three different ways in this package:
+ *
+ * - `ui/editor-navigation.ts` painted it at FOUR-column stops in the composer,
+ * - `entries/UserEntry.tsx` handed the raw byte to `<Text>`, so the terminal
+ *   painted it at EIGHT-column stops in the transcript,
+ * - `tools/terminal-output.ts` expanded it by UTF-16 code-unit count, so a
+ *   pasted `中文<TAB>X` table came out two columns short.
+ *
+ * A user who pastes a TAB-indented block or an Excel/Word table therefore saw
+ * the draft and the sent message disagree about their own text. One function,
+ * used by the composer AND by every renderer of stored text, is what makes the
+ * "before send" and "after send" rows character-identical.
+ *
+ * `input/` is the wrong home for it: `cli/input` may depend on `node:stream`
+ * and nothing else (`.claude-index/index.md`), and column arithmetic needs the
+ * width table. `ui/` already owns that (`selection/selection.ts` uses
+ * `string-width` for exactly this reason).
+ *
+ * Pure, React-free, Ink-free.
+ */
+import stringWidth from 'string-width';
+/**
+ * Tab stop width, matching every terminal's default.
+ *
+ * A COPY OF `tools/terminal-output.ts`'s number, on purpose and in the same
+ * shape `composer-limits.ts` copies `budget.ts::HINT_MIN_ROWS`: importing the
+ * tools module here would point an arrow from `ui/` into `tools/` for one
+ * integer, and the two are asserted equal by a test instead. (`tools/` keeps
+ * its own expander because its rows are clipped to 200 columns before anyone
+ * looks at them, so a code-unit approximation there cannot reach a user.)
+ */
+export const TAB_WIDTH = 8;
+/**
+ * Expand every TAB in `text` to spaces up to the next `TAB_WIDTH` stop, given
+ * the display column the first character will be painted at.
+ *
+ * `fromColumn` is a DISPLAY column, not an offset: a caller that has already
+ * painted `中文` must pass 4. Lines are independent -- a `\n` resets the column
+ * to zero, because the terminal's pen returns to column 0.
+ *
+ * Non-ASCII text is measured with `string-width`, which is the whole point: a
+ * CJK glyph occupies two cells, and counting it as one space is what left
+ * CJK-plus-TAB tables misaligned.
+ */
+export function expandTabs(text, fromColumn = 0) {
+    if (text.indexOf('\t') === -1)
+        return text;
+    let out = '';
+    let column = Math.max(0, Math.floor(fromColumn));
+    let run = '';
+    for (const part of graphemesOf(text)) {
+        if (part === '\t') {
+            out += run;
+            run = '';
+            const width = TAB_WIDTH - (column % TAB_WIDTH);
+            out += ' '.repeat(width);
+            column += width;
+            continue;
+        }
+        run += part;
+        if (part === '\n')
+            column = 0;
+        else
+            column += stringWidth(part);
+    }
+    return out + run;
+}
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+/**
+ * Grapheme clusters rather than code units, so a combining mark or an emoji ZWJ
+ * sequence advances the column once, exactly as the terminal draws it.
+ */
+function graphemesOf(text) {
+    return Array.from(segmenter.segment(text), ({ segment }) => segment);
+}

package/dist/ui/editor-navigation.d.ts

@@ -25,7 +25,17 @@ export interface EditorVisualMap {
     readonly positions: VisualPosition[];
     readonly cursor: VisualPosition;
 }
-/** Map graphemes to hard-wrapped rows, sharing tab stops and caret reservation. */
+/**
+ * Map graphemes to hard-wrapped rows, sharing tab stops and caret reservation.
+ *
+ * THE TAB STOP IS THE TERMINAL'S (`TAB_WIDTH`), NOT AN EDITOR-SIZED FOUR. It
+ * used to be four, while the transcript handed the raw `\t` to `<Text>` and
+ * the terminal painted it at eight: the same pasted table sat one column off
+ * from itself before and after sending. A tab that would cross the right edge
+ * is still clipped to the row (the caret cannot point past the last cell), so
+ * a tab STRADDLING the wrap is the one shape where the draft and the stored
+ * text can differ by the remainder of the advance.
+ */
 export declare function buildEditorVisualMap(input: {
     buffer: string;
     cols: number;

package/dist/ui/editor-navigation.js

@@ -1,5 +1,6 @@
 /** Shared UTF-16 grapheme boundaries and terminal-cell layout for the editor. */
 import stringWidth from 'string-width';
+import { TAB_WIDTH } from './display-tab.js';
 const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
 /** Segment text without changing its UTF-16 offsets or stored whitespace. */
 export function graphemes(text) {
@@ -31,7 +32,17 @@ export function graphemeWidth(text) {
         return 1;
     return stringWidth(text);
 }
-/** Map graphemes to hard-wrapped rows, sharing tab stops and caret reservation. */
+/**
+ * Map graphemes to hard-wrapped rows, sharing tab stops and caret reservation.
+ *
+ * THE TAB STOP IS THE TERMINAL'S (`TAB_WIDTH`), NOT AN EDITOR-SIZED FOUR. It
+ * used to be four, while the transcript handed the raw `\t` to `<Text>` and
+ * the terminal painted it at eight: the same pasted table sat one column off
+ * from itself before and after sending. A tab that would cross the right edge
+ * is still clipped to the row (the caret cannot point past the last cell), so
+ * a tab STRADDLING the wrap is the one shape where the draft and the stored
+ * text can differ by the remainder of the advance.
+ */
 export function buildEditorVisualMap(input) {
     const cols = Math.max(1, Math.floor(input.cols));
     const cursor = snapGrapheme(input.buffer, input.cursor);
@@ -50,12 +61,12 @@ export function buildEditorVisualMap(input) {
             breakRow();
             continue;
         }
-        let width = part.text === '\t' ? Math.min(cols, 4 - column % 4)
+        let width = part.text === '\t' ? Math.min(cols, TAB_WIDTH - column % TAB_WIDTH)
             : graphemeWidth(part.text);
         if (column > 0 && column + width > cols) {
             breakRow();
             if (part.text === '\t')
-                width = Math.min(cols, 4);
+                width = Math.min(cols, TAB_WIDTH);
         }
         locate(part.index);
         rows[rows.length - 1].push({ ...part,