@phnx-labs/agents-cli 1.22.22 → 1.22.24

package/dist/commands/fork.js

@@ -3,71 +3,98 @@ import { setHelpSections } from '../lib/help.js';
 import { findSessionsById } from '../lib/session/db.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { forkSession, isForkableAgent, FORKABLE_AGENTS } from '../lib/session/fork.js';
-/** Register the top-level `agents fork` command. */
-export function registerForkCommand(program) {
-    const cmd = program
+const FORK_HELP = {
+    examples: `
+    # Fork a session by (partial) id, then continue the fork
+    agents sessions fork 4f3a9c21
+    agents sessions resume <new-id>
+
+    # Give the fork a name
+    agents sessions fork 4f3a9c21 --name "try redis instead"
+  `,
+    notes: `
+    - 'resume' continues the SAME conversation; 'fork' copies it under a new id so the two diverge.
+    - The fork is a full copy of the conversation so far; continuing it never touches the original.
+    - Resolve the session the same way as resume: an exact or prefix id fragment.
+    - Native copy currently supports: ${FORKABLE_AGENTS.join(', ')}. For other harnesses, branch by
+      starting a fresh agent and seeding it with '/continue <id>' — the source stays put.
+  `,
+};
+/**
+ * Resolve the source session, copy it under a fresh id, and print how to
+ * continue the fork. Shared by `agents sessions fork` and the `agents fork` alias.
+ */
+export async function runFork(sessionArg, options) {
+    // Resolve the source. Try the index first; only pay for a rescan if the id
+    // isn't found yet (mirrors the resume path's freshen-then-lookup).
+    let matches = findSessionsById(sessionArg, {});
+    if (matches.length === 0) {
+        await discoverSessions({});
+        matches = findSessionsById(sessionArg, {});
+    }
+    if (matches.length === 0) {
+        // Errors go to stderr and set a non-zero exit code so a script chaining on
+        // `agents sessions fork <id> && agents sessions resume <new>` doesn't proceed
+        // on a failed fork.
+        console.error(chalk.red(`No session matching "${sessionArg}".`));
+        console.error(chalk.gray('List candidates with: agents sessions'));
+        process.exitCode = 1;
+        return;
+    }
+    if (matches.length > 1) {
+        console.error(chalk.yellow(`"${sessionArg}" is ambiguous — ${matches.length} sessions match. Use a longer id:`));
+        for (const m of matches.slice(0, 8)) {
+            console.error(chalk.gray(`  ${m.shortId}  ${m.agent}  ${m.label || m.topic || ''}`));
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const source = matches[0];
+    if (!isForkableAgent(source.agent)) {
+        // A native copy needs the agent's transcript to be resumable by id; harnesses
+        // without that can still be branched by hand. Fail loud with the manual path
+        // rather than a silent no-op or a fake copy.
+        console.error(chalk.yellow(`A native fork copy isn't supported for ${source.agent} sessions yet (supported: ${FORKABLE_AGENTS.join(', ')}).`));
+        console.error(chalk.gray(`  Branch it by hand — start a fresh ${source.agent} and seed it with the source's context:`));
+        console.error(chalk.gray(`    agents run ${source.agent} --terminal   # then, in the new session:`));
+        console.error(chalk.gray(`    /continue ${source.shortId}`));
+        process.exitCode = 1;
+        return;
+    }
+    let result;
+    try {
+        result = forkSession(source, { name: options.name });
+    }
+    catch (err) {
+        console.error(chalk.red(`Could not fork ${source.shortId}: ${err.message}`));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(chalk.green(`Forked ${source.shortId} -> ${result.shortId}`));
+    console.log(chalk.gray(`  Label:    ${result.label}`));
+    console.log(chalk.gray(`  Continue: agents sessions resume ${result.shortId}`));
+    console.log(chalk.gray(`  Original ${source.shortId} is untouched.`));
+}
+/**
+ * Register `agents sessions fork <session>` — the canonical surface (fork is a
+ * session operation, so it lives under the `sessions` group).
+ */
+export function registerSessionsForkCommand(sessionsCmd) {
+    const cmd = sessionsCmd
         .command('fork <session>')
         .description('Branch a session into a new, independent copy you can continue separately. The original is untouched.')
         .option('--name <label>', 'Label for the fork (default: "fork of <original>")');
-    setHelpSections(cmd, {
-        examples: `
-      # Fork a session by (partial) id, then continue the fork
-      agents fork 4f3a9c21
-      agents resume <new-id>
-
-      # Give the fork a name
-      agents fork 4f3a9c21 --name "try redis instead"
-    `,
-        notes: `
-      - 'resume' continues the SAME conversation; 'fork' copies it under a new id so the two diverge.
-      - The fork is a full copy of the conversation so far; continuing it never touches the original.
-      - Resolve the session the same way as resume: an exact or prefix id fragment.
-      - Currently supports: ${FORKABLE_AGENTS.join(', ')}. Other agents are a planned follow-up.
-    `,
-    });
-    cmd.action(async (sessionArg, options) => {
-        // Resolve the source. Try the index first; only pay for a rescan if the id
-        // isn't found yet (mirrors the resume path's freshen-then-lookup).
-        let matches = findSessionsById(sessionArg, {});
-        if (matches.length === 0) {
-            await discoverSessions({});
-            matches = findSessionsById(sessionArg, {});
-        }
-        if (matches.length === 0) {
-            // Errors go to stderr and set a non-zero exit code so a script chaining on
-            // `agents fork <id> && agents resume <new>` doesn't proceed on a failed fork.
-            console.error(chalk.red(`No session matching "${sessionArg}".`));
-            console.error(chalk.gray('List candidates with: agents sessions'));
-            process.exitCode = 1;
-            return;
-        }
-        if (matches.length > 1) {
-            console.error(chalk.yellow(`"${sessionArg}" is ambiguous — ${matches.length} sessions match. Use a longer id:`));
-            for (const m of matches.slice(0, 8)) {
-                console.error(chalk.gray(`  ${m.shortId}  ${m.agent}  ${m.label || m.topic || ''}`));
-            }
-            process.exitCode = 1;
-            return;
-        }
-        const source = matches[0];
-        if (!isForkableAgent(source.agent)) {
-            console.error(chalk.yellow(`fork does not support ${source.agent} sessions yet.`));
-            console.error(chalk.gray(`  Supported: ${FORKABLE_AGENTS.join(', ')}.`));
-            process.exitCode = 1;
-            return;
-        }
-        let result;
-        try {
-            result = forkSession(source, { name: options.name });
-        }
-        catch (err) {
-            console.error(chalk.red(`Could not fork ${source.shortId}: ${err.message}`));
-            process.exitCode = 1;
-            return;
-        }
-        console.log(chalk.green(`Forked ${source.shortId} -> ${result.shortId}`));
-        console.log(chalk.gray(`  Label:    ${result.label}`));
-        console.log(chalk.gray(`  Continue: agents resume ${result.shortId}`));
-        console.log(chalk.gray(`  Original ${source.shortId} is untouched.`));
-    });
+    setHelpSections(cmd, FORK_HELP);
+    cmd.action(runFork);
+}
+/**
+ * Register the hidden top-level `agents fork` alias. Kept working for back-compat
+ * and muscle memory; the canonical, discoverable surface is `agents sessions fork`.
+ */
+export function registerForkCommand(program) {
+    const cmd = program
+        .command('fork <session>', { hidden: true })
+        .description('Alias for `agents sessions fork` — branch a session into a new, independent copy.')
+        .option('--name <label>', 'Label for the fork (default: "fork of <original>")');
+    cmd.action(runFork);
 }

package/dist/commands/go.d.ts

@@ -16,21 +16,46 @@
 import type { Command } from 'commander';
 import { type ActiveSession } from '../lib/session/active.js';
 import type { SessionMeta } from '../lib/session/types.js';
+import { type LiveStatusFilter } from './sessions.js';
 export declare function registerGoCommand(program: Command): void;
+/**
+ * Scope a live-session pool by device and live status. Pure so the `focus`
+ * device/status filters are unit-testable without touching the sweep. `hosts`
+ * keeps only sessions whose `machine` is in the set (local rows carry `self`,
+ * remote rows carry their peer tag); `statuses` reuses `--active`'s exact
+ * `matchesLiveStatus` derivation rather than a parallel status table.
+ */
+export declare function filterLivePool(sessions: ActiveSession[], opts?: {
+    hosts?: string[];
+    statuses?: LiveStatusFilter[];
+}): ActiveSession[];
 /**
  * Live jump targets (local + remote), keyed by session id. Cloud is excluded by
  * default (it has no local pid to attach), but `detach` opts in with
  * `includeCloud` so it can resolve a cloud id and refuse it with a clear message
  * instead of a bare "no live session".
+ *
+ * `hosts` scopes the sweep to named devices — the fan-out only dials them, and the
+ * pool is then filtered to `s.machine ∈ hosts` so a stray local row can't leak in.
+ * `statuses` narrows to the live-state words `--active` uses (orphan/crashed/…).
  */
 export declare function gatherLiveTargets(local: boolean, opts?: {
     includeCloud?: boolean;
+    hosts?: string[];
+    statuses?: LiveStatusFilter[];
 }): Promise<{
     self: string;
     activeById: Map<string, ActiveSession>;
 }>;
 /** Interactive pick over the live sessions' rich SessionMeta; returns the chosen live session. */
 export declare function pickLiveTarget(activeById: Map<string, ActiveSession>, self: string, message: string, enterHint: string): Promise<ActiveSession | null>;
+/**
+ * Multi-select over the live sessions' rich SessionMeta (same rows as
+ * `pickLiveTarget`, but a checkbox picker) — the plural sibling that lets `focus`
+ * open several sessions at once. Mirrors `sessions resume`'s `multiItemPicker`
+ * wiring; returns the chosen live sessions in pick order, or `[]` on cancel.
+ */
+export declare function pickLiveTargets(activeById: Map<string, ActiveSession>, self: string, message: string): Promise<ActiveSession[]>;
 /**
  * Map each live session to its rich SessionMeta (worktree/PR/changes/tools/tests
  * via the shared picker), reusing `discoverSessions`. Remote or unindexed live
@@ -53,6 +78,19 @@ export declare function describeWhere(s: ActiveSession, self: string): Where;
  * the session lives on another machine, else undefined.
  */
 export type UnreachableFallback = (s: ActiveSession, remote: string | undefined) => void | Promise<void>;
-/** Default (attach-only): open a login shell on the remote, or refuse locally. */
+export type AttachRailLiveness = {
+    state: 'alive';
+} | {
+    state: 'dead';
+    exitStatus?: number;
+} | {
+    state: 'missing';
+};
+/** Probe the tmux process, not just retained provenance. This is deliberately
+ * called immediately before an attach so remain-on-exit panes cannot masquerade
+ * as living agent sessions. */
+export declare function probeAttachRail(s: ActiveSession, self: string): Promise<AttachRailLiveness>;
+/** Strict attach-only fallback: no pane means no attach. Never open a shell or
+ * start recovery, because both would violate the caller's no-fork intent. */
 export declare function refuseFallback(s: ActiveSession, remote: string | undefined): Promise<void>;
 export declare function jumpTo(s: ActiveSession, self: string, fallback?: UnreachableFallback): Promise<void>;

package/dist/commands/go.js

@@ -21,12 +21,16 @@ import { getActiveSessions, findSessionFileForKind } from '../lib/session/active
 import { gatherRemoteActive } from '../lib/session/remote-active.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { deriveShortId } from '../lib/session/short-id.js';
-import { dedupeByMachineSession, mergeLocalFirst, pickSessionInteractive } from './sessions.js';
+import { dedupeByMachineSession, mergeLocalFirst, pickSessionInteractive, matchesLiveStatus, filterSessionsByQuery, formatPickerLabel, pickerColumnsFor, } from './sessions.js';
+import { buildPreview } from './sessions-picker.js';
+import { multiItemPicker } from '../lib/picker.js';
+import { isPromptCancelled } from './utils.js';
 import { focusAction } from './focus.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { attachTmux, runTmux } from '../lib/tmux/binary.js';
+import { paneExitStatus } from '../lib/tmux/session.js';
 import { getDefaultSocketPath } from '../lib/tmux/paths.js';
-import { sshStream, assertValidSshTarget, shellQuote } from '../lib/ssh-exec.js';
+import { sshExec, sshStream, assertValidSshTarget, shellQuote } from '../lib/ssh-exec.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
 const execFileAsync = promisify(execFile);
 export function registerGoCommand(program) {
@@ -40,11 +44,33 @@ export function registerGoCommand(program) {
         await focusAction(id, { local: opts.local, attachOnly: true });
     });
 }
+/**
+ * Scope a live-session pool by device and live status. Pure so the `focus`
+ * device/status filters are unit-testable without touching the sweep. `hosts`
+ * keeps only sessions whose `machine` is in the set (local rows carry `self`,
+ * remote rows carry their peer tag); `statuses` reuses `--active`'s exact
+ * `matchesLiveStatus` derivation rather than a parallel status table.
+ */
+export function filterLivePool(sessions, opts = {}) {
+    let out = sessions;
+    if (opts.hosts?.length) {
+        const set = new Set(opts.hosts);
+        out = out.filter((s) => !!s.machine && set.has(s.machine));
+    }
+    if (opts.statuses?.length) {
+        out = out.filter((s) => opts.statuses.some((status) => matchesLiveStatus(s, status)));
+    }
+    return out;
+}
 /**
  * Live jump targets (local + remote), keyed by session id. Cloud is excluded by
  * default (it has no local pid to attach), but `detach` opts in with
  * `includeCloud` so it can resolve a cloud id and refuse it with a clear message
  * instead of a bare "no live session".
+ *
+ * `hosts` scopes the sweep to named devices — the fan-out only dials them, and the
+ * pool is then filtered to `s.machine ∈ hosts` so a stray local row can't leak in.
+ * `statuses` narrows to the live-state words `--active` uses (orphan/crashed/…).
  */
 export async function gatherLiveTargets(local, opts = {}) {
     const self = machineId();
@@ -55,11 +81,12 @@ export async function gatherLiveTargets(local, opts = {}) {
     let active = localActive;
     if (!local) {
         try {
-            const remote = await gatherRemoteActive();
+            const remote = await gatherRemoteActive(opts.hosts);
             active = dedupeByMachineSession([...localActive, ...remote.sessions]);
         }
         catch { /* remote sweep is best-effort */ }
     }
+    active = filterLivePool(active, { hosts: opts.hosts, statuses: opts.statuses });
     const activeById = new Map();
     for (const s of active) {
         if (!s.sessionId)
@@ -80,6 +107,41 @@ export async function pickLiveTarget(activeById, self, message, enterHint) {
         return null;
     return activeById.get(picked.session.id) ?? null;
 }
+/**
+ * Multi-select over the live sessions' rich SessionMeta (same rows as
+ * `pickLiveTarget`, but a checkbox picker) — the plural sibling that lets `focus`
+ * open several sessions at once. Mirrors `sessions resume`'s `multiItemPicker`
+ * wiring; returns the chosen live sessions in pick order, or `[]` on cancel.
+ */
+export async function pickLiveTargets(activeById, self, message) {
+    const pool = await buildLivePool(activeById, self);
+    if (pool.length === 0)
+        return [];
+    // gutter: 6 = the multi-select cursor + checkbox ('> [x] ') multiItemPicker prepends.
+    const cols = { ...pickerColumnsFor(pool), gutter: 6 };
+    let chosen;
+    try {
+        chosen = await multiItemPicker({
+            message,
+            items: pool,
+            filter: (q) => (q.trim() ? filterSessionsByQuery(pool, q) : pool),
+            labelFor: (s, q) => formatPickerLabel(s, q, cols),
+            keyFor: (s) => s.id,
+            buildPreview,
+            pageSize: 15,
+            emptyMessage: 'No live sessions match.',
+            enterHint: 'focus',
+        });
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return [];
+        throw err;
+    }
+    if (!chosen)
+        return [];
+    return chosen.map((m) => activeById.get(m.id)).filter((s) => !!s);
+}
 /**
  * Map each live session to its rich SessionMeta (worktree/PR/changes/tools/tests
  * via the shared picker), reusing `discoverSessions`. Remote or unindexed live
@@ -147,15 +209,48 @@ export function describeWhere(s, self) {
         return { label: `${s.host ?? 'shell'} on ${remote}`, action: `open a shell on ${remote}` };
     return { label: s.host ?? 'unknown terminal', action: 'resume it (no live attach rail)' };
 }
-/** Default (attach-only): open a login shell on the remote, or refuse locally. */
+/** Probe the tmux process, not just retained provenance. This is deliberately
+ * called immediately before an attach so remain-on-exit panes cannot masquerade
+ * as living agent sessions. */
+export async function probeAttachRail(s, self) {
+    const mux = s.provenance?.mux;
+    if (mux?.kind !== 'tmux' || !mux.pane)
+        return { state: 'missing' };
+    const remote = s.machine && s.machine !== self ? s.machine : undefined;
+    if (!remote) {
+        const pane = await paneExitStatus(mux.pane, mux.socket ?? getDefaultSocketPath());
+        if (!pane.found)
+            return { state: 'missing' };
+        return pane.dead ? { state: 'dead', exitStatus: pane.status } : { state: 'alive' };
+    }
+    assertValidSshTarget(remote);
+    const sock = mux.socket ? `-S ${shellQuote(mux.socket)} ` : '';
+    const pane = shellQuote(mux.pane);
+    const command = `v=$(tmux ${sock}display-message -pt ${pane} -p '#{pane_dead} #{pane_dead_status}' 2>/dev/null) || { echo missing; exit 0; }; ` +
+        `printf '%s\\n' "$v"`;
+    const result = sshExec(remote, command, { timeoutMs: 15_000, multiplex: true });
+    if (result.code !== 0)
+        return { state: 'missing' };
+    const value = result.stdout.trim();
+    if (value === 'missing' || !value)
+        return { state: 'missing' };
+    const [dead, rawStatus] = value.split(/\s+/);
+    const exitStatus = Number.parseInt(rawStatus ?? '', 10);
+    return dead === '1'
+        ? { state: 'dead', exitStatus: Number.isFinite(exitStatus) ? exitStatus : undefined }
+        : { state: 'alive' };
+}
+/** Strict attach-only fallback: no pane means no attach. Never open a shell or
+ * start recovery, because both would violate the caller's no-fork intent. */
 export async function refuseFallback(s, remote) {
     if (remote) {
-        console.log(chalk.yellow(`${shortId(s)} on ${remote} isn't inside tmux — opening a shell on ${remote} instead.`));
-        assertValidSshTarget(remote);
-        process.exit(sshStream(remote, 'exec "${SHELL:-/bin/sh}" -l', { tty: true }));
+        console.log(chalk.yellow(`Can't attach ${shortId(s)} on ${remote} — it has no living tmux pane.`));
+        process.exitCode = 1;
+        return;
     }
     console.log(chalk.yellow(`Can't jump to ${shortId(s)} — it's in ${s.host ?? 'an unknown terminal'} with no attach rail (not tmux/Ghostty).`) +
         chalk.gray(`\nTry: agents sessions resume ${shortId(s)}`));
+    process.exitCode = 1;
 }
 export async function jumpTo(s, self, fallback = refuseFallback) {
     const remote = s.machine && s.machine !== self ? s.machine : undefined;
@@ -163,6 +258,11 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
     // Path C: remote tmux — ssh in and attach, resolving the pane's session on the remote.
     if (remote) {
         if (mux?.kind === 'tmux' && mux.pane) {
+            const liveness = await probeAttachRail(s, self);
+            if (liveness.state !== 'alive') {
+                await fallback(s, remote);
+                return;
+            }
             assertValidSshTarget(remote);
             const sock = mux.socket ? `-S ${shellQuote(mux.socket)} ` : '';
             const p = shellQuote(mux.pane);
@@ -179,6 +279,11 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
     }
     // Path B: local tmux — attach (or switch-client if we're already inside tmux).
     if (mux?.kind === 'tmux' && mux.pane) {
+        const liveness = await probeAttachRail(s, self);
+        if (liveness.state !== 'alive') {
+            await fallback(s, undefined);
+            return;
+        }
         const socket = mux.socket ?? getDefaultSocketPath();
         const { session, window } = await resolveLocalPane(socket, mux.pane);
         if (session && window != null) {

package/dist/commands/harness-wizard.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Shared interactive step engine for `agents harness` create + edit.
+ *
+ * A single engine drives BOTH the create wizard (`agents harness add`/`fork`,
+ * previously `runHarnessWizard`) and the new edit wizard (`agents harness edit`,
+ * which was flag-only before). A "step" is a self-contained unit — decide whether
+ * it runs for the current draft, then prompt/validate/apply — so the two modes
+ * differ only in their step list, not in the runner.
+ *
+ * Design goals (RUSH-2219, parent RUSH-2218):
+ *   - One runner, two modes. `create` builds a new harness from a source; `edit`
+ *     loads an existing profile and re-asks each field pre-filled with its value.
+ *   - Every step is skippable. A flag that already supplied the value pre-fills
+ *     the draft and its step is not re-asked — so non-interactive scripting via
+ *     flags is unchanged and the wizard only asks for what is missing.
+ *   - Pure and injectable. The engine talks to the user through {@link WizardIO},
+ *     an injected seam. Tests drive a scripted fake IO and assert which steps ran,
+ *     with no TTY. {@link defaultWizardIO} is the production driver over
+ *     `@inquirer/prompts`.
+ *   - Typed extension points, not stubs. The three sibling subtasks plug in via
+ *     {@link WizardHooks} without editing the engine: RUSH-2220 (model catalog +
+ *     secrets surface) via `pickModel`, RUSH-2221 (connection test) via
+ *     `connectionTest`, RUSH-2222 (edit matrix) via `editable`. Each hook is a
+ *     real no-op extension point — absent, the scaffold falls back to today's
+ *     behavior (free-text model, no test, resolver-sourced editability). None of
+ *     them fakes a result. RUSH-2223 (cross-host portability, `fork --to-host`)
+ *     extends the create source step; the seam is `HarnessDraft.toHost`.
+ */
+import type { AgentId } from '../lib/types.js';
+import { type Profile } from '../lib/profiles.js';
+/** Whether the wizard is creating a new harness or editing an existing one. */
+export type WizardMode = 'create' | 'edit';
+/** A single `select` choice. `disabled` greys the row (used by the edit matrix). */
+export interface WizardChoice<T> {
+    name: string;
+    value: T;
+    disabled?: boolean | string;
+}
+/**
+ * The prompt seam the engine drives. Injected so the engine is testable with no
+ * TTY: the production implementation ({@link defaultWizardIO}) wraps
+ * `@inquirer/prompts`; a test passes a scripted fake that records calls and
+ * returns canned answers.
+ */
+export interface WizardIO {
+    select<T>(opts: {
+        message: string;
+        choices: WizardChoice<T>[];
+        default?: T;
+    }): Promise<T>;
+    input(opts: {
+        message: string;
+        default?: string;
+        validate?: (v: string) => true | string;
+    }): Promise<string>;
+    password(opts: {
+        message: string;
+    }): Promise<string>;
+    confirm(opts: {
+        message: string;
+        default?: boolean;
+    }): Promise<boolean>;
+    /** Emit an informational line — a disabled field's reason, or a preset note. */
+    note(message: string): void;
+}
+/**
+ * The mutable draft threaded through every step. It is a superset of both modes'
+ * fields; a step reads what it needs and records its answer here. `create` maps
+ * the finished draft into `{ source, name, opts }` for `runForkFlow`; `edit` maps
+ * it into the `EditOptions` shape the flag-driven edit path already persists — so
+ * a wizard-built and a hand-written harness are byte-identical after save.
+ */
+export interface HarnessDraft {
+    readonly mode: WizardMode;
+    /** create: the fork source (a native agent id or an existing harness name). */
+    source?: string;
+    /** The resolved host CLI — drives the editability seams. edit: the profile host. */
+    host?: AgentId;
+    name?: string;
+    model?: string;
+    baseUrl?: string;
+    authProvider?: string;
+    /** `<bundle>` or `<bundle>:<key>` — a value copied out of an agents secrets bundle. */
+    fromSecrets?: string;
+    version?: string;
+    description?: string;
+    fallbackModel?: string;
+    /** edit: the profile being edited, providing current values. Read-only. */
+    readonly original?: Profile;
+    /**
+     * RUSH-2223 seam (cross-host portability): the target host to re-key a cloned
+     * harness onto (`fork --to-host <host>`). The scaffold never sets it; the
+     * portability subtask reads it in an extended source step. Left here so the
+     * draft shape is stable when that lands.
+     */
+    toHost?: AgentId;
+    /** The user chose "build custom" over a preset (create only). */
+    custom?: boolean;
+    /** The preset a create run selected, if any. */
+    preset?: string;
+    /** Pre-computed default for the name prompt (source or preset name). */
+    defaultName?: string;
+    /** The provider step has run (distinguishes "no auth chosen" from "not asked"). */
+    providerAsked?: boolean;
+}
+/**
+ * What the engine does with a step for a given draft:
+ *   - `'run'`             prompt the user, validate, and apply into the draft.
+ *   - `'skip'`            value already supplied (by a flag) or step N/A — silent.
+ *   - `{ disabled: … }`   the step does not apply to this host; surface the reason
+ *                         (the field reads as greyed/disabled) but do not prompt.
+ *                         This is the seam the edit matrix (RUSH-2222) drives.
+ */
+export type StepDecision = 'run' | 'skip' | {
+    disabled: string;
+};
+/** One wizard step: decide, then (only when decided `'run'`) prompt + apply. */
+export interface WizardStep {
+    readonly id: string;
+    decide(draft: HarnessDraft): StepDecision;
+    run(io: WizardIO, draft: HarnessDraft, hooks: WizardHooks): Promise<void>;
+}
+/** Per-host editability — which params this host's API format lets you change. */
+export interface HarnessEditable {
+    model: boolean;
+    baseUrl: boolean;
+    auth: boolean;
+    version: boolean;
+    fallback: boolean;
+}
+/**
+ * Resolver-sourced editability, the scaffold default behind the RUSH-2222 seam.
+ * Every field is read from the same maps the run-time resolver uses
+ * (`baseUrlEnvKeyForHost` / `authEnvKeyForHost` / `isSelfUpdatingAgent`), never a
+ * table hardcoded alongside them — so the wizard's enable/disable can never drift
+ * from what a run actually honors (repo rule: the capability table stays truthful,
+ * in lockstep with the code). RUSH-2222 may replace this via {@link WizardHooks.editable}
+ * to add per-param reasons; it must stay sourced from the resolver.
+ */
+export declare function defaultEditable(host: AgentId): HarnessEditable;
+/** Outcome of a connection test (RUSH-2221 fills the real classifier). */
+export interface ConnectionTestResult {
+    ok: boolean;
+    /** Machine-readable class when it failed (auth / endpoint / model / unknown). */
+    reason?: 'auth' | 'endpoint' | 'model' | 'unknown';
+    message?: string;
+}
+/**
+ * Extension points the sibling subtasks fill without touching the engine. Each is
+ * a real no-op-by-default seam: absent, the scaffold uses today's behavior; none
+ * fabricates a result.
+ */
+export interface WizardHooks {
+    /**
+     * RUSH-2220 — model catalog pick. Given the resolved host (+ version and the
+     * current value in edit), return a chosen model id, or `null` to fall through
+     * to the free-text prompt. Absent → always free-text (today's behavior).
+     */
+    pickModel?: (io: WizardIO, host: AgentId | undefined, version: string | undefined, current: string | undefined) => Promise<string | null>;
+    /**
+     * RUSH-2221 — connection test after configure, before save. Absent → no test
+     * (the wizard saves without one, exactly as today).
+     */
+    connectionTest?: (draft: HarnessDraft) => Promise<ConnectionTestResult>;
+    /**
+     * RUSH-2222 — per-host editability matrix. Absent → {@link defaultEditable}.
+     */
+    editable?: (host: AgentId) => HarnessEditable;
+}
+/** Resolve the host CLI a fork `source` runs under (the host `buildFork` will use). */
+export declare function hostForSource(source: string | undefined): AgentId | undefined;
+/**
+ * The engine. Walk the steps in order; for each, ask `decide` what to do, then
+ * prompt only when it says `'run'`. A `{ disabled }` decision surfaces the reason
+ * and moves on; `'skip'` is silent. Returns the finished draft.
+ */
+export declare function runWizardSteps(steps: WizardStep[], draft: HarnessDraft, io: WizardIO, hooks?: WizardHooks): Promise<HarnessDraft>;
+/**
+ * The create step list — the shape of `agents harness add`/`fork`. Faithful to
+ * the previous `runHarnessWizard` sequence (source → preset|custom → model →
+ * provider → base URL → name → key source), re-expressed as engine steps so the
+ * sibling subtasks can gate/replace individual steps. Produces the same
+ * `{ source, name, opts }` draft the fork flow already persists.
+ */
+export declare function createSteps(): WizardStep[];
+/**
+ * The edit step list — `agents harness edit <name>` with no flags on a TTY. Each
+ * step is pre-filled with the profile's current value and gated by the host's
+ * editability matrix (RUSH-2222 seam): an unsupported param reads as disabled with
+ * a reason instead of being silently accepted. Records into the same draft, which
+ * `runEditWizard` maps to the `EditOptions` shape the flag path already persists.
+ */
+export declare function editSteps(original: Profile): WizardStep[];
+/**
+ * Run the connection-test hook against a finished draft, if one is wired
+ * (RUSH-2221). Returns `null` when no hook is present (no test performed) so the
+ * caller can distinguish "not tested" from "tested and passed". Separated from the
+ * step list because the test needs the assembled profile, which the caller builds.
+ */
+export declare function runConnectionTest(draft: HarnessDraft, hooks: WizardHooks): Promise<ConnectionTestResult | null>;
+/**
+ * Production {@link WizardIO} over `@inquirer/prompts`, lazy-imported so the
+ * dependency loads only when a wizard actually runs. `note` prints to stderr so it
+ * never contaminates a `--json`/piped stdout.
+ */
+export declare function defaultWizardIO(): Promise<WizardIO>;