@aragon-agent/cli 0.6.1 → 0.6.2

package/README.md

@@ -14,10 +14,14 @@ steer / configure the session — all without leaving the terminal.
 
 Node **≥ 18**, any platform.
 
-**On Windows, `Shift+Tab` and the mouse wheel additionally need Node ≥ 22.17.0
-(or ≥ 24.2.0).** Everything else — the agent loop, every tool, skills, teams,
-`aragon -p` — works exactly the same on Node 18 and 20, which is why `engines`
-stays at `>=18` rather than locking those users out.
+**On Windows with Node < 22.17.0 (or 24.0/24.1), aragon turns the missing
+console flag on itself at startup**, which restores `Shift+Tab` on most
+machines. Where that is blocked — a locked-down PowerShell, an old console
+host — **`Ctrl+P` toggles the mode instead**; it is bound on every platform and
+does not depend on the console mode, the Node version, or anything else.
+Everything else — the agent loop, every tool, skills, teams, `aragon -p` — works
+exactly the same on Node 18 and 20, which is why `engines` stays at `>=18`
+rather than locking those users out.
 
 The reason is not the terminal emulator and not a setting: on Windows both
 `Shift+Tab` (`CSI Z`) and mouse reporting exist only while the console input
@@ -27,9 +31,14 @@ itself, and that translation has no entry for `Shift+Tab` (it arrives as a
 plain `Tab`) and discards mouse records outright. Node 20 is the current
 Windows default LTS, so this is a common configuration rather than an exotic
 one — it is why the same build behaves differently on two machines. Below that
-version aragon says so at startup and turns mouse reporting off rather than
-asking for reports that can never arrive; use `/plan` to switch mode and
-`Shift+↑` / `Shift+↓` to scroll until you upgrade.
+version aragon sets `ENABLE_VIRTUAL_TERMINAL_INPUT` itself, from a short
+PowerShell helper, right after it puts the console into raw mode — the flag is a
+property of the console, not of Node, so any process attached to it can turn it
+on. When that works, `Shift+Tab` arrives as `CSI Z` again and mouse reporting
+goes back on with it — the wheel should follow by the same route, though only
+the key has been measured. When it does not work, aragon says so at startup and
+turns mouse reporting off rather than asking for reports that can never arrive;
+`Ctrl+P` and `/plan` switch mode, and `Shift+↑` / `Shift+↓` scroll.
 
 ## Install
 
@@ -422,7 +431,8 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | --- | --- |
 | `Enter` | Submit (idle) / queue a steering message (running) |
 | `Alt+Enter` / `Shift+Enter` | Insert a newline |
