@aragon-agent/cli 0.6.24 → 0.6.26

package/dist/commands/clear-command.js

@@ -0,0 +1,107 @@
+/**
+ * `/clear` - start a new conversation - plus its `/reset` alias and the
+ * `/clear screen` form that keeps the old "just wipe the screen" meaning
+ * (clear-command-context-reset §3.5 / D-1 / D-2 / D-3).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`. The one
+ * localized string below is written with `\u` escapes for that reason, exactly
+ * as the `/reset` body it replaces did.
+ *
+ * WHY THE BODY LIVES HERE AND THE REGISTRATION STAYS IN `builtins.ts`: the same
+ * reason `/compact` and `/context` do (D-8). `builtins.ts` is 1511 lines against
+ * `CLAUDE.md`'s 1000-line cap, and this command is no longer a two-line
+ * projection reset - it interrupts a run, waits for it, archives a conversation
+ * and then clears. A two-line edit belongs inline; this does not.
+ *
+ * THE COMMAND'S ONLY JOB IS SEQUENCING AND SPEAKING. Every state change happens
+ * on the controller port (`AgentController.resetConversation`, which delegates
+ * the ORDER to `agent/conversation-reset.ts`), and every word the user reads is
+ * decided here, in one place, in the exact order they will read it.
+ */
+import { getLogger } from '../logging/logger.js';
+/** The toast a successful clear shows. Pinned verbatim by an existing test. */
+const CLEARED_TOAST = 'Started a new conversation.';
+/**
+ * Run `/clear` or `/reset`. Both registry entries point HERE (D-2), which is
+ * what stops the two from drifting back into "one clears the screen, one clears
+ * the session" - the drift that produced the defect this feature fixes.
+ */
+export async function runClearCommand(ctx) {
+    const verb = ctx.args.trim().toLowerCase();
+    if (verb === 'screen') {
+        // The old behaviour, byte for byte (I-3): silent, transcript plus the todo
+        // panel, history untouched.
+        clearScreenOnly(ctx);
+        return;
+    }
+    if (verb !== '') {
+        // Rejected rather than ignored. A command that silently accepts and
+        // discards an argument is a surface that lies about what it understood.
+        ctx.notify('warn', `Unknown argument "${ctx.args.trim()}" - use /clear [screen].`);
+        return;
+    }
+    // READ BEFORE CLEARING (P1-2 / I-9). `clearAllQueues()` empties
+    // `pendingUserSteering`, so a count taken afterwards is always zero - and a
+    // notice that says "0 messages cancelled" is worse than no notice at all.
+    const cancelled = ctx.state.pendingSteering.length;
+    const result = await ctx.controller.resetConversation({
+        interrupt: true,
+        // A THUNK, NOT A VALUE (P0-1 / §3.3). `ctx.state` is the view as of command
+        // entry, and the archive happens AFTER the interrupted engine unwinds - so
+        // the last tool cards of the abandoned run are written to the transcript in
+        // between. A value captured here would archive everything except the part
+        // the user was looking at when they typed the command.
+        readTranscript: () => ctx.transcriptEntries?.() ?? ctx.state.entries,
+    });
+    if (!result.ok) {
+        // ZERO SIDE EFFECTS (I-4), and a trace (P1-5). The user gets one sentence
+        // naming the next action; the log gets the reason, because "my /clear did
+        // nothing" is otherwise unanswerable after the fact.
+        getLogger().warn('agent', 'clear_still_running', { reason: result.reason });
+        ctx.notify('warn', result.message);
+        return;
+    }
+    // THE VIEW GOES LAST (B-5 / §3.3). `App`'s dispatch wrapper zeroes the run
+    // metrics, the interaction phase and the scroll anchor on this action, so
+    // dispatching it after the engine has settled is what makes "cleared" mean
+    // "nothing is still writing into it".
+    ctx.dispatch({ type: 'resetConversation' });
+    // THE ONE CONSUMER OF `messagesCleared` (P2-1). It cannot join the toast:
+    // `clear-command-todo.test.ts` pins that string verbatim, and a count nobody
+    // asked for is noise in the one place the user reads confirmations.
+    getLogger().info('agent', 'conversation_cleared', {
+        messagesCleared: result.messagesCleared,
+        interrupted: result.interrupted,
+    });
+    ctx.toast('info', CLEARED_TOAST);
+    // REINSTATED FROM THE OLD `/reset` (P1-1 / C-3). Dropping it would silently
+    // delete a user-visible acknowledgement that already existed and was already
+    // pinned by test.
+    if (cancelled) {
+        ctx.notify('warn', `\u5df2\u53d6\u6d88 ${cancelled} \u6761\u672a\u63a5\u6536\u6d88\u606f`);
+    }
+    if (result.archivedPath) {
+        // A PATH RATHER THAN A PROMISE: the user can copy it, and `/resume` accepts
+        // an absolute path. "Archived" with no way to find the file is a reassurance,
+        // not a recovery.
+        ctx.notify('info', `Previous conversation archived: ${result.archivedPath} (/resume <path> to restore)`);
+    }
+}
+/**
+ * Today's `/clear`, unchanged and silent (D-3 / I-3).
+ *
+ * Kept as a real form rather than as a separate command because "clear the
+ * screen" and "clear the conversation" are two different intentions, and a user
+ * who wants the first must not have to risk the second. It also gives
+ * `clearTranscript` a live dispatcher: `CLAUDE.md` forbids orphaned actions, and
+ * this was the last one that would have had none.
+ */
+function clearScreenOnly(ctx) {
+    // A USER OVERRIDE OF A PROJECTION, the same class as `/todo clear`, so it
+    // reuses reason `'user'`; the distinction against `clearMessages()`'s `'reset'`
+    // is recorded on `TodoStore`. Clearing the STORE and not merely the view
+    // mirror is what keeps `/save`, `/todo status|continue` and follow-through
+    // agreeing with the screen - they read the store directly.
+    ctx.controller.clearTodos();
+    ctx.dispatch({ type: 'clearTranscript' });
+}

