@phnx-labs/agents-cli 1.20.27 → 1.20.29

package/dist/lib/exec.js

@@ -261,10 +261,12 @@ export const AGENT_COMMANDS = {
         modelFlag: '--model',
         printFlags: ['--print'],
         verboseFlag: '--verbose',
+        resume: { flag: '--resume' },
     },
     codex: {
         base: ['codex', 'exec'],
         promptFlag: 'positional',
+        resume: { subcommand: 'resume' },
         modeFlags: {
             // NOTE: codex has no read-only mode in --sandbox; 'plan' here means
             // "workspace-write but no auto-approval" — closer to plan-as-restraint.
@@ -302,6 +304,9 @@ export const AGENT_COMMANDS = {
     opencode: {
         base: ['opencode', 'run'],
         promptFlag: 'positional',
+        // opencode's native resume is `opencode --session <id>` (NOT under `run`), so
+        // it does not compose with this headless `run` base. Until that's verified on
+        // a box with opencode installed, opencode resumes via Tier-2 `/continue`.
         modeFlags: {
             plan: ['--agent', 'plan'],
             edit: ['--agent', 'build'],
@@ -436,6 +441,14 @@ export const AGENT_COMMANDS = {
         modelFlag: '-m',
     },
 };
+/**
+ * Whether `agent` has a native resume form (Tier 1). Derived solely from the
+ * command template's `resume` field — the single source of truth. Agents that
+ * return false resume via the universal Tier-2 `/continue` replay instead.
+ */
+export function nativeResume(agent) {
+    return AGENT_COMMANDS[agent]?.resume !== undefined;
+}
 /** Assemble the full CLI argument array for an agent invocation. */
 export function buildExecCommand(options) {
     const template = AGENT_COMMANDS[options.agent];
@@ -453,30 +466,36 @@ export function buildExecCommand(options) {
             cmd.splice(1, 1);
         }
     }
+    // Native resume with a `{ subcommand }` shape (codex) appends the resume verb
+    // to the base: `codex exec` -> `codex exec resume` (headless) and, after the
+    // interactive drop above, `codex` -> `codex resume` (TUI). The session id is
+    // pushed later as the first positional (before any prompt). `{ flag }` agents
+    // (claude) need no base change — the flag is appended with the id below.
+    const resumeSpec = options.resume ? template.resume : undefined;
+    if (resumeSpec && 'subcommand' in resumeSpec) {
+        cmd.push(resumeSpec.subcommand);
+    }
     // Use versioned alias if a specific version was requested (e.g., claude@2.1.98).
     // Resolve to the absolute path of the shim so spawn doesn't depend on PATH —
     // on Linux installs where the shims dir isn't on PATH, spawning the bare
     // versioned name fails with ENOENT even though `agents view` shows the agent.
     //
-    // On Windows, shims are bash scripts and cannot be executed by spawn() directly.
-    // buildExecEnv() already sets the isolation env vars (CLAUDE_CONFIG_DIR, CODEX_HOME,
-    // etc.) that the bash shim would set, so we can skip the shim entirely and resolve
-    // straight to the real binary via getBinaryPath.
+    // On Windows the shims dir holds a `.cmd` companion next to the bash alias
+    // (see createVersionedAlias); prefer it so spawn() can launch it (the bash
+    // script is not directly executable by cmd.exe). When no shim exists on disk
+    // we fall back to the bare versioned name, which spawnAgent() resolves via
+    // PATH (+ PATHEXT/shell on Windows).
     if (options.version && cmd.length > 0) {
-        if (process.platform === 'win32') {
-            const binaryPath = getBinaryPath(options.agent, options.version);
-            const binaryPathCmd = binaryPath + '.cmd';
-            if (fs.existsSync(binaryPathCmd)) {
-                cmd[0] = binaryPathCmd;
-            }
-            else if (fs.existsSync(binaryPath)) {
-                cmd[0] = binaryPath;
-            }
+        const versionedName = `${cmd[0]}@${options.version}`;
+        const absPath = path.join(getShimsDir(), versionedName);
+        if (process.platform === 'win32' && fs.existsSync(absPath + '.cmd')) {
+            cmd[0] = absPath + '.cmd';
+        }
+        else if (fs.existsSync(absPath)) {
+            cmd[0] = absPath;
         }
         else {
-            const versionedName = `${cmd[0]}@${options.version}`;
-            const absPath = path.join(getShimsDir(), versionedName);
-            cmd[0] = fs.existsSync(absPath) ? absPath : versionedName;
+            cmd[0] = versionedName;
         }
     }
     // Add reasoning effort flags (before mode flags for codex -c positioning)
@@ -505,15 +524,39 @@ export function buildExecCommand(options) {
         // AGENT_COMMANDS.modeFlags drifted apart. Tests assert they agree.
         throw new Error(`Internal error: ${options.agent} declares '${resolvedMode}' in capabilities.modes but has no entry in AGENT_COMMANDS.modeFlags.${resolvedMode}.`);
     }
-    cmd.push(...modeFlags);
+    if (resumeSpec && 'subcommand' in resumeSpec) {
+        // codex `exec resume` / `resume` does NOT accept `--sandbox <mode>` (only the
+        // bypass flag, verified against `codex exec resume --help`). So the standard
+        // codex modeFlags can't be reused on resume. A non-plan HEADLESS resume needs
+        // the bypass or it stalls on approval prompts; plan and interactive resume
+        // inherit codex's default sandbox and pass no flag.
+        if (!interactive && resolvedMode !== 'plan') {
+            cmd.push('--dangerously-bypass-approvals-and-sandbox');
+        }
+    }
+    else {
+        cmd.push(...modeFlags);
+    }
     // Add print/headless flags only when a prompt is provided. Without a prompt
     // the caller wants an interactive REPL -- passing --print would immediately
     // wait on stdin and never render the TUI.
     if (!interactive && options.headless && template.printFlags) {
         cmd.push(...template.printFlags);
     }
-    // Add session ID (Claude only)
-    if (options.sessionId && options.agent === 'claude') {
+    // Resume vs. create. With `resume`, emit the agent's NATIVE resume reference:
+    // `{ flag }` agents append `<flag> <id>` (claude `--resume <id>`); `{ subcommand }`
+    // agents (codex) already pushed the verb above, so the id is the first
+    // positional here — placed before the prompt positional appended later. Without
+    // `resume`, the legacy claude-only `--session-id` CREATES a session with that id.
+    if (options.resume && options.sessionId && resumeSpec) {
+        if ('flag' in resumeSpec) {
+            cmd.push(resumeSpec.flag, options.sessionId);
+        }
+        else {
+            cmd.push(options.sessionId);
+        }
+    }
+    else if (options.sessionId && options.agent === 'claude') {
         cmd.push('--session-id', options.sessionId);
     }
     // Add model (only if explicitly provided by user)

package/dist/lib/hooks.d.ts

@@ -144,6 +144,23 @@ export declare function unmanagedHookNames(installedHookNames: string[], manifes
  * shadow/override warnings the registrar path prints.
  */
 export declare function listUnmanagedHooksInVersionHome(agent: AgentId, version: string): string[];
+/**
+ * Compute the trust hash Codex expects for a single command hook handler, so
+ * agents-cli can pre-trust the hooks it registers. Without a matching
+ * trusted_hash in [hooks.state], Codex classifies the hook Untrusted and
+ * silently drops it in non-interactive (`codex exec`) mode where there is no
+ * TUI prompt to approve it.
+ *
+ * Mirrors command_hook_hash() in codex-rs/hooks/src/engine/discovery.rs +
+ * version_for_toml() in codex-rs/config/src/fingerprint.rs:
+ *   sha256( canonicalJson( NormalizedHookIdentity ) ) prefixed with "sha256:".
+ *
+ * The identity passes through TOML on the Codex side, which drops None fields
+ * (commandWindows, statusMessage, and matcher when absent). `async` is always
+ * false (async hooks are not yet supported) and is always present. `timeout`
+ * is normalized to >= 1 (Codex: unwrap_or(600).max(1)).
+ */
+export declare function computeCodexHookTrustHash(eventKeyLabel: string, command: string, timeout: number, matcher: string | undefined): string;
 export declare function registerHooksToSettings(agentId: AgentId, versionHome: string, hookManifest?: Record<string, ManifestHook>, agentsDirOverride?: string): {
     registered: string[];
     errors: string[];

package/dist/lib/hooks.js

@@ -7,6 +7,7 @@
  * parsing those manifests, registering hooks into agent-native settings files,
  * and syncing them across version switches.
  */
+import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -148,6 +149,12 @@ const NON_SCRIPT_EXTENSIONS = new Set([
     '.md', '.markdown', '.rst', '.txt',
     '.yaml', '.yml', '.json', '.toml', '.ini', '.conf',
 ]);
+// Documentation siblings of a hook (e.g. `git-guard.md` next to `git-guard.sh`)
+// are human-readable docs the hook never reads at runtime — NOT a data sidecar.
+// Treating them as the hook's `dataFile` made the installer's correct omission
+// of docs look like perpetual drift in `agents doctor` that no sync could fix.
+// Structured siblings (.yaml/.json/.toml/...) remain valid data files.
+const DOC_EXTENSIONS = new Set(['.md', '.markdown', '.rst']);
 const SCRIPT_EXTENSIONS = new Set([
     '.sh',
     '.bash',
@@ -261,7 +268,7 @@ export function listHookEntriesFromDir(dir) {
             group.find((f) => f.isExec && !NON_SCRIPT_EXTENSIONS.has(f.ext.toLowerCase()));
         if (!script)
             continue;
-        const data = group.find((f) => f !== script);
+        const data = group.find((f) => f !== script && !DOC_EXTENSIONS.has(f.ext.toLowerCase()));
         entries.push({
             name: base,
             scriptPath: script.fullPath,
@@ -763,6 +770,71 @@ export function listUnmanagedHooksInVersionHome(agent, version) {
 // Codex events that support a matcher field (matches tool name or session type).
 // UserPromptSubmit and Stop never include a matcher.
 const CODEX_MATCHER_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'SessionStart']);
+// Maps PascalCase hook event names (as written in hooks.json) to the
+// snake_case labels Codex uses in its persisted [hooks.state] keys.
+// Mirrors hook_event_key_label() in codex-rs/hooks/src/lib.rs.
+const CODEX_EVENT_KEY_LABELS = {
+    PreToolUse: 'pre_tool_use',
+    PermissionRequest: 'permission_request',
+    PostToolUse: 'post_tool_use',
+    PreCompact: 'pre_compact',
+    PostCompact: 'post_compact',
+    SessionStart: 'session_start',
+    UserPromptSubmit: 'user_prompt_submit',
+    SubagentStart: 'subagent_start',
+    SubagentStop: 'subagent_stop',
+    Stop: 'stop',
+};
+// Recursively sort object keys alphabetically at every level, mirroring
+// canonical_json() in codex-rs/config/src/fingerprint.rs. Codex hashes the
+// canonical JSON form so trust survives key-order differences.
+function canonicalizeForHash(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalizeForHash);
+    }
+    if (value && typeof value === 'object') {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = canonicalizeForHash(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+/**
+ * Compute the trust hash Codex expects for a single command hook handler, so
+ * agents-cli can pre-trust the hooks it registers. Without a matching
+ * trusted_hash in [hooks.state], Codex classifies the hook Untrusted and
+ * silently drops it in non-interactive (`codex exec`) mode where there is no
+ * TUI prompt to approve it.
+ *
+ * Mirrors command_hook_hash() in codex-rs/hooks/src/engine/discovery.rs +
+ * version_for_toml() in codex-rs/config/src/fingerprint.rs:
+ *   sha256( canonicalJson( NormalizedHookIdentity ) ) prefixed with "sha256:".
+ *
+ * The identity passes through TOML on the Codex side, which drops None fields
+ * (commandWindows, statusMessage, and matcher when absent). `async` is always
+ * false (async hooks are not yet supported) and is always present. `timeout`
+ * is normalized to >= 1 (Codex: unwrap_or(600).max(1)).
+ */
+export function computeCodexHookTrustHash(eventKeyLabel, command, timeout, matcher) {
+    const handler = {
+        type: 'command',
+        command,
+        timeout: Math.max(timeout, 1),
+        async: false,
+    };
+    const identity = {
+        event_name: eventKeyLabel,
+        hooks: [handler],
+    };
+    if (matcher !== undefined && matcher !== '') {
+        identity.matcher = matcher;
+    }
+    const canonical = canonicalizeForHash(identity);
+    const hex = crypto.createHash('sha256').update(JSON.stringify(canonical), 'utf-8').digest('hex');
+    return `sha256:${hex}`;
+}
 /**
  * Register hooks as lifecycle events in an agent's config.
  * Reads hooks.yaml manifest, merges into the agent's config file(s).
@@ -1075,7 +1147,11 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
         errors.push(`Failed to write hooks.json: ${err.message}`);
         return { registered, errors };
     }
-    // Ensure [features] codex_hooks = true in config.toml
+    // Ensure [features] hooks = true and pre-trust every registered hook in
+    // config.toml. Codex only runs hooks that are enabled AND trusted; in
+    // non-interactive (`codex exec`) mode there is no TUI prompt to approve
+    // them, so an untrusted hook is silently dropped. We compute the same
+    // trust hash Codex would and persist it under [hooks.state].
     try {
         let tomlConfig = {};
         if (fs.existsSync(configPath)) {
@@ -1087,7 +1163,55 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
         if (!tomlConfig.features || typeof tomlConfig.features !== 'object') {
             tomlConfig.features = {};
         }
-        tomlConfig.features.codex_hooks = true;
+        // Codex 0.116+ feature flag is `hooks` (the legacy `codex_hooks` name is
+        // an unrecognized key that triggers a deprecation error and is ignored).
+        const features = tomlConfig.features;
+        delete features.codex_hooks;
+        features.hooks = true;
+        // Pre-trust hooks. The [hooks.state] key is keyed by the hooks.json path
+        // exactly as Codex resolves it (the absolute CODEX_HOME path), the
+        // snake_case event label, and the per-event group/handler indices — which
+        // must match Codex's parse order, so we iterate the just-written
+        // hooksFile structure in array order.
+        if (!tomlConfig.hooks || typeof tomlConfig.hooks !== 'object') {
+            tomlConfig.hooks = {};
+        }
+        const hooksTable = tomlConfig.hooks;
+        const existingState = hooksTable.state && typeof hooksTable.state === 'object'
+            ? hooksTable.state
+            : {};
+        const hookState = {};
+        for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {
+            const eventKeyLabel = CODEX_EVENT_KEY_LABELS[event];
+            if (!eventKeyLabel)
+                continue;
+            eventGroups.forEach((group, groupIdx) => {
+                if (!group.hooks)
+                    return;
+                group.hooks.forEach((handler, handlerIdx) => {
+                    if (handler.type !== 'command')
+                        return;
+                    const key = `${hooksPath}:${eventKeyLabel}:${groupIdx}:${handlerIdx}`;
+                    const trustedHash = computeCodexHookTrustHash(eventKeyLabel, handler.command, handler.timeout, group.matcher);
+                    // Preserve a user's explicit `enabled = false` for this exact hook;
+                    // only (re)write the trust hash.
+                    const prior = existingState[key];
+                    const entry = { trusted_hash: trustedHash };
+                    if (prior && prior.enabled === false) {
+                        entry.enabled = false;
+                    }
+                    hookState[key] = entry;
+                });
+            });
+        }
+        // Carry forward trust state for any hooks we did not (re)register this
+        // pass — e.g. user-added hooks under a different command path.
+        for (const [key, entry] of Object.entries(existingState)) {
+            if (!(key in hookState)) {
+                hookState[key] = entry;
+            }
+        }
+        hooksTable.state = hookState;
         fs.writeFileSync(configPath, TOML.stringify(tomlConfig), 'utf-8');
     }
     catch (err) {

package/dist/lib/hosts/dispatch.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Dispatch a headless agent run onto a host over SSH.
+ *
+ * The run is launched detached (`nohup … &`) writing combined output to a remote
+ * log and its exit code to a sibling `.exit` file, so progress survives a dropped
+ * connection (followed via offset-tail in progress.ts). This is the offload win:
+ * the agent's process/thread/file fan-out happens on the host, not the laptop.
+ */
+import type { Host } from './types.js';
+import { type HostTask } from './tasks.js';
+export interface DispatchOptions {
+    agent: string;
+    prompt: string;
+    mode?: string;
+    model?: string;
+    remoteCwd?: string;
+    /** Stream progress and block until completion (default true). */
+    follow?: boolean;
+    timeoutMs?: number;
+}
+export interface DispatchResult {
+    task: HostTask;
+    /** Exit code when followed; undefined when detached (--no-follow). */
+    exitCode?: number;
+}
+export declare function dispatchToHost(host: Host, opts: DispatchOptions): Promise<DispatchResult>;

package/dist/lib/hosts/dispatch.js

@@ -0,0 +1,71 @@
+/**
+ * Dispatch a headless agent run onto a host over SSH.
+ *
+ * The run is launched detached (`nohup … &`) writing combined output to a remote
+ * log and its exit code to a sibling `.exit` file, so progress survives a dropped
+ * connection (followed via offset-tail in progress.ts). This is the offload win:
+ * the agent's process/thread/file fan-out happens on the host, not the laptop.
+ */
+import { randomUUID } from 'crypto';
+import { sshExec, shellQuote } from '../ssh-exec.js';
+import { sshTargetFor } from './types.js';
+import { ensureHostReady } from './ready.js';
+import { saveTask, updateTask } from './tasks.js';
+import { followHostTask } from './progress.js';
+// Use $HOME (not ~) so the path is correct whether or not it's quoted and
+// regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
+// injection-safe to interpolate unquoted into remote commands.
+const REMOTE_DIR = '$HOME/.agents/.cache/hosts';
+export async function dispatchToHost(host, opts) {
+    const target = sshTargetFor(host);
+    const { warnings } = ensureHostReady(host, { agent: opts.agent });
+    for (const w of warnings)
+        process.stderr.write(`[hosts] warning: ${w}\n`);
+    const id = randomUUID().slice(0, 8);
+    const remoteLog = `${REMOTE_DIR}/${id}.log`;
+    const remoteExit = `${REMOTE_DIR}/${id}.exit`;
+    // Inner command run under a login shell so PATH resolves `agents`.
+    const runParts = ['agents', 'run', shellQuote(opts.agent), shellQuote(opts.prompt), '--quiet'];
+    if (opts.mode)
+        runParts.push('--mode', shellQuote(opts.mode));
+    if (opts.model)
+        runParts.push('--model', shellQuote(opts.model));
+    const cwd = opts.remoteCwd ? `cd ${shellQuote(opts.remoteCwd)} && ` : '';
+    const inner = `${cwd}${runParts.join(' ')} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
+    // Outer: ensure dir, launch detached under bash -lc, print the PID.
+    const launch = `mkdir -p ${REMOTE_DIR}; nohup bash -lc ${shellQuote(inner)} >/dev/null 2>&1 & echo $!`;
+    const res = sshExec(target, launch, { timeoutMs: 30000 });
+    if (res.code !== 0) {
+        throw new Error(`Failed to launch on "${host.name}": ${(res.stderr || res.stdout).trim() || 'ssh error'}`);
+    }
+    const pid = parseInt(res.stdout.trim().split('\n').pop() ?? '', 10);
+    const task = {
+        id,
+        host: host.name,
+        target,
+        agent: opts.agent,
+        prompt: opts.prompt,
+        pid: Number.isFinite(pid) ? pid : undefined,
+        remoteLog,
+        remoteExit,
+        status: 'running',
+        createdAt: new Date().toISOString(),
+    };
+    saveTask(task);
+    if (opts.follow === false) {
+        return { task };
+    }
+    const exitCode = await followHostTask(target, {
+        remoteLog,
+        remoteExit,
+        taskId: id,
+        echo: true,
+        timeoutMs: opts.timeoutMs,
+    });
+    const finished = updateTask(id, {
+        status: exitCode === 0 ? 'completed' : exitCode === -1 ? 'unknown' : 'failed',
+        exitCode: exitCode === -1 ? undefined : exitCode,
+        finishedAt: new Date().toISOString(),
+    });
+    return { task: finished ?? task, exitCode };
+}

package/dist/lib/hosts/progress.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Follow a dispatched host run by offset-tailing its remote log.
+ *
+ * The run writes combined output to a log file on the host and its exit code to
+ * a sibling `.exit` file. We poll `tail -c +<offset>` (durable, offset-tracked —
+ * a dropped connection resumes from the saved offset) and finish when `.exit`
+ * appears. Rich transcript-parser rendering is a fast-follow.
+ */
+export interface FollowOptions {
+    remoteLog: string;
+    remoteExit: string;
+    /** Mirror remote output into this task's local log too. */
+    taskId: string;
+    /** Print streamed output to stdout. */
+    echo?: boolean;
+    /** Overall wall-clock cap; returns -1 on timeout. */
+    timeoutMs?: number;
+    pollMs?: number;
+}
+/** Tail the remote log to stdout until the run finishes; return its exit code. */
+export declare function followHostTask(target: string, opts: FollowOptions): Promise<number>;

package/dist/lib/hosts/progress.js

@@ -0,0 +1,49 @@
+/**
+ * Follow a dispatched host run by offset-tailing its remote log.
+ *
+ * The run writes combined output to a log file on the host and its exit code to
+ * a sibling `.exit` file. We poll `tail -c +<offset>` (durable, offset-tracked —
+ * a dropped connection resumes from the saved offset) and finish when `.exit`
+ * appears. Rich transcript-parser rendering is a fast-follow.
+ */
+import * as fs from 'fs';
+import { sshExec } from '../ssh-exec.js';
+import { localLogPath } from './tasks.js';
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Tail the remote log to stdout until the run finishes; return its exit code. */
+export async function followHostTask(target, opts) {
+    const pollMs = opts.pollMs ?? 1500;
+    const deadline = Date.now() + (opts.timeoutMs ?? 3600_000);
+    const local = localLogPath(opts.taskId);
+    let offset = 0;
+    const drain = () => {
+        // remoteLog is a $HOME-prefixed path with a safe (hex) basename — intentionally
+        // unquoted so the remote shell expands $HOME.
+        const chunk = sshExec(target, `tail -c +${offset + 1} ${opts.remoteLog} 2>/dev/null`, { timeoutMs: 20000 });
+        if (chunk.stdout) {
+            if (opts.echo)
+                process.stdout.write(chunk.stdout);
+            try {
+                fs.appendFileSync(local, chunk.stdout);
+            }
+            catch { /* best-effort */ }
+            offset += Buffer.byteLength(chunk.stdout, 'utf8');
+        }
+    };
+    for (;;) {
+        drain();
+        const exit = sshExec(target, `cat ${opts.remoteExit} 2>/dev/null`, { timeoutMs: 12000 });
+        if (exit.code === 0 && exit.stdout.trim() !== '') {
+            drain(); // final flush
+            const code = parseInt(exit.stdout.trim(), 10);
+            return Number.isFinite(code) ? code : 0;
+        }
+        if (Date.now() > deadline) {
+            process.stderr.write('\n[hosts] follow timed out; the run continues on the host. Reattach with: agents hosts logs ' + opts.taskId + ' -f\n');
+            return -1;
+        }
+        await sleep(pollMs);
+    }
+}

package/dist/lib/hosts/providers/local.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Local host provider: the v1 directory.
+ *
+ * `list()` is the union of ssh-config `Host` stanzas (read-only, connection
+ * details owned by ssh) and inline entries the user registered in agents.yaml.
+ * The `Meta.hosts` overlay (caps/os, keyed by name) is merged onto both. We
+ * never copy or rewrite ssh config.
+ */
+import type { Host, HostProvider, HostProviderCapabilities } from '../types.js';
+export declare class LocalHostProvider implements HostProvider {
+    readonly id: "local";
+    capabilities(): HostProviderCapabilities;
+    list(): Promise<Host[]>;
+    resolve(name: string): Promise<Host | null>;
+    register(spec: Host): Promise<Host>;
+    remove(name: string): Promise<void>;
+}

package/dist/lib/hosts/providers/local.js

@@ -0,0 +1,81 @@
+/**
+ * Local host provider: the v1 directory.
+ *
+ * `list()` is the union of ssh-config `Host` stanzas (read-only, connection
+ * details owned by ssh) and inline entries the user registered in agents.yaml.
+ * The `Meta.hosts` overlay (caps/os, keyed by name) is merged onto both. We
+ * never copy or rewrite ssh config.
+ */
+import { readMeta, updateMeta } from '../../state.js';
+import { listSshConfigHosts, isSshConfigHost } from '../ssh-config.js';
+function entries() {
+    return readMeta().hosts ?? {};
+}
+function toHost(name, entry, enrolled) {
+    return {
+        name,
+        provider: 'local',
+        enrolled,
+        source: entry.source,
+        address: entry.address,
+        user: entry.user,
+        os: entry.os,
+        caps: entry.caps,
+        addedAt: entry.addedAt,
+    };
+}
+export class LocalHostProvider {
+    id = 'local';
+    capabilities() {
+        return { directory: true, mutate: true, presence: false, relay: false, lease: false };
+    }
+    async list() {
+        const overlay = entries();
+        const out = [];
+        const seen = new Set();
+        // Inline + overlaid hosts from the registry.
+        for (const [name, entry] of Object.entries(overlay)) {
+            out.push(toHost(name, entry, true));
+            seen.add(name);
+        }
+        // ssh-config hosts not already carrying an overlay → available, not enrolled.
+        for (const name of listSshConfigHosts()) {
+            if (seen.has(name))
+                continue;
+            out.push(toHost(name, { source: 'ssh-config' }, false));
+            seen.add(name);
+        }
+        return out.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async resolve(name) {
+        const entry = entries()[name];
+        if (entry)
+            return toHost(name, entry, true);
+        if (isSshConfigHost(name))
+            return toHost(name, { source: 'ssh-config' }, false);
+        return null;
+    }
+    async register(spec) {
+        const entry = {
+            source: spec.source,
+            ...(spec.source === 'inline' ? { address: spec.address, user: spec.user } : {}),
+            ...(spec.os ? { os: spec.os } : {}),
+            ...(spec.caps && spec.caps.length ? { caps: spec.caps } : {}),
+            addedAt: spec.addedAt ?? new Date().toISOString(),
+        };
+        updateMeta((meta) => ({ ...meta, hosts: { ...(meta.hosts ?? {}), [spec.name]: entry } }));
+        return toHost(spec.name, entry, true);
+    }
+    async remove(name) {
+        updateMeta((meta) => {
+            const hosts = { ...(meta.hosts ?? {}) };
+            delete hosts[name];
+            // Drop the key entirely when empty so we don't leave `hosts: {}` behind.
+            if (Object.keys(hosts).length === 0) {
+                const { hosts: _omit, ...rest } = meta;
+                return rest;
+            }
+            return { ...meta, hosts };
+        });
+    }
+}

package/dist/lib/hosts/ready.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Host readiness + bootstrap.
+ *
+ * Before a dispatch we ensure the box is reachable and has agents-cli. Enrollment
+ * can additionally install/upgrade agents-cli to match the local version (version
+ * parity) using the same shape as scripts/sandbox.sh. We never copy `.history`.
+ */
+import type { Host } from './types.js';
+/** Resolve this CLI's own version by walking up to the nearest package.json. */
+export declare function localCliVersion(): string | null;
+/** uname over ssh → reachable + OS string. */
+export declare function probeHost(target: string): {
+    reachable: boolean;
+    os?: string;
+};
+/** Remote agents-cli version (login shell for PATH), or null if not installed. */
+export declare function remoteAgentsVersion(target: string): string | null;
+/** True if the named agent CLI is installed on the remote (best-effort). */
+export declare function remoteAgentInstalled(target: string, agent: string): boolean;
+/** Install (or upgrade to) a specific agents-cli version on the remote, then `agents setup`. */
+export declare function bootstrapAgentsCli(target: string, version: string | null): {
+    ok: boolean;
+    output: string;
+};
+export interface EnsureReadyOptions {
+    agent: string;
+    /** Throw instead of warn when the agent isn't installed remotely. */
+    requireAgent?: boolean;
+}
+/**
+ * Verify a host can run the agent: reachable + agents-cli present. Throws with an
+ * actionable message otherwise. Agent-not-installed is a warning by default (the
+ * remote `agents run` will surface it); pass requireAgent to make it fatal.
+ */
+export declare function ensureHostReady(host: Host, opts: EnsureReadyOptions): {
+    warnings: string[];
+};