@aragon-agent/cli 0.6.25 → 0.6.26

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

@@ -0,0 +1,83 @@
+/**
+ * What command the new terminal runs (tui-branch-terminal-shortcut 3.4).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * THIS MODULE HAS NO IO ON PURPOSE. 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.
+ *
+ * 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, pasteable into cmd / PowerShell / sh (quoted where needed). */
+    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 toasts and manual fallback. */
+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.
+ *
+ * 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.
+ */
+export declare function joinCommandLine(parts: readonly string[]): 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,109 @@
+/**
+ * What command the new terminal runs (tui-branch-terminal-shortcut 3.4).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * THIS MODULE HAS NO IO ON PURPOSE. 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.
+ *
+ * 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 { 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 toasts and manual fallback. */
+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.
+ *
+ * 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.
+ */
+export function joinCommandLine(parts) {
+    return parts.map(quoteForDisplay).join(' ');
+}
+/** 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.`;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * The `/branch` port: flush, plan, spawn (tui-branch-terminal-shortcut 3.6).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * ORDER IS CORRECTNESS (I-1). The child process's first act is to read the parent
+ * session file, and the parent's checkpoint is debounced and fingerprint-
+ * short-circuited (`checkpoint.ts`). Spawning before a successful FORCED write
+ * means the branch can read the previous turn - or, after `aragon sessions rm
+ * <id>`, no file at all - and the user sees "the branch opened but lost the last
+ * ten turns". That is a data defect, not a UX one, so `checkpoint({force:true})`
+ * returns `ok` before any terminal is created.
+ *
+ * THE CHILD IS NOT A SERVICE (D-5 / I-3): `detached: true`, `stdio: 'ignore'`,
+ * `unref()`, and deliberately no `ProcSupervisor` registration. Registering it
+ * would make the parent's exit kill a session running in another window.
+ *
+ * EVERY FAILURE CARRIES A PASTEABLE COMMAND (I-4). "Could not open a terminal" is
+ * a dead end; `aragon --resume a4k2m9` is 22 characters the user can always use.
+ */
+import { spawn } from 'node:child_process';
+import { type ScopedLogger } from '../logging/logger.js';
+import { type BranchCommandPort } from '../commands/branch-command.js';
+export interface BranchRequest {
+    id: string;
+    cwd: string;
+    /** Late `'error'` events after the window opened (I-10). */
+    onLateError?: (message: string) => void;
+}
+export type BranchOpenResult = {
+    ok: true;
+    command: string;
+    shell: string;
+    rung: string;
+} | {
+    ok: false;
+    reason: 'cooldown' | 'checkpoint-failed' | 'no-launcher' | 'spawn-failed';
+    /**
+     * A complete, user-facing sentence - never an internal reason code.
+     * `checkpoint-failed` in particular has two very different causes
+     * (`not-sendable` vs `no-identity`), and only the launcher knows which one it
+     * hit, so the sentence is composed HERE from `BRANCH_COPY`.
+     */
+    message: string;
+    /** Always present, so no failure is a dead end (I-4). */
+    command: string;
+    retryInMs?: number;
+};
+export interface BranchLauncherDeps {
+    /** Injected by `cli.tsx`: a thin wrapper over `checkpointWriter.writeNow`, with `force`. */
+    checkpoint(opts: {
+        force: true;
+    }): {
+        ok: boolean;
+        message?: string;
+    };
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+    argv: readonly string[];
+    execPath: string;
+    spawn?: typeof spawn;
+    isExecutable?: (name: string) => boolean;
+    now?: () => number;
+    logger?: ScopedLogger;
+}
+/**
+ * Build the port. The only mutable state is this closure's four values, none of
+ * which outlives the process (no persistence, 6 in the spec).
+ */
+export declare function createBranchLauncher(deps: BranchLauncherDeps): BranchCommandPort;

package/dist/session/branch-launch.js

