@aragon-agent/cli 0.6.25 → 0.6.27

package/dist/proc/terminal-plan.js

@@ -0,0 +1,393 @@
+/**
+ * What a new terminal window looks like from the outside (tui-branch-terminal-shortcut
+ * 3.7).
+ *
+ * ASCII ONLY - `src/proc/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * PURE, AND THAT IS THE POINT. Three platforms, at least ten terminal emulators,
+ * four exec-argument conventions and Windows' three layers of parsing (we -> `cmd`
+ * -> `PowerShell`) all collapse into "what should we spawn, with which argv". A
+ * command body that called `spawn('cmd', ['/c','start', ...])` inline would bury
+ * the only testable part of this feature - the command line itself - inside
+ * untestable IO. `proc/readiness.ts` and `proc/classify.ts` set the same precedent
+ * inside this directory.
+ *
+ * WHY SESSION CODE MAY DEPEND ON THIS MODULE: it imports nothing from
+ * `node:child_process`, reads no configuration and creates no process. The single
+ * place a process is created stays in `session/branch-launch.ts`, so `proc/` keeps
+ * meaning "processes" and `session/` keeps meaning "sessions".
+ *
+ * EVERY RUNG CARRIES ITS OWN WORKING DIRECTORY (D-16 / D-23 / I-9). This is the
+ * one thing a reviewer will assume is free and is not: `spawn({ cwd })` decides the
+ * cwd of the process WE start, and for `wt -w 0 nt` (a new tab in an already
+ * running Windows Terminal) or `osascript` (a new Terminal.app window) that
+ * process merely forwards the request - the window opens in the terminal's own
+ * default directory. So `wt` passes `-d`, and both script rungs start with
+ * `cd <cwd> &&`. `--resume` does not restore a cwd, so a window that opens in the
+ * wrong place can never be corrected from inside the branch.
+ */
+import { statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+/**
+ * The POSIX ladder (D-6), most-specific first.
+ *
+ * `--` TERMINATES THE EMULATOR'S OWN OPTION PARSING for `gnome-terminal`, `kitty`
+ * and `wezterm` (which spells it `start --`). Without it their parsers eat the
+ * `-c` that belongs to the shell we are starting, and the window opens with the
+ * emulator's own error instead of our command - the same class of defect the
+ * `wt` rung has (D-23 / R-16).
+ */
+const POSIX_CANDIDATES = Object.freeze([
+    { name: 'terminal-env', probe: '$TERMINAL', execArgs: ['-e'] },
+    { name: 'x-terminal-emulator', probe: 'x-terminal-emulator', execArgs: ['-e'] },
+    { name: 'gnome-terminal', probe: 'gnome-terminal', execArgs: ['--'] },
+    { name: 'konsole', probe: 'konsole', execArgs: ['-e'] },
+    { name: 'xfce4-terminal', probe: 'xfce4-terminal', execArgs: ['-x'] },
+    { name: 'kitty', probe: 'kitty', execArgs: ['--'] },
+    { name: 'wezterm', probe: 'wezterm', execArgs: ['start', '--'] },
+    { name: 'alacritty', probe: 'alacritty', execArgs: ['-e'] },
+    { name: 'xterm', probe: 'xterm', execArgs: ['-e'] },
+]);
+/** The env var that overrides the shell the new window runs (D-7). */
+export const ARAGON_BRANCH_SHELL_ENV = 'ARAGON_BRANCH_SHELL';
+/**
+ * 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.
+ *
+ * The return value is a LIST because the failures this feature can actually hit
+ * are synchronous argument rejections (ENOENT on `wt.exe`, no X display), and a
+ * list lets `branch-launch.ts` walk down it without knowing anything about
+ * terminals. Rung COUNT is bounded by the caller (`BRANCH_TERMINAL_LIMITS.maxRungs`),
+ * so there is exactly one place that number lives.
+ */
+export function planTerminalLaunch(input) {
+    const isExecutable = input.isExecutable ?? defaultIsExecutable(input.platform, input.pathDirs);
+    const platform = normalizePlatform(input.platform);
+    if (platform === 'win32') {
+        return {
+            ok: true,
+            plans: windowsPlans(input, isExecutable),
+            shell: input.shell,
+            manual: input.manual,
+        };
+    }
+    const script = posixWindowScript(input.cwd, input.shell, input.command);
+    const plans = platform === 'darwin'
+        ? darwinPlans(isExecutable, script)
+        : posixPlans(input, isExecutable, script);
+    if (plans.length === 0) {
+        // NOT AN ERROR STATE TO APOLOGISE FOR (K-2): an SSH session or a container has
+        // no terminal emulator, and the honest answer - one pasteable command - is the
+        // whole reason the manual line exists (I-4).
+        return { ok: false, reason: 'no-launcher', shell: input.shell, manual: input.manual };
+    }
+    return { ok: true, plans, shell: input.shell, manual: input.manual };
+}
+function normalizePlatform(platform) {
+    if (platform === 'win32')
+        return 'win32';
+    if (platform === 'darwin')
+        return 'darwin';
+    return 'posix';
+}
+/**
+ * Windows: `wt` when we are demonstrably inside Windows Terminal, then `cmd`.
+ *
+ * THE `WT_SESSION` TEST IS NOT A CAPABILITY TEST, IT IS THE ONLY HONEST ONE WE
+ * HAVE. Probing for `wt.exe` proves the binary exists, not that a Windows Terminal
+ * is listening; `WT_SESSION` is set for every process a pane starts, so its
+ * presence is the one signal that a new tab will land somewhere.
+ */
+function windowsPlans(input, isExecutable) {
+    const plans = [];
+    const encoded = encodePowerShellCommand(powerShellScript(input.command));
+    const inWindowsTerminal = (input.env.WT_SESSION ?? '').length > 0;
+    if (inWindowsTerminal && isExecutable('wt.exe')) {
+        plans.push({
+            file: 'wt.exe',
+            // `-d` IS THE CWD (D-16). `-w 0` reuses the current window, `nt` opens a new
+            // tab, and `--` stops `wt` parsing the single-dash switches that belong to
+            // PowerShell. This failure is UNOBSERVABLE: `wt.exe` forwards the request and
+            // exits, so a rejected argument still produces a successful `'spawn'` event
+            // and the ladder cannot fall back (K-1 / D-23).
+            args: ['-w', '0', 'nt', '-d', input.cwd, '--title', input.title, '--', input.shell.path,
+                '-NoExit', '-EncodedCommand', encoded],
+            windowsVerbatimArguments: false,
+            rung: 'wt',
+        });
+    }
+    plans.push({
+        file: 'cmd.exe',
+        // `start`'s FIRST argument is the window title, and it must be present: an
+        // empty string is what most snippets use, but naming the window is how a user
+        // tells three branches apart in the taskbar (AC-1). The cwd needs no argument
+        // at all - `cmd.exe` inherits the cwd we pass to `spawn` (I-9).
+        args: ['/d', '/s', '/c', cmdStartLine(input.title, input.shell.path, encoded)],
+        windowsVerbatimArguments: true,
+        rung: 'cmd',
+    });
+    return plans;
+}
+/** `start "<title>" <shell> -NoExit -EncodedCommand <base64>`, one verbatim `cmd` line. */
+function cmdStartLine(title, shellPath, encoded) {
+    return `start ${quoteWin32Arg(title)} ${quoteWin32Arg(shellPath)}` +
+        ` -NoExit -EncodedCommand ${encoded}`;
+}
+/** macOS: Terminal.app via AppleScript; the script owns the cwd and the held-open shell. */
+function darwinPlans(isExecutable, script) {
+    // `osascript` IS PROBED, unlike `cmd.exe`. It lives at `/usr/bin/osascript` on
+    // every macOS install, so a failed probe means a broken PATH or a system without
+    // the tool - and in that case "no terminal could be opened here" plus a pasteable
+    // command is the honest answer (T-29), not a spawn that is certain to fail.
+    if (!isExecutable('osascript'))
+        return [];
+    return [{
+            file: 'osascript',
+            args: [
+                '-e',
+                `tell application "Terminal" to do script "${escapeAppleScriptText(script)}"`,
+                '-e',
+                'tell application "Terminal" to activate',
+            ],
+            windowsVerbatimArguments: false,
+            rung: 'osascript',
+        }];
+}
+/** Every POSIX candidate that exists, in ladder order. */
+function posixPlans(input, isExecutable, script) {
+    const plans = [];
+    for (const candidate of POSIX_CANDIDATES) {
+        const file = resolveCandidate(candidate, input.env);
+        if (file === null || !isExecutable(file))
+            continue;
+        plans.push({
+            file,
+            // The `cd` lives INSIDE the script, not in the emulator's argv: `-e` / `--` /
+            // `-x` conventions all pass the rest of the argv to the shell unchanged, so a
+            // script that starts with `cd` is correct for every rung - including rungs
+            // that do not exist yet (D-16 / D-23).
+            args: [...candidate.execArgs, input.shell.path, '-c', script],
+            windowsVerbatimArguments: false,
+            rung: candidate.name,
+        });
+    }
+    return plans;
+}
+/**
+ * The `$TERMINAL` escape hatch, with the D-7 trade-off spelled out: a value with
+ * spaces (`"/usr/bin/code --reuse-window"`) is used as ONE executable path and
+ * never split, because splitting needs a shell parser and a shell parser is what
+ * re-introduces the quoting problem. Not found means "skip this rung".
+ */
+function resolveCandidate(candidate, env) {
+    if (candidate.probe !== '$TERMINAL')
+        return candidate.probe;
+    const value = env.TERMINAL;
+    if (value === undefined || value.length === 0)
+        return null;
+    return value;
+}
+/**
+ * The window script, used verbatim by both the AppleScript payload and `-c`.
+ *
+ * `cd` FIRST, THEN THE COMMAND, THEN `exec <shell> -i`. The trailing `exec` keeps
+ * the window alive after `aragon` exits: the TUI writes its final transcript on
+ * exit (`ui/exit-snapshot.ts`), and a window that closes at that instant swallows
+ * the last screenful the user was about to read. `-c`, not `-lc` (R-15): a LOGIN
+ * shell sources `~/.bash_profile` / `~/.zprofile`, which can be slow, noisy, or
+ * PATH-changing, and holding the window open is already `exec ... -i`'s job.
+ */
+function posixWindowScript(cwd, shell, command) {
+    return `cd ${posixQuote(cwd)} && ${posixScript(command)} ; exec ${posixQuote(shell.path)} -i`;
+}
+/**
+ * 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) {
+    // 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) {
+    if (BARE_POWER_SHELL_WORD_RE.test(value))
+        return value;
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * `-EncodedCommand` takes base64 of UTF-16LE, which needs no shell quoting at all.
+ *
+ * The alphabet is `A-Za-z0-9+/=` - no spaces, no quotes, no `cmd` metacharacters -
+ * so the blob survives all three of Windows' parsers as an ordinary word. This is
+ * the same trick `ui/win-vt-force.ts` uses, for the same reason: encode the fragile
+ * thing into a form nothing can argue with, at construction time. Our command line
+ * necessarily contains spaced paths (`C:\Program Files\nodejs\node.exe`), so the
+ * fragile thing is not hypothetical.
+ */
+export function encodePowerShellCommand(script) {
+    return Buffer.from(script, 'utf16le').toString('base64');
+}
+/** POSIX single-quote escaping: `'` becomes `'\''`. */
+export function posixQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+export function posixScript(parts) {
+    return parts.map(posixQuote).join(' ');
+}
+/** AppleScript string literals only need `\` and `"` escaped. */
+export function escapeAppleScriptText(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/**
+ * Win32 argv quoting for the `cmd` rung's title and shell path: quote when it
+ * contains whitespace, otherwise leave it alone.
+ *
+ * THE INPUT DOMAIN EXCLUDES `"` BY CONSTRUCTION (R-17/T-48): Windows paths cannot
+ * contain it, and the title is `aragon <id>` where an id is `[A-Za-z0-9._-]`. If a
+ * future source can contain a quote, this must switch to `cmd`'s rule (`""`) and
+ * not to the POSIX `\"` written here - the two are not interchangeable.
+ */
+export function quoteWin32Arg(value) {
+    return /\s/.test(value) ? `"${value}"` : value;
+}
+/** PATH entries for `name` probing: both spellings on Windows, `:` on POSIX. */
+export function pathDirsOf(env, platform) {
+    if (normalizePlatform(platform) === 'win32') {
+        // `Path` and `PATH` genuinely coexist in a Windows env object (Node copies what
+        // it was given), and reading only one of them is how a probe silently finds
+        // nothing. Both are read, in that order, deduplicated.
+        const dirs = [];
+        for (const key of ['Path', 'PATH']) {
+            const value = env[key];
+            if (value === undefined || value.length === 0)
+                continue;
+            for (const dir of value.split(';')) {
+                if (dir.length > 0 && !dirs.includes(dir))
+                    dirs.push(dir);
+            }
+        }
+        return dirs;
+    }
+    const value = env.PATH ?? '';
+    return value.split(':').filter((dir) => dir.length > 0);
+}
+/**
+ * The default probe: is this a file we could execute?
+ *
+ * An absolute or separator-bearing value is stat'd directly (that is the
+ * `ARAGON_BRANCH_SHELL=/usr/local/bin/fish` case); a bare name is looked up in the
+ * PATH directories, trying `name` and - on Windows - `name + '.exe'`, because a
+ * user typing `pwsh` and a probe looking for `pwsh.exe` are the same request.
+ *
+ * EVERY EXCEPTION RETURNS FALSE: one failed stat means "this candidate is not
+ * here", not "the feature is broken", and a missing terminal must degrade to the
+ * manual command rather than throw out of a key handler.
+ */
+export function defaultIsExecutable(platform, pathDirs) {
+    const windows = normalizePlatform(platform) === 'win32';
+    const dirs = pathDirs ?? pathDirsOf(process.env, platform);
+    return (name) => {
+        if (name.length === 0)
+            return false;
+        const suffixes = windows && !/\.exe$/i.test(name) ? [name, `${name}.exe`] : [name];
+        if (isAbsolute(name) || /[\\/]/.test(name)) {
+            return suffixes.some((suffix) => isFile(suffix));
+        }
+        return dirs.some((dir) => suffixes.some((suffix) => isFile(join(dir, suffix))));
+    };
+}
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Which shell the new window runs (D-7), first match wins.
+ *
+ * The requirement says "PowerShell / bash", and both platforms have two answers
+ * worth distinguishing: PowerShell 7 (`pwsh.exe`) when the user installed it,
+ * Windows PowerShell 5.1 otherwise; `$SHELL` when the user's login shell is not
+ * bash, then bash, then `/bin/sh` as the one path that exists everywhere.
+ * `ARAGON_BRANCH_SHELL` is the escape hatch - an ENV VALUE, not a config key
+ * (D-17): a "Ctrl+L opens no terminal" switch would create the one state this
+ * feature must never have.
+ */
+export function resolveShell(input) {
+    // `pathDirs` is FORWARDED, not dropped: a caller that supplies its own PATH
+    // (a test, or `branch-launch.ts` with the injected env) must not have the shell
+    // probe silently fall back to `process.env`'s PATH.
+    const isExecutable = input.isExecutable ?? defaultIsExecutable(input.platform, input.pathDirs);
+    const override = input.env[ARAGON_BRANCH_SHELL_ENV];
+    const platform = normalizePlatform(input.platform);
+    if (platform === 'win32') {
+        if (override !== undefined && override.length > 0 && isExecutable(override)) {
+            return { path: override, kind: 'powershell' };
+        }
+        if (isExecutable('pwsh.exe'))
+            return { path: 'pwsh.exe', kind: 'powershell' };
+        return { path: 'powershell.exe', kind: 'powershell' };
+    }
+    if (override !== undefined && override.length > 0) {
+        return { path: override, kind: 'posix' };
+    }
+    const loginShell = input.env.SHELL;
+    if (loginShell !== undefined && isAbsolute(loginShell)) {
+        return { path: loginShell, kind: 'posix' };
+    }
+    if (isExecutable('bash'))
+        return { path: 'bash', kind: 'posix' };
+    return { path: '/bin/sh', kind: 'posix' };
+}
+/**
+ * Fit a window title into `maxCells` columns (R-7 / T-47).
+ *
+ * THE TITLE IS THE ONLY THING THIS TOUCHES. An id can be 64 characters long, so
+ * `aragon <id>` exceeds the 60-cell budget by construction for the longest ids -
+ * and truncating the id anywhere else (the command line, `--resume`) would produce
+ * a branch that cannot find its own parent. Code points, not bytes: the title is
+ * ASCII today, and a future non-ASCII title must not be cut through a surrogate
+ * pair.
+ */
+export function truncateTitle(title, maxCells) {
+    const chars = Array.from(title);
+    // A budget that is not a usable number is a caller bug, not a reason to destroy
+    // the title: clamping to one character would be silently worse than not cutting.
+    if (!Number.isFinite(maxCells) || maxCells < 1)
+        return title;
+    if (chars.length <= maxCells)
+        return title;
+    return chars.slice(0, Math.floor(maxCells)).join('');
+}

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

@@ -0,0 +1,127 @@
+/**
+ * What command the new terminal runs (tui-branch-terminal-shortcut 3.4).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * 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
+ * feature that a unit test can pin exactly - the command line - is not buried
+ * inside an `spawn()` call. The repository already draws the boundary this way:
+ * `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*.
+ */
+/** Which of the three resolution rules produced the command (D-8). */
+export type AragonCommandKind = 'override' | 'script' | 'bin';
+export interface AragonCommandResolution {
+    /** argv pieces, ready to hand to a shell or a terminal emulator. */
+    parts: string[];
+    kind: AragonCommandKind;
+    /** Human-readable note for the log and the error copy. Never part of the command. */
+    origin: string;
+}
+export interface BranchInvocation {
+    /** `[...aragon.parts, '--resume', id]`. */
+    parts: string[];
+    /**
+     * 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";
+/** The env var that overrides "what executable the new window runs" (D-7 sibling). */
+export declare const ARAGON_BRANCH_COMMAND_ENV = "ARAGON_BRANCH_COMMAND";
+/**
+ * Decide what to execute in the new window (D-8), first match wins.
+ *
+ * The precedence exists because `aragon` is NOT on PATH in three of this
+ * repository's own four ways of running: `npm run dev:cli`, `npx
+ * @aragon-agent/cli`, and `node packages/cli/dist/cli.js`. Rule 2 recovers all
+ * three from `process.execPath` + `process.argv[1]` without consulting PATH at
+ * all, which is the only way "press the key and something starts" holds on a
+ * machine where the global install is missing.
+ *
+ * The override is treated as ONE executable path and never split into arguments:
+ * splitting needs a shell parser, and a shell parser is what re-introduces the
+ * quoting problem this feature spends a whole module avoiding. The documented
+ * escape hatch is a `.cmd` / `.sh` wrapper.
+ */
+export declare function resolveAragonCommand(input: {
+    argv: readonly string[];
+    execPath: string;
+    env: Record<string, string | undefined>;
+}): AragonCommandResolution;
+/**
+ * `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 read at a glance.
+ *
+ * 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.
+ *
+ * The command body checks first (it owns the user-facing sentence). This check
+ * exists because a future caller can go straight to `buildResumeInvocation`, and
+ * the injection defence belongs at the boundary that builds the string rather
+ * than at the one call site that happens to exist today.
+ *
+ * Returns `null` when the id is usable, otherwise one sentence naming the actual
+ * value (`<= 64 characters`, first 24 of it) so the user can see what was wrong.
+ */
+export declare function validateBranchId(id: string): string | null;

package/dist/session/branch-invocation.js

@@ -0,0 +1,153 @@
+/**
+ * What command the new terminal runs (tui-branch-terminal-shortcut 3.4).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * 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
+ * feature that a unit test can pin exactly - the command line - is not buried
+ * inside an `spawn()` call. The repository already draws the boundary this way:
+ * `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). */
+export const ARAGON_BRANCH_COMMAND_ENV = 'ARAGON_BRANCH_COMMAND';
+/** Longest prefix of a rejected id that reaches the user's screen. */
+const REJECTED_ID_PREVIEW_CELLS = 24;
+/**
+ * A path that could be a script we are already running (`node <script.js>`).
+ *
+ * Anchored and case-insensitive: Windows writes `.JS` in the wild, and an
+ * unanchored variant would also match `cli.js.bak` - which is not something node
+ * could have been invoked with.
+ */
+const SCRIPT_PATH_RE = /\.(?:js|cjs|mjs)$/i;
+/**
+ * Decide what to execute in the new window (D-8), first match wins.
+ *
+ * The precedence exists because `aragon` is NOT on PATH in three of this
+ * repository's own four ways of running: `npm run dev:cli`, `npx
+ * @aragon-agent/cli`, and `node packages/cli/dist/cli.js`. Rule 2 recovers all
+ * three from `process.execPath` + `process.argv[1]` without consulting PATH at
+ * all, which is the only way "press the key and something starts" holds on a
+ * machine where the global install is missing.
+ *
+ * The override is treated as ONE executable path and never split into arguments:
+ * splitting needs a shell parser, and a shell parser is what re-introduces the
+ * quoting problem this feature spends a whole module avoiding. The documented
+ * escape hatch is a `.cmd` / `.sh` wrapper.
+ */
+export function resolveAragonCommand(input) {
+    const override = input.env[ARAGON_BRANCH_COMMAND_ENV];
+    if (override !== undefined && override.length > 0) {
+        return {
+            parts: [override],
+            kind: 'override',
+            origin: `${ARAGON_BRANCH_COMMAND_ENV}=${override}`,
+        };
+    }
+    const script = input.argv[1];
+    if (script !== undefined && isAbsolute(script) && SCRIPT_PATH_RE.test(script)) {
+        return {
+            parts: [input.execPath, script],
+            kind: 'script',
+            origin: 'process.execPath + process.argv[1]',
+        };
+    }
+    return { parts: ['aragon'], kind: 'bin', origin: 'aragon on PATH' };
+}
+/**
+ * `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 read at a glance.
+ *
+ * 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)
+        return '""';
+    if (!/[\s"]/.test(part))
+        return part;
+    return `"${part.replace(/"/g, '\\"')}"`;
+}
+/**
+ * The second gate on D-9: an id is about to be concatenated into a command line.
+ *
+ * The command body checks first (it owns the user-facing sentence). This check
+ * exists because a future caller can go straight to `buildResumeInvocation`, and
+ * the injection defence belongs at the boundary that builds the string rather
+ * than at the one call site that happens to exist today.
+ *
+ * Returns `null` when the id is usable, otherwise one sentence naming the actual
+ * value (`<= 64 characters`, first 24 of it) so the user can see what was wrong.
+ */
+export function validateBranchId(id) {
+    if (isValidSessionId(id))
+        return null;
+    const preview = id.slice(0, REJECTED_ID_PREVIEW_CELLS);
+    return `Session id "${preview}" is not a legal file name, so it cannot be resumed.`;
+}