@aragon-agent/cli 0.6.26 → 0.6.27

package/CHANGELOG.md

@@ -77,6 +77,21 @@ were written.
 
 ### Fixed
 
+- **`Ctrl+L` opened a window that failed with a PowerShell `ParserError` on
+  Windows.** The script handed to `-EncodedCommand` was the argv joined with
+  quotes but with no call operator, and PowerShell reads a quoted string in command
+  position as an *expression*: with node installed under `C:\Program Files\...`
+  the child was never created - `UnexpectedToken` at column 36 - while the parent
+  TUI still reported that the window opened. `powerShellScript` now emits
+  `& <argv...>`, which is the only form that runs a word of any shape as a
+  command. The failure fallback follows: it is now two labelled lines
+  (`PowerShell:` / `cmd.exe   :`), because one line cannot be correct for both
+  parsers - and the `PowerShell:` line is byte-for-byte the script the window
+  receives. A leading `@` can no longer be left bare either, since `@name` is
+  PowerShell's splat operator and silently swallows an argument. New
+  `powershell-script-parse.test.ts` hands the generated scripts to the real
+  Windows PowerShell parser (and pins the old shape to its exact error), so this
+  class of defect has a guard instead of a green suite.
 - **A conversation saved mid-tool could be resumed into an illegal history.**
   A `tool_call` with no matching `tool_result` makes the next request fail. The
   checkpoint writer closes every dangling call on the copy it writes and re-checks

package/README.md

@@ -1838,16 +1838,45 @@ The platform ladder, in order:
 The shell is `pwsh.exe` then `powershell.exe` on Windows, and `$SHELL` then `bash`
 then `/bin/sh` elsewhere. Windows receives the command as `-EncodedCommand` (base64
 of UTF-16LE), because that alphabet has no spaces, quotes or `cmd` metacharacters -
-it survives `cmd` -> `start` -> PowerShell without a quoting argument.
+it survives `cmd` -> `start` -> PowerShell without a quoting argument. The payload
+that gets encoded is `& <argv...>`, and **the leading `&` is load-bearing**: in
+command position PowerShell reads a quoted string as an *expression*, so with a node
+install under `C:\Program Files\...` the script `'C:\Program Files\nodejs\node.exe'
+<script>` is a `ParserError ... UnexpectedToken` and no child is ever created - while
+the parent still reports that the window opened. `&` is PowerShell's call operator:
+it takes the next word as a command name whatever its shape.
 
 When no terminal can be opened - an SSH session, a container, a machine with no
-graphical session - the command opens nothing and prints the fallback instead:
+graphical session - the command opens nothing and prints the fallback instead. On
+Windows that fallback is **two labelled lines**, because one line cannot be correct
+for both parsers (`& 'x'` is right for PowerShell and wrong for `cmd.exe`, which
+keeps the single quotes; `"x"` is right for `cmd.exe` and an expression to
+PowerShell):
+
+```
+No terminal window could be opened here. Run this in another terminal:
+PowerShell: & aragon --resume a4k2m9
+cmd.exe   : aragon --resume a4k2m9
+```
+
+Copy the line that matches the terminal you opened. macOS and Linux keep the single
+line they have always printed:
 
 ```
 No terminal window could be opened here. Run this in another terminal:
 aragon --resume a4k2m9
 ```
 
+A `node <dist/cli.js>` build prints the same two lines with the full paths, quoted:
+
+```
+PowerShell: & 'C:\Program Files\nodejs\node.exe' C:\Users\me\AppData\Roaming\npm\node_modules\@aragon-agent\cli\dist\launcher.js --resume a4k2m9
+cmd.exe   : "C:\Program Files\nodejs\node.exe" C:\Users\me\AppData\Roaming\npm\node_modules\@aragon-agent\cli\dist\launcher.js --resume a4k2m9
+```
+
+The `PowerShell:` line is byte-for-byte the script the new window receives, so the
+fallback can never drift from what the feature actually runs.
+
 Two environment variables exist because neither belongs in a config file:
 
 | Variable | Effect |

package/dist/proc/terminal-plan.d.ts

@@ -65,7 +65,10 @@ export interface TerminalPlanInput {
     /** New window title, ASCII, already truncated to the cell budget. */
     title: string;
     cwd: string;
-    /** `joinCommandLine(command)` - the pasteable fallback shown to the user. */
+    /**
+     * `renderManualCommand(command, platform)`'s product: two lines on win32
+     * (`PowerShell:` / `cmd.exe   :`), one line everywhere else.
+     */
     manual: string;
 }
 /** The env var that overrides the shell the new window runs (D-7). */
@@ -80,7 +83,22 @@ export declare const ARAGON_BRANCH_SHELL_ENV = "ARAGON_BRANCH_SHELL";
  * so there is exactly one place that number lives.
  */
 export declare function planTerminalLaunch(input: TerminalPlanInput): TerminalPlanResult;
-/** 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 declare function powerShellScript(parts: readonly string[]): string;
 /** Bare words stay bare; everything else becomes a single-quoted literal. */
 export declare function powerShellQuote(value: string): string;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.6.26",
+  "version": "0.6.27",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -56,7 +56,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.38",
+    "@aragon-agent/core": "^0.2.39",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",