@@ -0,0 +1,248 @@
+/**
+ * The `/branch` port: flush, plan, spawn (tui-branch-terminal-shortcut 3.6).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * ORDER IS CORRECTNESS (I-1). The child process's first act is to read the parent
+ * session file, and the parent's checkpoint is debounced and fingerprint-
+ * short-circuited (`checkpoint.ts`). Spawning before a successful FORCED write
+ * means the branch can read the previous turn - or, after `aragon sessions rm
+ * <id>`, no file at all - and the user sees "the branch opened but lost the last
+ * ten turns". That is a data defect, not a UX one, so `checkpoint({force:true})`
+ * returns `ok` before any terminal is created.
+ *
+ * THE CHILD IS NOT A SERVICE (D-5 / I-3): `detached: true`, `stdio: 'ignore'`,
+ * `unref()`, and deliberately no `ProcSupervisor` registration. Registering it
+ * would make the parent's exit kill a session running in another window.
+ *
+ * EVERY FAILURE CARRIES A PASTEABLE COMMAND (I-4). "Could not open a terminal" is
+ * a dead end; `aragon --resume a4k2m9` is 22 characters the user can always use.
+ */
+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 { BRANCH_TERMINAL_LIMITS } from './limits.js';
+/**
+ * Build the port. The only mutable state is this closure's four values, none of
+ * which outlives the process (no persistence, 6 in the spec).
+ */
+export function createBranchLauncher(deps) {
+    const now = deps.now ?? Date.now;
+    const logger = deps.logger ?? getLogger().child('branch');
+    const spawnFn = deps.spawn ?? spawn;
+    const pathDirs = pathDirsOf(deps.env, deps.platform);
+    const isExecutable = deps.isExecutable ?? defaultIsExecutable(deps.platform, pathDirs);
+    /** Last SUCCESSFUL open (D-10). Failures never move it, so a retry is never blocked. */
+    let lastOpenedAt = null;
+    let inFlight = false;
+    /** Resolution is cached for the process (R-13 / K-14); a FAILED probe is not. */
+    let cachedAragon = null;
+    let cachedShell = null;
+    /**
+     * Resolve WHAT the new window runs, and the command line 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.
+     */
+    function planFor(id) {
+        cachedAragon ??= resolveAragonCommand({
+            argv: deps.argv,
+            execPath: deps.execPath,
+            env: deps.env,
+        });
+        return {
+            aragon: cachedAragon,
+            invocation: buildResumeInvocation({ id, aragon: cachedAragon }),
+        };
+    }
+    function shellFor() {
+        cachedShell ??= resolveShell({
+            platform: deps.platform,
+            env: deps.env,
+            isExecutable,
+            pathDirs,
+        });
+        return cachedShell;
+    }
+    function cooldown(command, retryInMs) {
+        return {
+            ok: false,
+            reason: 'cooldown',
+            message: BRANCH_COPY.cooldown(retryInMs),
+            command,
+            retryInMs,
+        };
+    }
+    function failure(reason, message, command) {
+        return { ok: false, reason, message, command };
+    }
+    /** Steps 1-2: the in-flight gate, then the cooldown window (D-10). */
+    function gated(command) {
+        const windowMs = BRANCH_TERMINAL_LIMITS.cooldownMs;
+        if (inFlight)
+            return cooldown(command, windowMs);
+        if (lastOpenedAt === null)
+            return null;
+        const waited = now() - lastOpenedAt;
+        if (waited >= windowMs)
+            return null;
+        return cooldown(command, Math.max(1, windowMs - waited));
+    }
+    async function openOnce(request) {
+        const { aragon, invocation } = 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.
+        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);
+        }
+        // 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);
+        // 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 });
+        if (!flushed.ok) {
+            const reason = flushed.message ?? 'write-failed';
+            // R-19: `no-identity` is a timing answer ("this frame has no id yet"), not a
+            // 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);
+        }
+        const shell = shellFor();
+        // Step 7: the TITLE is what gets truncated, never the id in the command line (T-47).
+        const title = truncateTitle(`aragon ${request.id}`, BRANCH_TERMINAL_LIMITS.titleMaxCells);
+        const planned = planTerminalLaunch({
+            platform: deps.platform,
+            env: deps.env,
+            pathDirs,
+            isExecutable,
+            shell,
+            command: invocation.parts,
+            title,
+            cwd: request.cwd,
+            manual: joinCommandLine(invocation.parts),
+        });
+        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);
+        }
+        // Step 8: walk the ladder, bounded by maxRungs (T-33).
+        const rungs = planned.plans.slice(0, BRANCH_TERMINAL_LIMITS.maxRungs);
+        let lastError = null;
+        for (const plan of rungs) {
+            const outcome = await trySpawn(request, plan);
+            if (outcome === 'ok') {
+                lastOpenedAt = now();
+                // `origin` is why the record exists (D-18): "I pressed Ctrl+L and nothing
+                // happened" is answered by WHICH aragon the child ran (`aragon` from PATH,
+                // `node <script>`, or the env override) and through which rung, which no
+                // other record in the log can tell you.
+                logger.info('opened', {
+                    id: request.id,
+                    rung: plan.rung,
+                    shell: planned.shell.path,
+                    aragon: aragon.kind,
+                    origin: aragon.origin,
+                });
+                return { ok: true, command, 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);
+    }
+    /**
+     * One rung, with EXACTLY ONE `'error'` LISTENER THAT IS NEVER REMOVED (R-3 / I-10).
+     *
+     * `once('error')` is what the first draft used and it is wrong: after the probe
+     * settles on `'spawn'` (or on the timeout) that handler is still removed on
+     * first use, so a LATE error has no listener - an unhandled `'error'` on a
+     * ChildProcess throws at the process top level and takes the parent TUI with it.
+     * A permanent listener with a `settled` flag gives the probe the first error and
+     * the user the rest.
+     */
+    async function trySpawn(request, plan) {
+        const child = spawnFn(plan.file, plan.args, {
+            cwd: request.cwd,
+            detached: true,
+            // I-3: the child's streams must never join the parent's, or Ink's frame
+            // differ treats another process's bytes as an outside writer.
+            stdio: 'ignore',
+            // A new window has to be visible; hiding it would defeat the whole key.
+            windowsHide: false,
+            // The FULL environment, inherited on purpose (K-7): `ARAGON_HOME` is how the
+            // child finds the same sessions directory, and `ARAGON_*` is user
+            // configuration (D-7). `ARAGON_LOG_FILE` appends per record with `pid` + `sid`.
+            env: deps.env,
+            ...(plan.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
+        });
+        child.unref();
+        return probeSpawn(child, plan, request);
+    }
+    /** Wait for `'spawn'` | `'error'` | the timeout, then keep listening for late errors. */
+    function probeSpawn(child, plan, request) {
+        return new Promise((resolve) => {
+            let settled = false;
+            let timer = null;
+            const finish = (value) => {
+                if (settled) {
+                    if (value === 'ok')
+                        return;
+                    // LATE error: report it, never re-settle, never remove the listener.
+                    const message = value.message || String(value);
+                    logger.warn('late_error', { rung: plan.rung, message });
+                    request.onLateError?.(BRANCH_COPY.lateError(message));
+                    return;
+                }
+                settled = true;
+                if (timer !== null)
+                    clearTimeout(timer);
+                resolve(value);
+            };
+            timer = setTimeout(() => {
+                // A timeout counts as SUCCESS (K-8): `'spawn'` and `'error'` both missing
+                // almost always means the process was created and the event was merely
+                // delayed behind the scheduler. Reporting a failure here produces the worse
+                // error - "window is open, UI says it is not".
+                logger.debug('probe_timeout', { rung: plan.rung });
+                finish('ok');
+            }, BRANCH_TERMINAL_LIMITS.spawnProbeMs);
+            timer.unref?.();
+            // `spawn` fires at most once, so `once` is honest here.
+            child.once('spawn', () => finish('ok'));
+            // PERMANENT. Installed before any await so no error can slip past it.
+            child.on('error', (error) => finish(error));
+        });
+    }
+    return {
+        async open(request) {
+            const blocked = gated(planFor(request.id).invocation.command);
+            if (blocked !== null)
+                return blocked;
+            inFlight = true;
+            try {
+                return await openOnce(request);
+            }
+            finally {
+                // `inFlight` always clears, including on a synchronous throw from `spawn`
+                // (an invalid `cwd`), which then bubbles to `executeSlashInput`'s try/catch
+                // and becomes one honest `Command failed: ...` line (D-2).
+                inFlight = false;
+            }
+        },
+    };
+}