-| `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows needs Node ≥ 22.17 — see [Requirements](#requirements) |
+| `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows this needs a console flag Node < 22.17 does not set; aragon sets it at startup — see [Requirements](#requirements) |
+| `Ctrl+P` | The same toggle, over a channel no Windows console can swallow. Use it if `Shift+Tab` does nothing |
 | `Esc` | Abort the run / close an overlay / close a popup |
 | `Ctrl+C` ×2 | Exit (first press warns) |
 | `Ctrl+L` | Redraw the frame (clear the screen in inline mode) |
@@ -747,17 +757,28 @@ it is an informed act rather than a stray keypress.
 
 ### If `Shift+Tab` does nothing
 
-**On Windows, check your Node version first: `node -v`.** Below 22.17.0 (or on
-24.0/24.1) the key never reaches aragon as `Shift+Tab` at all — it arrives as an
-ordinary `Tab`, so it does not switch mode, and with the `/` palette or an `@`
-popup open it completes that entry over your draft instead. The mouse wheel is
-dead for the same reason. See [Requirements](#requirements); aragon reports this
-once at startup when it detects it.
-
-Otherwise: some multiplexers and remote-desktop stacks never send `CSI Z`.
-Either way `/plan`, `/plan on`, `/plan off` and `/plan status` are first-class
-equivalents, and `--plan` / `ARAGON_PLAN=1` / `planModeDefault` cover the
-startup case.
+**Press `Ctrl+P`.** It is the same toggle and it does not depend on any of the
+machinery below.
+
+To find out why, run this in the same terminal, press `Shift+Tab` once, then
+`Ctrl+C`:
+
+```powershell
+node -e "process.stdin.setRawMode(true);process.stdin.resume();process.stdin.on('data',b=>{console.log(b.toString('hex'));if(b[0]===3)process.exit(0)})"
+```
+
+| It prints | What it means |
+| --- | --- |
+| `09` | The console is swallowing the modifier — the key is arriving as an ordinary `Tab`. Check `node -v`: below 22.17.0 (or on 24.0/24.1) this is expected, and aragon's own attempt to fix it was blocked. See [Requirements](#requirements) |
+| `1b5b5a` | The key reaches the process fine, so something inside aragon is eating it — most often an overlay is open, or the run is still going and the switch is pending (the status bar shows `BUILD → PLAN`) |
+| nothing | Your terminal, multiplexer or remote-desktop stack never sent it; some never send `CSI Z` at all |
+
+On the first row the wheel is dead for the same reason, and with the `/` palette
+or an `@` popup open the stray `Tab` completes that entry over your draft.
+
+`/plan`, `/plan on`, `/plan off` and `/plan status` are first-class equivalents
+in every case, and `--plan` / `ARAGON_PLAN=1` / `planModeDefault` cover the
+startup case. `aragon doctor` reports this machine's answer as `vt-input`.
 
 ### Headless
 

package/dist/agent/agent-mode.d.ts

@@ -28,6 +28,45 @@ export declare const MODE_LABEL: Record<AgentMode, string>;
  * and nothing else. Two ship today (§1 non-goals).
  */
 export declare function nextMode(current: AgentMode): AgentMode;
+/**
+ * The keys that toggle the mode, as the user sees them written
+ * (shift-tab-mode-toggle-still-dead-on-windows, C2).
+ *
+ * `fallback` exists because `primary` CANNOT be made to work everywhere. On a
+ * Windows console without `ENABLE_VIRTUAL_TERMINAL_INPUT`, libuv takes the
+ * character branch for `VK_TAB` and drops the modifier wholesale, so `Shift+Tab`
+ * and `Ctrl+Tab` both arrive as a bare `0x09` - byte-identical to `Tab`. C1
+ * turns that bit back on where it can, but it has three known ways to fail that
+ * are outside this package (an old conhost refusing the bit, a locked-down
+ * PowerShell, a foreign process resetting the mode), so a rung that depends on
+ * NOTHING has to exist underneath it.
+ *
+ * `ctrl+p` IS MEASURED, not guessed. On the lossy path it arrives as `0x10`,
+ * because Windows generates a real control character for `Ctrl+<letter>` and
+ * libuv's character branch forwards it untouched; `Alt+M` produces no bytes at
+ * all and `Ctrl+Tab` collapses exactly like `Shift+Tab` (analysis section 3.6).
+ * Any idle `Ctrl+<letter>` in the `0x01-0x1A` range would work; this one is free
+ * throughout the package - `keymap.ts` claims a/e/w/u/k, `App` claims c/l/t/o,
+ * and `PromptInput` returns early on every `key.ctrl` - so binding it takes no
+ * behaviour away from anyone. `Ctrl+B` survives the same path but is tmux's
+ * default prefix, and this binding is unconditional and cross-platform, so it
+ * would be silently dead for a whole class of macOS and Linux users.
+ *
+ * BOUND UNCONDITIONALLY, on every platform. A binding that only exists where it
+ * is needed cannot be documented in one place, cannot be taught by muscle
+ * memory, and is missing on precisely the machine whose capability probe was
+ * wrong.
+ *
+ * THESE ARE THE LABELS, NOT THE BINDING. Editing a value here changes only what
+ * the user is TOLD to press - the hint row, the startup notice, `doctor`. The
+ * key that is actually listened for is `input === 'p'` in `App`'s `useInput`,
+ * and the help overlay and README spell both keys out in their own title case.
+ * Change one without the others and the product advertises a key it ignores.
+ */
+export declare const MODE_TOGGLE_KEYS: {
+    readonly primary: "shift+tab";
+    readonly fallback: "ctrl+p";
+};
 /** The two tools that only exist because a human is attached. */
 export declare const PLAN_TOOL_NAMES: readonly ["ask_user", "submit_plan"];
 /**

package/dist/agent/agent-mode.js

@@ -30,6 +30,42 @@ export function nextMode(current) {
     const index = AGENT_MODES.indexOf(current);
     return AGENT_MODES[(index + 1) % AGENT_MODES.length];
 }
+/**
+ * The keys that toggle the mode, as the user sees them written
+ * (shift-tab-mode-toggle-still-dead-on-windows, C2).
+ *
+ * `fallback` exists because `primary` CANNOT be made to work everywhere. On a
+ * Windows console without `ENABLE_VIRTUAL_TERMINAL_INPUT`, libuv takes the
+ * character branch for `VK_TAB` and drops the modifier wholesale, so `Shift+Tab`
+ * and `Ctrl+Tab` both arrive as a bare `0x09` - byte-identical to `Tab`. C1
+ * turns that bit back on where it can, but it has three known ways to fail that
+ * are outside this package (an old conhost refusing the bit, a locked-down
+ * PowerShell, a foreign process resetting the mode), so a rung that depends on
+ * NOTHING has to exist underneath it.
+ *
+ * `ctrl+p` IS MEASURED, not guessed. On the lossy path it arrives as `0x10`,
+ * because Windows generates a real control character for `Ctrl+<letter>` and
+ * libuv's character branch forwards it untouched; `Alt+M` produces no bytes at
+ * all and `Ctrl+Tab` collapses exactly like `Shift+Tab` (analysis section 3.6).
+ * Any idle `Ctrl+<letter>` in the `0x01-0x1A` range would work; this one is free
+ * throughout the package - `keymap.ts` claims a/e/w/u/k, `App` claims c/l/t/o,
+ * and `PromptInput` returns early on every `key.ctrl` - so binding it takes no
+ * behaviour away from anyone. `Ctrl+B` survives the same path but is tmux's
+ * default prefix, and this binding is unconditional and cross-platform, so it
+ * would be silently dead for a whole class of macOS and Linux users.
+ *
+ * BOUND UNCONDITIONALLY, on every platform. A binding that only exists where it
+ * is needed cannot be documented in one place, cannot be taught by muscle
+ * memory, and is missing on precisely the machine whose capability probe was
+ * wrong.
+ *
+ * THESE ARE THE LABELS, NOT THE BINDING. Editing a value here changes only what
+ * the user is TOLD to press - the hint row, the startup notice, `doctor`. The
+ * key that is actually listened for is `input === 'p'` in `App`'s `useInput`,
+ * and the help overlay and README spell both keys out in their own title case.
+ * Change one without the others and the product advertises a key it ignores.
+ */
+export const MODE_TOGGLE_KEYS = { primary: 'shift+tab', fallback: 'ctrl+p' };
 /** The two tools that only exist because a human is attached. */
 export const PLAN_TOOL_NAMES = ['ask_user', 'submit_plan'];
 /**

package/dist/cli.js

@@ -47,6 +47,7 @@ import { setFrameStatsProvider } from './commands/perf.js';
 import { tryCreateMouseFilter } from './input/stdin-mouse-filter.js';
 import { enterAltScreen, writeExitTranscript } from './ui/screen.js';
 import { supportsWindowsVtInput } from './ui/win-vt-input.js';
+import { forceWindowsVtInput } from './ui/win-vt-force.js';
 import { readExitSnapshot } from './ui/exit-snapshot.js';
 import { renderTranscriptText } from './ui/transcript-text.js';
 import { detectCapabilities } from './ui/capabilities.js';
@@ -285,6 +286,69 @@ function makeExecController(flags, deps) {
  */
 const FRAME_FALLBACK_NOTICE = 'Frame diffing lost sync with the terminal and fell back to a full repaint. ' +
     'If the display looks wrong, restart with `--no-diff-render`.';
+/**
+ * Make this console deliver `CSI Z`, on a Node that will not do it for us
+ * (shift-tab-mode-toggle-still-dead-on-windows, C1).
+ *
+ * Returns whether the console now reports; never throws. `false` means nothing
+ * changed and the session runs exactly as it did before this feature existed,
+ * with `MODE_TOGGLE_KEYS.fallback` carrying the mode toggle instead.
+ *
+ * RAW MODE IS RAISED HERE, AND THE ORDER IS THE ENTIRE MECHANISM. libuv rewrites
+ * the whole console mode on every raw-mode TRANSITION, and its pre-22.17 path
+ * does not know about this bit - so setting the bit first and letting Ink raise
+ * raw mode afterwards clears it again, measured (analysis section 3.3). Raising
+ * it first inverts that: `uv_tty_set_mode` returns early when the mode is
+ * unchanged, so Ink's own `setRawMode(true)` at mount is a no-op and the bit
+ * survives to the first keypress.
+ *
+ * That same asymmetry is why there is no restore call anywhere. Ink lowers raw
+ * mode when it unmounts, and that transition IS the restore - it is the only
+ * thing that ever clears the bit, since neither Windows nor the console does
+ * (section 3.5b). The `exit` hook exists for the paths that never unmount
+ * (`taskkill`, a closed terminal window, a crash), which are exactly the
+ * unattended ones where a console left in VT-input mode has nobody to notice.
+ *
+ * WHY THIS RUNS BEFORE `render()` rather than from an effect inside `App`: the
+ * answer gates `wantMouse`, which decides the `?1000h` write and the filter
+ * BEFORE Ink mounts. Learning the truth one tick too late would mean the wheel
+ * stays off for the whole session on a console we just repaired.
+ */
+function forceVtInputForThisConsole() {
+    if (process.platform !== 'win32' || !process.stdin.isTTY)
+        return false;
+    const logger = getLogger();
+    try {
+        process.stdin.setRawMode(true);
+    }
+    catch (err) {
+        // A TTY that refuses raw mode is not a console we can repair; C2 carries it.
+        logger.warn('cli', 'vt_input_rawmode_failed', { error: err.message });
+        return false;
+    }
+    process.on('exit', () => {
+        try {
+            process.stdin.setRawMode(false);
+        }
+        catch {
+            /* Stream already torn down — nothing left to restore. */
+        }
+    });
+    const result = forceWindowsVtInput();
+    if (result.ok) {
+        logger.info('cli', 'vt_input_forced', { before: result.before, after: result.after });
+        return true;
+    }
+    // Constrained Language Mode kills `Add-Type`, an old conhost drops the bit it
+    // does not implement, and `wrong_console` means we configured somebody else's
+    // console. All three are ordinary on the fleets this bug keeps landing on, so
+    // they degrade in silence and only the log says which one happened.
+    logger.warn('cli', 'vt_input_force_failed', {
+        reason: result.reason,
+        ...(result.detail ? { detail: result.detail } : {}),
+    });
+    return false;
+}
 /**
  * The interactive TUI — and the ONLY place that may touch the screen.
  *
@@ -339,7 +403,15 @@ function runInteractive(flags, extras = {}) {
     // filter itself, and the `mouseSource` prop that decides whether the user is
     // advised about a mode that is not running. Wiring any of them separately
     // re-opens the gap where the app claims a capability it does not have.
-    const vtInputSupported = supportsWindowsVtInput(process.platform, process.versions.node);
+    //
+    // AND `vtInputSupported` IS NOW A MEASUREMENT, NOT A PREDICTION
+    // (shift-tab-mode-toggle-still-dead-on-windows, C1). It used to be exactly
+    // `supportsWindowsVtInput(...)` - "is this Node new enough to turn the bit on
+    // for us?". We now turn it on ourselves when it is not, so continuing to gate
+    // on the Node version would switch the wheel off, and keep the warning up, on
+    // a console this process just repaired.
+    const vtInputByNode = supportsWindowsVtInput(process.platform, process.versions.node);
+    const vtInputSupported = vtInputByNode || forceVtInputForThisConsole();
     const wantMouse = mode === 'fullscreen' &&
         config.mouse &&
         !!process.stdout.isTTY &&

package/dist/config/ui-state.d.ts

@@ -35,8 +35,8 @@ export interface UiState {
     /** Whether the one-shot "hold Shift to select text" notice has been shown. */
     mouseNoticeSeen: boolean;
     /**
-     * Whether the one-shot "this Windows console cannot deliver Shift+Tab or the
-     * wheel" notice has been shown.
+     * Which revision of the "this Windows console cannot deliver Shift+Tab or the
+     * wheel" notice this user has already been shown (`0` = none).
      *
      * A SEPARATE KEY FROM `mouseNoticeSeen`, AND THAT IS THE WHOLE POINT. The
      * people this notice exists for are precisely the ones who have already
@@ -44,12 +44,22 @@ export interface UiState {
      * them, and therefore already have `mouseNoticeSeen: true` on disk. Folding
      * the two would make the fix inert for its entire audience, in silence.
      *
+     * A VERSION RATHER THAN A BOOLEAN, for the second turn of that same screw.
+     * The predecessor of this field was `vtInputNoticeSeen: boolean`, written by
+     * builds whose text knew nothing about `MODE_TOGGLE_KEYS.fallback` — and the
+     * audience for the text that DOES name it is, once again, exactly the set of
+     * users who already have the old flag set. A boolean can only say "shown",
+     * never "shown WHAT", so the only way to reach them without re-showing the
+     * notice on every launch is to let the wording carry a number. That old key
+     * is deliberately not read: it is absent from the shape below, so a file
+     * written by 0.6.1 reads as `0` and replays exactly once.
+     *
      * NOT ADDED TO `UI_STATE_SCHEMA`: bumping the schema makes `readFromDisk`
      * discard the whole object, which would reset everyone's submit counter and
      * re-show the mouse notice. A new field simply reads as its default on an
      * older file, which is the behaviour wanted here anyway.
      */
-    vtInputNoticeSeen: boolean;
+    vtInputNoticeVersion: number;
 }
 /** Read the state, caching it for the life of the process. Never throws. */
 export declare function loadUiState(): UiState;
@@ -58,8 +68,9 @@ export declare function readSubmitCount(): number;
 export declare function bumpSubmitCount(): number;
 export declare function getMouseNoticeSeen(): boolean;
 export declare function setMouseNoticeSeen(seen: boolean): void;
-export declare function getVtInputNoticeSeen(): boolean;
-export declare function setVtInputNoticeSeen(seen: boolean): void;
+/** `0` on a file written before the field existed — see the field's comment. */
+export declare function getVtInputNoticeVersion(): number;
+export declare function setVtInputNoticeVersion(version: number): void;
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

package/dist/config/ui-state.js

@@ -35,13 +35,14 @@ const DEFAULT_UI_STATE = {
     schema: UI_STATE_SCHEMA,
     submitCount: 0,
     mouseNoticeSeen: false,
-    vtInputNoticeSeen: false,
+    vtInputNoticeVersion: 0,
 };
 let memory = null;
-function coerceCount(value) {
+/** Non-negative integer or `fallback`; shared by both numeric fields. */
+function coerceCount(value, fallback) {
     const n = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10);
     if (!Number.isFinite(n) || n < 0)
-        return DEFAULT_UI_STATE.submitCount;
+        return fallback;
     return Math.floor(n);
 }
 /**
@@ -61,13 +62,11 @@ function readFromDisk() {
             return { ...DEFAULT_UI_STATE };
         return {
             schema: UI_STATE_SCHEMA,
-            submitCount: coerceCount(parsed.submitCount),
+            submitCount: coerceCount(parsed.submitCount, DEFAULT_UI_STATE.submitCount),
             mouseNoticeSeen: typeof parsed.mouseNoticeSeen === 'boolean'
                 ? parsed.mouseNoticeSeen
                 : DEFAULT_UI_STATE.mouseNoticeSeen,
-            vtInputNoticeSeen: typeof parsed.vtInputNoticeSeen === 'boolean'
-                ? parsed.vtInputNoticeSeen
-                : DEFAULT_UI_STATE.vtInputNoticeSeen,
+            vtInputNoticeVersion: coerceCount(parsed.vtInputNoticeVersion, DEFAULT_UI_STATE.vtInputNoticeVersion),
         };
     }
     catch {
@@ -127,11 +126,12 @@ export function getMouseNoticeSeen() {
 export function setMouseNoticeSeen(seen) {
     update({ mouseNoticeSeen: seen });
 }
-export function getVtInputNoticeSeen() {
-    return loadUiState().vtInputNoticeSeen;
+/** `0` on a file written before the field existed — see the field's comment. */
+export function getVtInputNoticeVersion() {
+    return loadUiState().vtInputNoticeVersion;
 }
-export function setVtInputNoticeSeen(seen) {
-    update({ vtInputNoticeSeen: seen });
+export function setVtInputNoticeVersion(version) {
+    update({ vtInputNoticeVersion: version });
 }
 /**
  * Migration-only: fill in fields that are still at their default, and never
@@ -143,7 +143,7 @@ export function importLegacyUiState(patch) {
     const next = {};
     if (patch.submitCount !== undefined &&
         current.submitCount === DEFAULT_UI_STATE.submitCount) {
-        next.submitCount = coerceCount(patch.submitCount);
+        next.submitCount = coerceCount(patch.submitCount, DEFAULT_UI_STATE.submitCount);
     }
     if (patch.mouseNoticeSeen !== undefined &&
         current.mouseNoticeSeen === DEFAULT_UI_STATE.mouseNoticeSeen) {

package/dist/diagnostics/doctor.js

@@ -17,9 +17,11 @@ import { getHomeResolutionWarning, getSessionsDir, getUserDataDir } from '../con
 import { readConfigFile } from '../config/store.js';
 import { loadConfig, makeGetApiKey } from '../config/load.js';
 import { isAdapterProvider, toRetryPolicy } from '../config/schema.js';
+import { MODE_TOGGLE_KEYS } from '../agent/agent-mode.js';
+import { supportsWindowsVtInput } from '../ui/win-vt-input.js';
 const MIN_NODE_MAJOR = 18;
 export async function runDoctorChecks(flags, opts = {}) {
-    const checks = [checkNode(), checkHome(), checkConfigFile()];
+    const checks = [checkNode(), ...checkVtInput(), checkHome(), checkConfigFile()];
     const config = loadConfig(flags);
     checks.push(checkProviderKey(config));
     checks.push(checkModel(config));
@@ -42,6 +44,44 @@ function checkNode() {
         remedy: `Install Node ${MIN_NODE_MAJOR} or newer.`,
     };
 }
+/**
+ * Whether this console can deliver `Shift+Tab`
+ * (shift-tab-mode-toggle-still-dead-on-windows, C3-2).
+ *
+ * `MIN_NODE_MAJOR` STAYS AT 18 and this is a separate check on purpose. The
+ * install floor is about whether aragon runs; this is about one key, and raising
+ * the floor to 22.17 would lock out a large, otherwise perfectly healthy Node 20
+ * population over it.
+ *
+ * `warn`, never `fail`: aragon turns the console bit on itself at startup, and
+ * `MODE_TOGGLE_KEYS.fallback` works whether or not that succeeded, so nothing
+ * here is actually broken - the exit code must not say it is.
+ *
+ * WHY IT EXISTS AT ALL: `checkNode` passes every version this bug affects, so a
+ * user whose mode toggle is dead ran the tool built to explain their machine and
+ * was told it was fine (analysis section 3.7). A diagnostic that is confidently
+ * wrong is worse than one that is silent - it ends the investigation.
+ *
+ * Returned as a list so the row simply does not exist off Windows, where there
+ * is no such thing as a console input mode to report on.
+ */
+function checkVtInput() {
+    if (process.platform !== 'win32')
+        return [];
+    if (supportsWindowsVtInput(process.platform, process.versions.node)) {
+        return [pass('vt-input', `v${process.versions.node} delivers Shift+Tab and mouse reports`)];
+    }
+    return [
+        {
+            name: 'vt-input',
+            verdict: 'warn',
+            detail: `Node v${process.versions.node} never enables ENABLE_VIRTUAL_TERMINAL_INPUT, so this ` +
+                'console reports Shift+Tab as a plain Tab and sends no mouse events',
+            remedy: `aragon turns that bit on at startup; if a policy blocks it, ${MODE_TOGGLE_KEYS.fallback} ` +
+                'and /plan toggle the mode too. Node 22.17+ (or 24.2+) removes the problem.',
+        },
+    ];
+}
 function checkHome() {
     const home = getUserDataDir();
     const warning = getHomeResolutionWarning();

package/dist/exec/index.js

@@ -22,7 +22,7 @@ import process from 'node:process';
 import { runHeadless } from '../agent/headless.js';
 import { computeCost } from '../agent/usage.js';
 import { loadConfig } from '../config/load.js';
-import { latestSessionForCwd, readSessionFile, resolveSessionRef, sessionPathFor, tryAcquireSessionLock, writeSession, } from '../session/store.js';
+import { latestSessionForCwd, readSessionFile, resolveSessionRef, resumedSessionId, sessionPathFor, tryAcquireSessionLock, writeSession, } from '../session/store.js';
 import { createEmitter } from './emitter.js';
 import { resolveExecOptions } from './options.js';
 import { resolvePermission } from './permission.js';
@@ -352,11 +352,15 @@ function planSession(options, cwd, err) {
     if (options.resume !== undefined) {
         const path = resolveSessionRef(options.resume, cwd);
         const saved = path ? readSessionFile(path) : null;
-        if (!saved) {
+        if (!path || !saved) {
             err.write(`session_not_found: no readable session for --resume "${options.resume}".\n`);
             return null;
         }
-        return { id: saved.meta?.id ?? options.resume, saved, saving, cwd };
+        // NOT `options.resume` AND NOT `meta.id` UNCHECKED (R-7). The flag accepts
+        // `<id|path>`, so the value the caller typed is frequently a path, and
+        // `meta.id` comes out of a file - neither is usable as a filename without
+        // being checked. `resumedSessionId` is the one place that decision is made.
+        return { id: resumedSessionId(path, saved), saved, saving, cwd };
     }
     if (options.continueSession) {
         const entry = latestSessionForCwd(cwd);
@@ -365,7 +369,7 @@ function planSession(options, cwd, err) {
             err.write(`no_session_for_cwd: no previous aragon exec session for ${cwd}.\n`);
             return null;
         }
-        return { id: entry.id, saved, saving, cwd };
+        return { id: resumedSessionId(entry.path, saved), saved, saving, cwd };
     }
     if (options.sessionId !== undefined) {
         // THE UPSERT. A wrapper that mints its own id must not have to ask whether

package/dist/exec/runner.js

@@ -193,8 +193,8 @@ export class ExecRunner {
         const followThrough = this.opts.followThrough ?? 'notify';
         for (;;) {
             const next = await source.next();
-            // EXHAUSTION IS CHECKED BEFORE THE SOURCE, SO A RUN THAT ENDS ON ITS OWN
-            // TERMS IS NEVER MISREPORTED (IF-3). `next === null` first is what makes
+            // THE SOURCE IS POLLED BEFORE THE EXHAUSTION CHECK, SO A RUN THAT ENDS ON
+            // ITS OWN TERMS IS NEVER MISREPORTED (IF-3). `next === null` first is what makes
             // that true: a conversation of exactly `--max-turns` turns whose caller has
             // nothing more to say exits 0 with `end_turn`, not 3 with `max_turns`.
             if (next === null)

package/dist/session/cli-commands.js

@@ -16,7 +16,17 @@
  * should make on its own.
  */
 import process from 'node:process';
-import { listSessions, pruneSessions, readSessionFile, removeSession, sessionPathFor, sessionsDir, } from './store.js';
+import { isValidSessionId, listSessions, pruneSessions, readSessionFile, removeSession, sessionPathFor, sessionsDir, } from './store.js';
+/**
+ * One wording for one rule, shared by `show` and `rm`.
+ *
+ * It is deliberately the same sentence `--session-id` produces: a caller who
+ * meets the rule once should recognise it everywhere, and two spellings of the
+ * same refusal read as two different rules.
+ */
+const INVALID_ID_MESSAGE = (id) => `Invalid session id "${id}". Use 1-64 characters matching ` +
+    '[A-Za-z0-9][A-Za-z0-9._-]* (no "/", "\\", ".." or a leading dot). ' +
+    'Pass a path to `aragon exec --resume` if you mean a file elsewhere.';
 const SUBCOMMANDS = ['list', 'show', 'rm', 'prune', 'path'];
 export function registerSessionsCommand(program) {
     program
@@ -74,6 +84,10 @@ function runShow(argument, opts) {
         process.stderr.write('Usage: aragon sessions show <id> [--json]\n');
         return 2;
     }
+    if (!isValidSessionId(argument)) {
+        process.stderr.write(`${INVALID_ID_MESSAGE(argument)}\n`);
+        return 2;
+    }
     const path = sessionPathFor(argument);
     const session = readSessionFile(path);
     if (!session) {
@@ -112,6 +126,14 @@ function runRemove(argument, opts) {
         process.stderr.write('Refusing to delete without --yes.\n');
         return 2;
     }
+    // BEFORE `--yes` IS HONOURED AS PERMISSION TO DELETE. `sessions rm` is
+    // documented to accept any file IN THE SESSIONS DIRECTORY, because the user
+    // named it - not any file anywhere, which is what an unvalidated id joined to
+    // that directory would reach (R-7).
+    if (!isValidSessionId(argument)) {
+        process.stderr.write(`${INVALID_ID_MESSAGE(argument)}\n`);
+        return 2;
+    }
     if (!removeSession(argument)) {
         process.stderr.write(`session_not_found: no session "${argument}".\n`);
         return 2;

package/dist/session/store.d.ts

@@ -54,6 +54,24 @@ export interface SessionListEntry {
 }
 export declare function sessionsDir(): string;
 export declare function sessionPathFor(id: string): string;
+/**
+ * The id a RESUMED session writes back under.
+ *
+ * `--resume` accepts `<id|path>`, so the value the caller typed is NOT usable as
+ * an id: `--resume ./sessions/hand-saved.json` would otherwise make the path
+ * itself the id, and every later `sessionPathFor` / lock call would build a
+ * filename out of it - outside the sessions directory whenever the path was
+ * relative. That is the same write primitive `--session-id` is validated to
+ * prevent, arriving through the flag next to it. `meta.id` is no safer: it comes
+ * out of a file, and files are inputs.
+ *
+ * The order is the one that keeps every legitimate resume landing where the user
+ * expects: an exec-written session names itself, a TUI `/save` is named by its
+ * file, and anything else gets a fresh id rather than a guess - reported back in
+ * `system.init.sessionId` and `result.sessionId`, so the caller is never left
+ * wondering which session it just wrote.
+ */
+export declare function resumedSessionId(path: string, saved: SavedSession): string;
 /** Read one file, or `null` for anything unreadable. NEVER THROWS. */
 export declare function readSessionFile(path: string): SavedSession | null;
 /**

package/dist/session/store.js

@@ -53,8 +53,58 @@ const POINTER_FILE = '.last.json';
 export function sessionsDir() {
     return getSessionsDir();
 }
+/**
+ * THE CHOKE POINT. Every string that becomes a session filename passes here.
+ *
+ * `isValidSessionId` is applied HERE rather than only at `--session-id`, because
+ * that flag is not the only way a caller-supplied string reaches this function:
+ * `--resume <id|path>` derives an id from the resumed FILE, `sessions rm` /
+ * `sessions show` take one straight from argv, and a session file can carry any
+ * `meta.id` at all. Guarding each caller instead would mean the boundary holds
+ * only for the callers someone remembered - and `join()` silently normalises
+ * `../..` away, so an escape leaves no trace to notice later. Validating at the
+ * single point that builds the path is what makes R-7 a property of the module
+ * rather than a habit of its callers.
+ *
+ * THROWS rather than coercing to a "safe" name: a caller who asked for one file
+ * and silently got another is a worse failure than a loud one, and every caller
+ * that can be handed untrusted input validates first and reports exit 2 itself.
+ */
+function assertSessionId(id) {
+    if (!isValidSessionId(id)) {
+        throw new Error(`Invalid session id "${id}": expected 1-64 characters matching ` +
+            '[A-Za-z0-9][A-Za-z0-9._-]* (no "/", "\\", ".." or a leading dot).');
+    }
+    return id;
+}
 export function sessionPathFor(id) {
-    return join(getSessionsDir(), `${id}.json`);
+    return join(getSessionsDir(), `${assertSessionId(id)}.json`);
+}
+/**
+ * The id a RESUMED session writes back under.
+ *
+ * `--resume` accepts `<id|path>`, so the value the caller typed is NOT usable as
+ * an id: `--resume ./sessions/hand-saved.json` would otherwise make the path
+ * itself the id, and every later `sessionPathFor` / lock call would build a
+ * filename out of it - outside the sessions directory whenever the path was
+ * relative. That is the same write primitive `--session-id` is validated to
+ * prevent, arriving through the flag next to it. `meta.id` is no safer: it comes
+ * out of a file, and files are inputs.
+ *
+ * The order is the one that keeps every legitimate resume landing where the user
+ * expects: an exec-written session names itself, a TUI `/save` is named by its
+ * file, and anything else gets a fresh id rather than a guess - reported back in
+ * `system.init.sessionId` and `result.sessionId`, so the caller is never left
+ * wondering which session it just wrote.
+ */
+export function resumedSessionId(path, saved) {
+    const declared = saved.meta?.id;
+    if (typeof declared === 'string' && isValidSessionId(declared))
+        return declared;
+    const base = basenameId(path);
+    if (isValidSessionId(base))
+        return base;
+    return randomUUID();
 }
 function ensureDir() {
     const dir = getSessionsDir();
@@ -117,6 +167,11 @@ export function writeSession(input) {
     return path;
 }
 export function removeSession(id) {
+    // An id that cannot name a session in this directory has not "failed to be
+    // deleted" - there was never a file of that name to delete. `sessions rm`
+    // validates first and reports the reason, so this stays a boolean.
+    if (!isValidSessionId(id))
+        return false;
     const path = sessionPathFor(id);
     try {
         unlinkSync(path);
@@ -329,7 +384,9 @@ export function tryAcquireSessionLock(id, opts = {}) {
     const now = opts.now ?? Date.now;
     const isAlive = opts.isProcessAlive ?? defaultIsProcessAlive;
     ensureDir();
-    const path = join(getSessionsDir(), `${id}.lock`);
+    // Same boundary as `sessionPathFor` - a lock is a file in this directory too,
+    // and an id that may not name a session may not name its lock either.
+    const path = join(getSessionsDir(), `${assertSessionId(id)}.lock`);
     const payload = {
         pid: process.pid,
         host: hostname(),