package/dist/commands/registry.d.ts

@@ -6,10 +6,12 @@ import type { SubmitMessageOptions } from '../agent/prompt-options.js';
 import type { CopyRequest, CopyRequestResult } from '../ui/clipboard-task.js';
 import type { AgentController } from '../agent/controller.js';
 import type { AgentMode } from '../agent/agent-mode.js';
-import type { NoticeLevel, Overlay, ToastLevel, ViewAction, ViewState } from '../agent/reducer.js';
+import type { Entry, NoticeLevel, Overlay, ToastLevel, ViewAction, ViewState } from '../agent/reducer.js';
 import type { PersistedConfig } from '../config/schema.js';
 import type { FollowThroughBudget } from '../todo/follow-through.js';
 import type { UpdateCommandPort } from '../update/types.js';
+import type { SessionCommandPort } from './session-command.js';
+import type { BranchCommandPort } from './branch-command.js';
 export interface CommandContext {
     /** App-owned shared lock and single feedback path for command and selection copies. */
     requestCopy?: (request: CopyRequest) => Promise<CopyRequestResult>;
@@ -108,6 +110,51 @@ export interface CommandContext {
      * stream is handed over directly.
      */
     writeForeign?: (text: string) => void;
+    /**
+     * The LIVE transcript rows, for `/clear`'s archive (clear-command-context-reset
+     * P0-1 / §3.5).
+     *
+     * A THUNK, AND THAT IS THE WHOLE POINT. The `state` field above is a snapshot
+     * of `ViewState` taken when the command started; `/clear` interrupts a run and
+     * then waits for the engine to unwind, so the last tool cards of that run are
+     * written to the transcript AFTER `state` was captured. Reading `state.entries`
+     * would archive everything except the part the user was just looking at.
+     *
+     * OPTIONAL, like `followBudget` / `update` / `mouse`: every existing
+     * `CommandContext` fixture in this package builds the object by literal, and a
+     * required field would break all of them at compile time for a feature none of
+     * them are about. Absent means the archive degrades to history-only.
+     *
+     * `Entry` arrives as a TYPE-ONLY import so this module keeps its runtime shape
+     * (the same rule the `update/types.js` import above follows).
+     */
+    transcriptEntries?: () => Entry[];
+    /**
+     * The session's read-only identity plus the two actions `/session` and
+     * `/resume` need (tui-session-id-resume 3.11 / D-14 / D-15).
+     *
+     * OPTIONAL, like `followBudget` / `update` / `mouse` / `transcriptEntries`
+     * above: every existing `CommandContext` fixture in this package builds this
+     * object by literal, and a required field would break all of them at compile
+     * time for a feature none of them is about. Absent means the build has no
+     * session identity, and `/session` says exactly that rather than pretending.
+     */
+    session?: SessionCommandPort;
+    /**
+     * The `/branch` port: open a new terminal on this session (tui-branch-terminal-
+     * shortcut 3.11 / #8).
+     *
+     * OPTIONAL for the same reason `session` above is: every existing
+     * `CommandContext` fixture in this package builds this object by literal, and a
+     * required field would break all of them at compile time for a feature none of
+     * them is about. Absent means `/branch` says "not available in this build"
+     * rather than failing silently.
+     *
+     * TYPE-ONLY import, following the rule the `session-command.js` import above
+     * records: the command needs the SHAPE of the port and of its result, never a
+     * value at run time.
+     */
+    branch?: BranchCommandPort;
 }
 /** What `/mouse` can see and do. Read at command time, never captured. */
 export interface MouseCommandPort {

package/dist/commands/session-command.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `/session` - report this session's identity, and the two things a user does
+ * with it (tui-session-id-resume §3.11 / D-13 / D-14).
+ *
+ * ASCII ONLY - `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THE BODY LIVES HERE AND THE REGISTRATION STAYS IN `builtins.ts`: the same
+ * reason `/clear` and `/compact` do. `builtins.ts` is already past the
+ * 1000-line guideline, and this command is a report, not a one-liner.
+ *
+ * COPYING THE RESUME COMMAND IS THE POINT, NOT A CONVENIENCE (D-14). Typing 6
+ * characters off a status bar is the only step of this whole feature that can
+ * fail for a human, and `/session copy` removes it: one keystroke, the exact
+ * command in the clipboard, no transcription.
+ */
+import type { CheckpointResult } from '../session/checkpoint.js';
+import type { SessionIdentity } from '../session/startup-session.js';
+import type { CommandContext } from './registry.js';
+/**
+ * What `/session` can see and do.
+ *
+ * THREE MEMBERS AND NO MORE. `identity()` is read at command time rather than
+ * captured, because `/resume` rotates the id under a live App (D-15) and a
+ * captured value would report the previous one for the rest of the session.
+ */
+export interface SessionCommandPort {
+    /** The current identity, or `undefined` when this build has none. */
+    identity(): SessionIdentity | undefined;
+    /** Write once now; `pin` also marks the file as never-prunable. */
+    checkpoint(opts?: {
+        pin?: boolean;
+    }): CheckpointResult;
+    /** Adopt another conversation and move to a derived id; `undefined` if it cannot. */
+    rotate(loadedPath: string): SessionIdentity | undefined;
+}
+/**
+ * The one path an id maps to.
+ *
+ * THROUGH `sessionPathFor` RATHER THAN A SECOND `join` (§2.2): that function is
+ * the single choke point where an id becomes a file name, and a report that
+ * built its own path would be the first thing to disagree with the writer about
+ * where a session lives.
+ */
+export declare function sessionFilePath(id: string): string;
+/**
+ * Run `/session`, `/session copy` or `/session pin`.
+ *
+ * ONE NOTICE FOR THE WHOLE REPORT (§3.11 / R-20): six separate notices would put
+ * six cards in the transcript and replay them as six fragments on exit. The
+ * `file` line is NOT truncated even when it overflows: it is a path the user
+ * needs to be able to copy, and it is in the same family as `/save`'s
+ * `Saved session to <path>`.
+ */
+export declare function runSessionCommand(ctx: CommandContext): void;

package/dist/commands/session-command.js

@@ -0,0 +1,109 @@
+/**
+ * `/session` - report this session's identity, and the two things a user does
+ * with it (tui-session-id-resume §3.11 / D-13 / D-14).
+ *
+ * ASCII ONLY - `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THE BODY LIVES HERE AND THE REGISTRATION STAYS IN `builtins.ts`: the same
+ * reason `/clear` and `/compact` do. `builtins.ts` is already past the
+ * 1000-line guideline, and this command is a report, not a one-liner.
+ *
+ * COPYING THE RESUME COMMAND IS THE POINT, NOT A CONVENIENCE (D-14). Typing 6
+ * characters off a status bar is the only step of this whole feature that can
+ * fail for a human, and `/session copy` removes it: one keystroke, the exact
+ * command in the clipboard, no transcription.
+ */
+import { sessionPathFor } from '../session/store.js';
+/**
+ * The one path an id maps to.
+ *
+ * THROUGH `sessionPathFor` RATHER THAN A SECOND `join` (§2.2): that function is
+ * the single choke point where an id becomes a file name, and a report that
+ * built its own path would be the first thing to disagree with the writer about
+ * where a session lives.
+ */
+export function sessionFilePath(id) {
+    return sessionPathFor(id);
+}
+/**
+ * Run `/session`, `/session copy` or `/session pin`.
+ *
+ * ONE NOTICE FOR THE WHOLE REPORT (§3.11 / R-20): six separate notices would put
+ * six cards in the transcript and replay them as six fragments on exit. The
+ * `file` line is NOT truncated even when it overflows: it is a path the user
+ * needs to be able to copy, and it is in the same family as `/save`'s
+ * `Saved session to <path>`.
+ */
+export function runSessionCommand(ctx) {
+    const port = ctx.session;
+    if (!port) {
+        // HONEST RATHER THAN SILENT: a build without the feature should say so,
+        // because "nothing happened" reads as a bug.
+        ctx.notify('warn', 'This session has no id (session recording is off for this build).');
+        return;
+    }
+    const verb = ctx.args.trim().toLowerCase();
+    const identity = port.identity();
+    if (!identity) {
+        ctx.notify('warn', 'This session has no id (session recording is off for this build).');
+        return;
+    }
+    if (verb === 'copy') {
+        copyCommand(ctx, identity);
+        return;
+    }
+    if (verb === 'pin') {
+        pinSession(ctx, port, identity);
+        return;
+    }
+    if (verb !== '') {
+        // Rejected rather than ignored: a command that silently discards an argument
+        // is a surface that lies about what it understood.
+        ctx.notify('warn', `Unknown argument "${ctx.args.trim()}" - use /session [copy|pin].`);
+        return;
+    }
+    report(ctx, identity);
+}
+/** The six-line report. Pure read: no checkpoint, no toast, no dispatch. */
+function report(ctx, identity) {
+    const resume = `aragon --resume ${identity.id}`;
+    const lines = [
+        `id        ${identity.id}`,
+        `file      ${sessionFilePath(identity.id)}`,
+        identity.parentId
+            ? `branch    ${identity.parentId} (this session does not write to it)`
+            : 'branch    (none - this session started here)',
+        `pinned    ${identity.pinned ? 'yes' : 'no'}`,
+        `resume    ${resume}`,
+        'save as   aragon --save <new-id>',
+    ];
+    ctx.notify('info', lines.join('\n'));
+}
+/** `/session copy` - the exact command, through the SAME door `/copy` uses. */
+function copyCommand(ctx, identity) {
+    const text = `aragon --resume ${identity.id}`;
+    if (!ctx.requestCopy) {
+        ctx.notify('warn', 'Clipboard coordinator unavailable.');
+        return;
+    }
+    void ctx.requestCopy({ text, lines: 1 }).then((result) => {
+        if (result.status === 'confirmed' || result.status === 'sent') {
+            ctx.toast('info', `Copied ${text}`);
+            return;
+        }
+        // A failed or refused copy must not look like a successful one: the command
+        // is short enough to read off the report above, so naming the failure is
+        // enough to recover.
+        ctx.notify('warn', result.status === 'busy' ? 'Clipboard is busy - try /session copy again.' :
+            `Copy failed: ${result.reason}`);
+    });
+}
+/** `/session pin` - write once and stop `sessions prune` from ever touching it. */
+function pinSession(ctx, port, identity) {
+    const result = port.checkpoint({ pin: true });
+    if (!result.ok) {
+        ctx.notify('warn', `Could not pin this session: ${result.message}`);
+        return;
+    }
+    ctx.toast('info', `Session ${identity.id} pinned: aragon sessions prune will not delete it.`);
+}

package/dist/config/load.d.ts

@@ -228,6 +228,21 @@ export interface CliFlags {
     compaction?: boolean;
     /** `--compaction-threshold <0..1|N%>` — session override for `threshold`. */
     compactionThreshold?: string;
+    /**
+     * `--resume <id|path>` - continue a saved session under a NEW id
+     * (tui-session-id-resume 4).
+     *
+     * A FLAG FIELD AND NOT A CONFIG KEY (D-19). There is no persisted "always
+     * resume this session", and no switch that shows an id without writing it:
+     * that state - an id a user can copy and cannot use - is worse than having no
+     * id at all.
+     *
+     * Carried through `toFlags` like every other flag; a field that reaches only
+     * `CliFlags` is inert with no compile error and no runtime error.
+     */
+    resumeSession?: string;
+    /** `--save <id>` - name THIS run's persistent session and pin it. */
+    saveSessionAs?: string;
 }
 /**
  * Resolve the effective config by merging all layers, then derive the runtime

package/dist/config/model-profiles.d.ts

@@ -34,6 +34,14 @@ export interface ProfileValidationIssue {
 export declare function emptyModelProfiles(): ModelProfilesConfig;
 /** Return independently mutable role state. */
 export declare function emptyModelProfileState(invalid?: boolean): ModelProfilesRuntime;
+/**
+ * The endpoint rule published as a predicate (model-profile-connection-test §5 row 10).
+ *
+ * The probe's `invalid_base_url` guard has to use THE SAME ruler as validation, or a
+ * URL the editor accepts can still be refused by the test (and the reverse). A second
+ * copy of these four clauses is one edit away from disagreeing with the config layer.
+ */
+export declare function isValidEndpointUrl(value: string | null | undefined): boolean;
 /** Validate untrusted input; diagnostics never include supplied values. */
 export declare function validateModelProfiles(value: unknown): ProfileValidationIssue[];
 /**

package/dist/config/model-profiles.js

@@ -32,6 +32,16 @@ function validUrl(value) {
         return false;
     }
 }
+/**
+ * The endpoint rule published as a predicate (model-profile-connection-test §5 row 10).
+ *
+ * The probe's `invalid_base_url` guard has to use THE SAME ruler as validation, or a
+ * URL the editor accepts can still be refused by the test (and the reverse). A second
+ * copy of these four clauses is one edit away from disagreeing with the config layer.
+ */
+export function isValidEndpointUrl(value) {
+    return validUrl(value);
+}
 function validateEntry(value, index) {
     const path = `modelProfiles.entries[${index}]`;
     const invalid = (field, message) => ({

package/dist/exec/index.js

@@ -418,7 +418,16 @@ function planSession(options, cwd, err) {
     if (options.sessionId !== undefined) {
         // THE UPSERT. A wrapper that mints its own id must not have to ask whether
         // this is the first turn; that is the whole reason this form exists.
-        return { id: options.sessionId, saved: readSessionFile(sessionPathFor(options.sessionId)), saving, cwd };
+        //
+        // AND IT IS A RESUME FORM, so the same write-back rule applies (tui-session-
+        // id-resume D-20 / I-3). When a file already exists under that id,
+        // `resumedSessionId` decides which id this run writes - and for a TUI
+        // checkpoint that answer is a NEW uuid. Without this line the wrapper-friendly
+        // upsert was the one remaining way to reach a TUI checkpoint and replace it,
+        // which is silent, unrecoverable loss of the user's live conversation.
+        const path = sessionPathFor(options.sessionId);
+        const saved = readSessionFile(path);
+        return { id: saved ? resumedSessionId(path, saved) : options.sessionId, saved, saving, cwd };
     }
     return { id: randomUUID(), saved: null, saving, cwd };
 }

package/dist/logging/logger.d.ts

@@ -23,7 +23,7 @@
 import type { LogConfig } from '../config/schema.js';
 import { type LogLevelName } from './levels.js';
 /** Closed set, not free text: a typo'd scope is a record nobody can filter on. */
-export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update' | 'compaction';
+export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update' | 'compaction' | 'session' | 'branch';
 export interface LogRecord {
     ts: string;
     lv: LogLevelName;

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

@@ -0,0 +1,155 @@
+/**
+ * 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.
+ */
+/** The three ladders, collapsed from `NodeJS.Platform` (win32 / darwin / everything else). */
+export type TerminalPlatform = 'win32' | 'darwin' | 'posix';
+export interface ShellInvocation {
+    /** Executable: an absolute path or a name resolved through PATH. */
+    path: string;
+    /** Which command syntax the aragon command has to be encoded for. */
+    kind: 'powershell' | 'posix';
+}
+export interface TerminalLaunchPlan {
+    /** The program we spawn. */
+    file: string;
+    args: string[];
+    /** True only for the `cmd` rung, whose command line `cmd.exe` must see verbatim. */
+    windowsVerbatimArguments: boolean;
+    /** Ladder name, for the log and for the success toast's debug detail. */
+    rung: string;
+}
+export type TerminalPlanResult = {
+    ok: true;
+    plans: TerminalLaunchPlan[];
+    shell: ShellInvocation;
+    manual: string;
+} | {
+    ok: false;
+    reason: 'no-launcher';
+    shell: ShellInvocation;
+    manual: string;
+};
+export interface TerminalPlanInput {
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+    pathDirs: readonly string[];
+    isExecutable?: (name: string) => boolean;
+    shell: ShellInvocation;
+    /** The aragon command's argv pieces (`session/branch-invocation.ts`'s product). */
+    command: readonly string[];
+    /** New window title, ASCII, already truncated to the cell budget. */
+    title: string;
+    cwd: string;
+    /** `joinCommandLine(command)` - the pasteable fallback shown to the user. */
+    manual: string;
+}
+/** The env var that overrides the shell the new window runs (D-7). */
+export declare const ARAGON_BRANCH_SHELL_ENV = "ARAGON_BRANCH_SHELL";
+/**
+ * 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 declare function planTerminalLaunch(input: TerminalPlanInput): TerminalPlanResult;
+/** PowerShell: the whole command as one base64(UTF-16LE) blob (D-20). */
+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;
+/**
+ * `-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 declare function encodePowerShellCommand(script: string): string;
+/** POSIX single-quote escaping: `'` becomes `'\''`. */
+export declare function posixQuote(value: string): string;
+export declare function posixScript(parts: readonly string[]): string;
+/** AppleScript string literals only need `\` and `"` escaped. */
+export declare function escapeAppleScriptText(value: string): string;
+/**
+ * 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 declare function quoteWin32Arg(value: string): string;
+/** PATH entries for `name` probing: both spellings on Windows, `:` on POSIX. */
+export declare function pathDirsOf(env: Record<string, string | undefined>, platform: NodeJS.Platform): string[];
+/**
+ * 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 declare function defaultIsExecutable(platform: NodeJS.Platform, pathDirs?: readonly string[]): (name: string) => boolean;
+/**
+ * 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 declare function resolveShell(input: {
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+    isExecutable?: (name: string) => boolean;
+    pathDirs: readonly string[];
+}): ShellInvocation;
+/**
+ * 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 declare function truncateTitle(title: string, maxCells: number): string;