@phnx-labs/agents-cli 1.20.26 → 1.20.28

package/dist/lib/heal.js

@@ -0,0 +1,279 @@
+/**
+ * Resource heal engine — close the gap between what DotAgents repos DEFINE and
+ * what is actually present/valid in each installed agent home.
+ *
+ * Powers two callers:
+ *   - `agents doctor --fix`  — explicit, operator-driven. Mode 'full': fills
+ *     missing, overwrites drifted content, and refreshes stale plugins even when
+ *     the baseline is unknown (the operator asked for it).
+ *   - the routines daemon's periodic safety check — Mode 'safe': fixes only the
+ *     unambiguous gaps (missing resources, Claude-invalid plugin manifests, and
+ *     provably-unmodified stale plugins). Drift and risky refreshes are reported,
+ *     never clobbered.
+ *
+ * Built on the LIVE-home diff (`diffVersionResources`) — NOT the staleness
+ * manifest. `isStale()` only compares the last-synced manifest against the
+ * sources, so home-side rot (a deleted, corrupted, or Claude-rejected file in a
+ * version home whose source never changed) is invisible to it and to the sync
+ * fast-guard. The diff reads the actual home, so heal catches exactly that class
+ * of drift — the kind that silently broke the `code` plugin on a non-default
+ * Claude version.
+ *
+ * Heal FILLS and FIXES; it never deletes. Orphan/extra removal stays the job of
+ * `agents prune cleanup`, so a heal pass can never lose work.
+ */
+import { ALL_AGENT_IDS } from './agents.js';
+import { syncResourcesToVersion, listInstalledVersions, getVersionHomePath, getActuallySyncedResources, compareVersions, } from './versions.js';
+import { diffVersionResources, } from './doctor-diff.js';
+import { discoverPlugins, updatePlugin, readPluginSourceInfo, getUpstreamManifestVersion, } from './plugins.js';
+import { repairPluginManifestFile } from './plugin-marketplace.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { spawn } from 'child_process';
+// ─── diff → selection mapping ────────────────────────────────────────────────
+// Which ResourceSelection key each healable diff kind writes through. `rules`
+// re-syncs via the whole-memory channel (not name-scoped); `promptcuts` is not
+// version-synced at all, so it is never healed here.
+const KIND_TO_SELECTION = {
+    commands: 'commands',
+    skills: 'skills',
+    hooks: 'hooks',
+    mcp: 'mcp',
+    permissions: 'permissions',
+    subagents: 'subagents',
+    plugins: 'plugins',
+};
+function totalHealed(r) {
+    return r.versions.reduce((n, v) => n + v.healed.length, 0);
+}
+/** True when a heal pass made (or would make) any change at all. */
+export function healChangedAnything(r) {
+    return (totalHealed(r) > 0 ||
+        r.repairedManifests.length > 0 ||
+        r.refreshedPlugins.length > 0);
+}
+/** One-line summary of a heal pass for daemon logs. */
+export function summarizeHeal(r) {
+    const parts = [];
+    const healed = totalHealed(r);
+    if (healed > 0)
+        parts.push(`${healed} resource(s) healed`);
+    if (r.repairedManifests.length > 0)
+        parts.push(`${r.repairedManifests.length} manifest(s) repaired`);
+    if (r.refreshedPlugins.length > 0)
+        parts.push(`${r.refreshedPlugins.length} plugin(s) refreshed`);
+    if (r.skippedPlugins.length > 0)
+        parts.push(`${r.skippedPlugins.length} plugin(s) need attention`);
+    return parts.length > 0 ? parts.join(', ') : 'nothing to heal';
+}
+/**
+ * Fire a native desktop notification when a background heal did something
+ * noteworthy. Best-effort — missing `osascript`/`notify-send` or no display is
+ * swallowed. Silent when the pass auto-fixed everything and nothing needs the
+ * operator (no point pinging them for routine self-healing).
+ */
+export function notifyHeal(r) {
+    const needsAttention = r.skippedPlugins.length;
+    const healed = totalHealed(r) + r.repairedManifests.length + r.refreshedPlugins.length;
+    if (needsAttention === 0 && healed === 0)
+        return;
+    const title = needsAttention > 0
+        ? `agents: ${needsAttention} plugin${needsAttention === 1 ? '' : 's'} need attention`
+        : 'agents: auto-healed config gaps';
+    const body = needsAttention > 0
+        ? `${summarizeHeal(r)}. Run: agents doctor --fix`
+        : summarizeHeal(r);
+    const platform = os.platform();
+    try {
+        if (platform === 'darwin') {
+            const safeTitle = title.replace(/"/g, '\\"');
+            const safeBody = body.replace(/"/g, '\\"');
+            const child = spawn('osascript', ['-e', `display notification "${safeBody}" with title "${safeTitle}"`], { detached: true, stdio: 'ignore' });
+            child.unref();
+        }
+        else if (platform === 'linux') {
+            const child = spawn('notify-send', [title, body], { detached: true, stdio: 'ignore' });
+            child.unref();
+        }
+    }
+    catch {
+        // Notification is best-effort; nothing to do.
+    }
+}
+// ─── central plugin layer (version-independent, runs once per heal) ──────────
+/**
+ * Strip Claude-invalid bare-name `skills`/`commands` fields from every central
+ * plugin's SOURCE plugin.json. Unambiguously safe (Claude auto-discovers both
+ * from their directories) and the precondition for those plugins loading at all.
+ */
+export function repairCentralPluginManifests(dryRun = false) {
+    const out = [];
+    for (const p of discoverPlugins()) {
+        const manifestPath = path.join(p.root, '.claude-plugin', 'plugin.json');
+        const dropped = repairPluginManifestFile(manifestPath, { dryRun });
+        if (dropped.length > 0)
+            out.push({ plugin: p.name, droppedFields: dropped });
+    }
+    return out;
+}
+/**
+ * Fast-forward central plugins whose local `.source` upstream now ships a newer
+ * version. `allowModified` (full mode) re-pulls regardless of baseline; safe
+ * mode refreshes only when the central copy is provably an untouched mirror of
+ * its last pull (baseline version === current version) and reports the rest.
+ */
+async function refreshStaleCentralPlugins(opts) {
+    const refreshed = [];
+    const skipped = [];
+    for (const p of discoverPlugins()) {
+        const info = readPluginSourceInfo(p.root);
+        if (!info)
+            continue;
+        const upstream = getUpstreamManifestVersion(info); // null for git sources
+        if (!upstream)
+            continue;
+        const central = p.manifest.version;
+        if (compareVersions(upstream, central) <= 0)
+            continue; // central already current
+        const baselineKnown = info.version !== undefined;
+        const modified = baselineKnown && info.version !== central;
+        if (!opts.allowModified) {
+            // Safe mode never overwrites a copy it can't prove is pristine.
+            if (modified) {
+                skipped.push({ plugin: p.name, from: central, upstream, reason: 'modified' });
+                continue;
+            }
+            if (!baselineKnown) {
+                skipped.push({ plugin: p.name, from: central, upstream, reason: 'no-baseline' });
+                continue;
+            }
+        }
+        if (opts.dryRun) {
+            refreshed.push({ plugin: p.name, from: central, to: upstream });
+            continue;
+        }
+        const r = await updatePlugin(p.name);
+        if (r.success)
+            refreshed.push({ plugin: p.name, from: central, to: upstream });
+    }
+    return { refreshed, skipped };
+}
+// ─── per-version heal ────────────────────────────────────────────────────────
+function healVersion(agent, version, opts) {
+    const result = { agent, version, healed: [], skipped: [] };
+    const home = getVersionHomePath(agent, version);
+    if (!fs.existsSync(home))
+        return result;
+    // Always resolve against non-project layers: the global version home is never
+    // reconciled against per-cwd project resources (they layer in at launch).
+    const diffOpts = { cwd: opts.cwd, excludeProject: true };
+    const report = diffVersionResources(agent, version, diffOpts);
+    const selection = {};
+    // Resources we attempt to write, tracked so the post-write re-diff can tell
+    // "actually fixed" from "writer couldn't satisfy the diff" (no false claims).
+    const attempted = [];
+    for (const rows of Object.values(report.kinds)) {
+        for (const row of rows) {
+            const isMissing = row.status === 'missing';
+            const isDrift = row.status === 'diff';
+            if (!isMissing && !isDrift)
+                continue;
+            if (isDrift && !opts.includeDrift) {
+                // Ambiguous content drift — could be a deliberate hand-edit. Report it
+                // (the daemon notifies); never silently overwrite in safe mode.
+                result.skipped.push({ kind: row.kind, name: row.name, reason: 'drift' });
+                continue;
+            }
+            if (row.kind === 'promptcuts')
+                continue; // not version-synced
+            if (row.kind === 'rules') {
+                selection.memory = 'all';
+                attempted.push({ kind: row.kind, name: row.name, was: row.status });
+                continue;
+            }
+            const key = KIND_TO_SELECTION[row.kind];
+            if (!key)
+                continue;
+            (selection[key] ??= []).push(row.name);
+            attempted.push({ kind: row.kind, name: row.name, was: row.status });
+        }
+    }
+    // Plugins are presence-only in the diff, so a stale/invalid-but-present plugin
+    // mirror never shows as 'diff' — yet its central source just changed (repaired
+    // or refreshed). Re-push those into this version's marketplace mirror, but only
+    // where the plugin is already installed (don't force-install into a version
+    // that opted out). These are verified by the central change, not the re-diff.
+    const pluginHealed = [];
+    if (opts.changedPlugins.size > 0) {
+        const synced = new Set(getActuallySyncedResources(agent, version, diffOpts).plugins);
+        const already = new Set(selection.plugins ?? []);
+        for (const name of opts.changedPlugins) {
+            if (!synced.has(name) || already.has(name))
+                continue;
+            (selection.plugins ??= []).push(name);
+            pluginHealed.push({ kind: 'plugins', name, was: 'diff' });
+        }
+    }
+    const hasWork = Object.keys(selection).length > 0;
+    if (!hasWork)
+        return result;
+    if (opts.dryRun) {
+        // No write — report the intended fixes as-is.
+        result.healed.push(...attempted, ...pluginHealed);
+        return result;
+    }
+    // Explicit selection => bypasses the manifest fast-guard and writes exactly
+    // these names (additive; no orphan-sweep), so nothing outside the gap moves.
+    syncResourcesToVersion(agent, version, selection, { cwd: opts.cwd });
+    result.healed.push(...pluginHealed);
+    // Verify: re-diff and only claim resources that actually flipped to ok. Ones
+    // still flagged are reported as 'unreconcilable' so repeated runs converge in
+    // messaging instead of "fixing" the same item forever.
+    const post = diffVersionResources(agent, version, diffOpts);
+    const stillBad = new Set();
+    for (const rows of Object.values(post.kinds)) {
+        for (const row of rows) {
+            if (row.status === 'missing' || row.status === 'diff')
+                stillBad.add(`${row.kind}:${row.name}`);
+        }
+    }
+    for (const a of attempted) {
+        if (stillBad.has(`${a.kind}:${a.name}`)) {
+            result.skipped.push({ kind: a.kind, name: a.name, reason: 'unreconcilable' });
+        }
+        else {
+            result.healed.push(a);
+        }
+    }
+    return result;
+}
+// ─── public entrypoint ────────────────────────────────────────────────────────
+/**
+ * Run a heal pass. Repairs the central plugin layer once (manifest + stale
+ * refresh), then reconciles every targeted (agent, version) home against its
+ * live diff. Returns a full account of what changed (or would, under dryRun).
+ */
+export async function heal(opts) {
+    const cwd = opts.cwd ?? os.homedir();
+    const full = opts.mode === 'full';
+    const repairedManifests = repairCentralPluginManifests(opts.dryRun);
+    const { refreshed, skipped: skippedPlugins } = await refreshStaleCentralPlugins({
+        dryRun: opts.dryRun,
+        allowModified: full,
+    });
+    const changedPlugins = new Set([
+        ...repairedManifests.map((r) => r.plugin),
+        ...refreshed.map((r) => r.plugin),
+    ]);
+    const targets = opts.agent
+        ? [{ agent: opts.agent, versions: opts.versions ?? listInstalledVersions(opts.agent) }]
+        : ALL_AGENT_IDS.map((a) => ({ agent: a, versions: listInstalledVersions(a) }));
+    const versions = [];
+    for (const t of targets) {
+        for (const v of t.versions) {
+            versions.push(healVersion(t.agent, v, { cwd, includeDrift: full, changedPlugins, dryRun: opts.dryRun }));
+        }
+    }
+    return { versions, repairedManifests, refreshedPlugins: refreshed, skippedPlugins };
+}

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>;
+}