@phnx-labs/agents-cli 1.20.64 → 1.20.66

package/dist/lib/plugins.js

@@ -134,12 +134,34 @@ export function pluginResourceGroups(plugin) {
         out.push({ label: 'settings', items: ['settings.json'] });
     return out;
 }
+/**
+ * True when a manifest field declares an inline execution surface — a non-empty
+ * path string, a non-empty array, or an object with at least one key. The
+ * official plugin format lets `hooks`/`mcpServers` live inline in the manifest
+ * (a path or an inline map) instead of as a `hooks/` dir or `.mcp.json` file, so
+ * filesystem-only detection would miss them and auto-enable a hostile plugin.
+ */
+function manifestDeclaresExecSurface(value) {
+    if (typeof value === 'string')
+        return value.trim().length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (value && typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return false;
+}
 export function inspectPluginCapabilities(pluginRoot) {
     const manifest = loadPluginManifest(pluginRoot);
     const plugin = manifest ? buildDiscoveredPlugin(pluginRoot, manifest) : null;
     return {
-        hasHooks: (plugin?.hooks.length || 0) > 0 || pluginHasDirectoryEntries(pluginRoot, 'hooks'),
-        hasMcp: fs.existsSync(path.join(pluginRoot, '.mcp.json')),
+        // Inline manifest `hooks`/`mcpServers` are execution surfaces too — a cloned
+        // repo's project plugin must not be auto-enabled just because it ships the
+        // exec config inline in plugin.json rather than as a hooks/ dir or .mcp.json.
+        hasHooks: (plugin?.hooks.length || 0) > 0 ||
+            pluginHasDirectoryEntries(pluginRoot, 'hooks') ||
+            manifestDeclaresExecSurface(manifest?.hooks),
+        hasMcp: fs.existsSync(path.join(pluginRoot, '.mcp.json')) ||
+            manifestDeclaresExecSurface(manifest?.mcpServers),
         hasBin: (plugin?.bin.length || 0) > 0,
         hasScripts: (plugin?.scripts.length || 0) > 0,
         hasSettings: pluginHasNonPermissionSettings(pluginRoot),
@@ -499,6 +521,14 @@ export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
     // OpenCode uses TS/JS modules under ~/.config/opencode/plugins/, not the
     // Claude marketplace layout. Install those modules and return early.
     if (agent === 'opencode') {
+        // Trust gate (RUSH-1756): OpenCode plugins are raw executable TS/JS modules,
+        // so they must clear the same consent check as every other exec surface
+        // before install — this branch used to return early, bypassing the gate the
+        // Gemini/Hermes/marketplace branches all apply.
+        const enablePlugin = options.allowExecSurfaces === true || !hasPluginExecSurfaces(inspectPluginCapabilities(plugin.root));
+        if (!enablePlugin) {
+            return result;
+        }
         const ok = installOpenCodePlugin(plugin, versionHome);
         result.success = ok;
         if (ok)
@@ -982,6 +1012,72 @@ function writeGeminiExtensionManifest(plugin, destRoot) {
     }
     fs.writeFileSync(path.join(destRoot, GEMINI_EXTENSION_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
 }
+/**
+ * Security (RUSH-1755): `fs.cpSync(..., { recursive: true })` copies symlinks
+ * verbatim (dereference defaults to false), so a malicious plugin can ship a
+ * symlink whose target escapes the install root — e.g.
+ * `.agents-cli-managed -> ~/.bashrc`. The managed-marker / manifest writes that
+ * follow the copy would then write THROUGH the link, clobbering an
+ * attacker-chosen path outside the install root.
+ *
+ * Walk destRoot after the recursive copy, lstat each entry, and remove any
+ * symlink whose resolved target escapes BOTH destRoot and sourceRoot. Both roots
+ * matter because Node's cpSync rewrites a *relative* internal symlink
+ * (`./x`) into an *absolute* link back into the source tree, so a legitimate
+ * internal symlink resolves under sourceRoot (not destRoot) after the copy.
+ * Keeping targets within sourceRoot preserves those internal symlinks — matching
+ * copyPluginToMarketplace's policy — while genuinely external escapes are
+ * dropped, neutralizing the write-through.
+ */
+function stripEscapingSymlinks(destRoot, sourceRoot) {
+    const realRoots = [destRoot, sourceRoot].map((r) => {
+        try {
+            return fs.realpathSync(r);
+        }
+        catch {
+            return r;
+        }
+    });
+    const within = (target) => realRoots.some((root) => target === root || target.startsWith(root + path.sep));
+    const removed = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isSymbolicLink()) {
+                let escapes;
+                try {
+                    escapes = !within(fs.realpathSync(full));
+                }
+                catch {
+                    // Dangling / unresolvable symlink — treat as escaping and drop it.
+                    escapes = true;
+                }
+                if (escapes) {
+                    try {
+                        fs.rmSync(full, { force: true });
+                        removed.push(path.relative(destRoot, full) || entry.name);
+                    }
+                    catch { /* best effort */ }
+                }
+            }
+            else if (entry.isDirectory()) {
+                // Do not descend into symlinked dirs — isDirectory() is false for a
+                // symlink even when it points at a directory, so this only recurses
+                // into real subdirectories, keeping the walk inside destRoot.
+                walk(full);
+            }
+        }
+    };
+    walk(destRoot);
+    return removed;
+}
 export function installGeminiPlugin(plugin, versionHome) {
     const destRoot = path.join(geminiExtensionsDir(versionHome), plugin.name);
     try {
@@ -989,6 +1085,7 @@ export function installGeminiPlugin(plugin, versionHome) {
             fs.rmSync(destRoot, { recursive: true, force: true });
         }
         fs.cpSync(plugin.root, destRoot, { recursive: true });
+        stripEscapingSymlinks(destRoot, plugin.root);
         const userConfig = loadUserConfig(plugin.name);
         if (Object.keys(userConfig).length > 0) {
             expandUserConfigInDir(destRoot, userConfig);
@@ -1030,6 +1127,7 @@ export function installGoosePlugin(plugin, versionHome) {
             fs.rmSync(destRoot, { recursive: true, force: true });
         }
         fs.cpSync(plugin.root, destRoot, { recursive: true });
+        stripEscapingSymlinks(destRoot, plugin.root);
         fs.writeFileSync(path.join(destRoot, '.agents-cli-managed'), `plugin=${plugin.name}\n`, 'utf-8');
         return true;
     }
@@ -1111,6 +1209,7 @@ export function installHermesPlugin(plugin, versionHome, enable) {
             fs.rmSync(destRoot, { recursive: true, force: true });
         }
         fs.cpSync(plugin.root, destRoot, { recursive: true });
+        stripEscapingSymlinks(destRoot, plugin.root);
         const userConfig = loadUserConfig(plugin.name);
         if (Object.keys(userConfig).length > 0) {
             expandUserConfigInDir(destRoot, userConfig);
@@ -1640,7 +1739,33 @@ export function getUpstreamManifestVersion(info) {
  * Update an installed plugin by re-pulling from its original source.
  * Returns true if the update succeeded.
  */
-export async function updatePlugin(name) {
+/**
+ * Labels of exec surfaces present in `after` that were NOT present in `before`.
+ * Used by updatePlugin to distinguish a newly-appearing execution surface
+ * (upstream compromise → renewed consent required) from one the user already
+ * trusted (leave enablement alone).
+ */
+export function newExecSurfaceLabels(before, after) {
+    return Object.keys(PLUGIN_EXEC_SURFACE_LABELS)
+        .filter((key) => after[key] && !before[key])
+        .map((key) => PLUGIN_EXEC_SURFACE_LABELS[key]);
+}
+/**
+ * Re-fetch a plugin from its recorded source and apply the update to disk.
+ *
+ * Security (RUSH-1757): a plugin's upstream is mutable. `updatePlugin` never
+ * mutates the live plugin tree before it has inspected the incoming content —
+ * the new revision is fetched into a **quarantine** dir first, its capabilities
+ * are diffed against the current on-disk baseline, and the update is applied to
+ * `plugin.root` only after the trust decision. If the update introduces a NEW
+ * executable surface (hooks/, .mcp.json, bin/, scripts/, settings.json,
+ * permissions/) that the current revision did not carry, the update is refused
+ * unless `options.allowExecSurfaces` is set — the last-good content is kept in
+ * place, so a benign-then-compromised upstream can never execute on the next
+ * update without renewed consent. A surface the user already trusted is not a
+ * "new" surface and does not re-trigger the gate.
+ */
+export async function updatePlugin(name, options = {}) {
     const plugin = getPlugin(name);
     if (!plugin) {
         return { success: false, error: `Plugin '${name}' not found` };
@@ -1656,33 +1781,68 @@ export async function updatePlugin(name) {
     catch {
         return { success: false, error: `Could not read source info for '${name}'` };
     }
+    // Baseline: what the live (already-trusted) revision ships today.
+    const before = inspectPluginCapabilities(plugin.root);
+    // Quarantine dir lives beside plugin.root (same filesystem) so the final
+    // apply can be a rename. The dot-prefix keeps it out of plugin discovery.
+    const quarantine = path.join(path.dirname(plugin.root), `.${path.basename(plugin.root)}.update-quarantine`);
+    const cleanupQuarantine = () => {
+        try {
+            fs.rmSync(quarantine, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+    };
+    cleanupQuarantine();
     try {
+        // 1. Fetch the incoming revision into quarantine — never touch plugin.root yet.
         if (sourceInfo.isGit) {
-            execFileSync('git', ['-C', plugin.root, 'pull', '--ff-only'], { stdio: 'pipe' });
+            // Copy the working checkout (with its .git) and fast-forward the copy, so a
+            // hostile upstream diff lands in the quarantine, not the live tree.
+            fs.cpSync(plugin.root, quarantine, { recursive: true });
+            execFileSync('git', ['-C', quarantine, 'pull', '--ff-only'], { stdio: 'pipe' });
         }
         else {
             const resolvedSource = sourceInfo.source.replace(/^~/, homeDir());
             if (!fs.existsSync(resolvedSource)) {
+                cleanupQuarantine();
                 return { success: false, error: `Source path no longer exists: ${resolvedSource}` };
             }
-            // Preserve .user-config.json and .source during re-copy
-            const userConfigPath = path.join(plugin.root, USER_CONFIG_FILE);
-            const userConfigBackup = fs.existsSync(userConfigPath)
-                ? fs.readFileSync(userConfigPath, 'utf-8')
-                : null;
-            fs.rmSync(plugin.root, { recursive: true, force: true });
-            fs.cpSync(resolvedSource, plugin.root, { recursive: true });
-            if (userConfigBackup !== null) {
-                fs.writeFileSync(userConfigPath, userConfigBackup, 'utf-8');
-            }
+            fs.cpSync(resolvedSource, quarantine, { recursive: true });
+        }
+        // 2. Diff capabilities of the incoming revision against the baseline.
+        const after = inspectPluginCapabilities(quarantine);
+        const newSurfaces = newExecSurfaceLabels(before, after);
+        // 3. Refuse a surface-introducing update without renewed consent. The
+        //    last-good content stays in place untouched.
+        if (newSurfaces.length > 0 && options.allowExecSurfaces !== true) {
+            cleanupQuarantine();
+            return {
+                success: false,
+                blockedByExecSurfaces: true,
+                newExecSurfaces: newSurfaces,
+                error: `Update refused: '${name}' introduces new executable surfaces (${newSurfaces.join(', ')}). ` +
+                    `Re-run with --allow-exec-surfaces if you trust the source.`,
+            };
+        }
+        // 4. Apply: swap the quarantined revision into plugin.root, preserving the
+        //    user config and re-stamping .source.
+        const userConfigPath = path.join(plugin.root, USER_CONFIG_FILE);
+        const userConfigBackup = fs.existsSync(userConfigPath)
+            ? fs.readFileSync(userConfigPath, 'utf-8')
+            : null;
+        fs.rmSync(plugin.root, { recursive: true, force: true });
+        fs.renameSync(quarantine, plugin.root);
+        if (userConfigBackup !== null) {
+            fs.writeFileSync(userConfigPath, userConfigBackup, 'utf-8');
         }
         // Re-stamp .source with the freshly pulled manifest version so the baseline
         // tracks what's now on disk (keeps the heal "unmodified?" check honest).
         const freshVersion = loadPluginManifest(plugin.root)?.version;
         fs.writeFileSync(path.join(plugin.root, SOURCE_FILE), JSON.stringify({ ...sourceInfo, version: freshVersion }), 'utf-8');
+        return { success: true, newExecSurfaces: newSurfaces, hasExecSurfaces: hasPluginExecSurfaces(after) };
     }
     catch (err) {
+        cleanupQuarantine();
         return { success: false, error: err.message };
     }
-    return { success: true };
 }

package/dist/lib/redact.d.ts

@@ -1,4 +1,17 @@
 /**
  * Shared redaction helpers for text that may be exported or logged.
  */
-export declare function redactSecrets(text: string): string;
+/**
+ * Scrub secrets from `text`. Two passes: format-based patterns (above), then a
+ * value-aware pass that masks any `knownValues` verbatim — a credential we
+ * already hold in hand leaks regardless of its format, so an exact-value match
+ * catches tokens the regexes don't recognize.
+ */
+export declare function redactSecrets(text: string, knownValues?: readonly string[]): string;
+/**
+ * Secret values already present in the environment (e.g. an injected secrets
+ * bundle), selected by secret-shaped var NAME. These are the "known" values fed
+ * to {@link redactSecrets} so an exported transcript can't leak a live
+ * credential verbatim even when its format matches no pattern.
+ */
+export declare function knownSecretValuesFromEnv(env?: NodeJS.ProcessEnv): string[];

package/dist/lib/redact.js

@@ -3,17 +3,63 @@
  */
 const SECRET_PATTERNS = [
     [/\bAKIA[0-9A-Z]{16}\b/g, '[REDACTED_AWS_KEY]'],
+    // GitHub: classic PATs (ghp_), OAuth (gho_), app/refresh/server tokens
+    // (ghs_/ghr_), and fine-grained PATs (github_pat_). All share the 36-char
+    // classic body; fine-grained tokens are longer, so match greedily.
     [/\bghp_[A-Za-z0-9]{36}\b/g, '[REDACTED_GITHUB_TOKEN]'],
+    [/\bgh[osru]_[A-Za-z0-9]{36}\b/g, '[REDACTED_GITHUB_TOKEN]'],
+    [/\bgithub_pat_[A-Za-z0-9_]{22,}\b/g, '[REDACTED_GITHUB_TOKEN]'],
+    // Anthropic keys (sk-ant-api03-…) before the generic sk- rule so the marker
+    // is specific; the generic rule would otherwise swallow it first.
+    [/\bsk-ant-api03-[A-Za-z0-9_-]{20,}\b/g, '[REDACTED_ANTHROPIC_KEY]'],
+    // Stripe live secret / restricted keys.
+    [/\b[rs]k_live_[A-Za-z0-9]{20,}\b/g, '[REDACTED_STRIPE_KEY]'],
     [/\bsk-[A-Za-z0-9]{20,}\b/g, '[REDACTED_API_KEY]'],
+    // Slack bot/user/app-level tokens (xoxb-/xoxp-/xapp-…).
+    [/\bxox[bp]-[A-Za-z0-9-]{10,}\b/g, '[REDACTED_SLACK_TOKEN]'],
+    [/\bxapp-[A-Za-z0-9-]{10,}\b/g, '[REDACTED_SLACK_TOKEN]'],
     [/\bnpm_[A-Za-z0-9]{36}\b/g, '[REDACTED_NPM_TOKEN]'],
     [/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[REDACTED_JWT]'],
     [/Bearer\s+\S+/gi, 'Bearer [REDACTED]'],
     [/\b([A-Z0-9_]*(?:TOKEN|KEY|SECRET|PASSWORD)[A-Z0-9_]*)=("[^"]*"|'[^']*'|\S+)/gi, '$1=[REDACTED]'],
 ];
-export function redactSecrets(text) {
+/** Env vars whose NAME marks their VALUE as a credential worth masking literally. */
+const SECRET_ENV_NAME = /(?:TOKEN|KEY|SECRET|PASSWORD)/i;
+/** Don't literal-mask trivially short values — they collide with ordinary text. */
+const MIN_KNOWN_VALUE_LEN = 6;
+/**
+ * Scrub secrets from `text`. Two passes: format-based patterns (above), then a
+ * value-aware pass that masks any `knownValues` verbatim — a credential we
+ * already hold in hand leaks regardless of its format, so an exact-value match
+ * catches tokens the regexes don't recognize.
+ */
+export function redactSecrets(text, knownValues) {
     let safe = text;
     for (const [pattern, replacement] of SECRET_PATTERNS) {
         safe = safe.replace(pattern, replacement);
     }
+    if (knownValues) {
+        for (const value of knownValues) {
+            if (value.length < MIN_KNOWN_VALUE_LEN)
+                continue;
+            safe = safe.split(value).join('[REDACTED]');
+        }
+    }
     return safe;
 }
+/**
+ * Secret values already present in the environment (e.g. an injected secrets
+ * bundle), selected by secret-shaped var NAME. These are the "known" values fed
+ * to {@link redactSecrets} so an exported transcript can't leak a live
+ * credential verbatim even when its format matches no pattern.
+ */
+export function knownSecretValuesFromEnv(env = process.env) {
+    const out = [];
+    for (const [name, value] of Object.entries(env)) {
+        if (!value || value.length < MIN_KNOWN_VALUE_LEN)
+            continue;
+        if (SECRET_ENV_NAME.test(name))
+            out.push(value);
+    }
+    return out;
+}

package/dist/lib/remote-agents-json.js

@@ -11,7 +11,7 @@ import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from './ssh-exec.js';
 import { sshTargetFor } from './devices/connect.js';
 import { resolveExplicitTargets } from './devices/resolve-target.js';
-import { loadDevices } from './devices/registry.js';
+import { loadDevices, isControlDevice } from './devices/registry.js';
 import { remoteShellFor, buildWindowsAgentsCommand } from './hosts/remote-cmd.js';
 import { machineId, normalizeHost } from './machine-id.js';
 const REMOTE_TIMEOUT_MS = 12_000;
@@ -66,6 +66,12 @@ export async function gatherRemoteAgentsJson(options) {
                 continue;
             if (normalizeHost(device.name) === self)
                 continue;
+            // Control-only devices (a phone/tablet cockpit) drive the fleet but never
+            // run agents — never dial them, whatever their platform reads as. Keyed on
+            // role, not platform, so this holds even for a control device that carries
+            // a real OS value (mirrors the skip in session/remote-list.ts).
+            if (isControlDevice(device))
+                continue;
             if (!['windows', 'linux', 'macos'].includes(device.platform))
                 continue;
             try {

package/dist/lib/rotate.d.ts

@@ -182,18 +182,21 @@ export declare function rotationFailoverChain(rotation: RotateResult | null, pic
  *   would break a previously-working `agents run … --loop` / `--acp`.
  * - `resumeCheckpoint` runs take the loop path (same guard).
  * - `interactive` / no-prompt runs can't be re-dispatched headlessly.
- * - `explicitFallback` (a user `--fallback` chain OR a profile fallback already
- *   unshifted) defines its own recovery; don't layer rotation failover on top.
  * - `hasRotation`/`hasVersion` gate on an actual pre-flight rotation having
  *   picked an account, so pinned and non-rotation runs are untouched.
  *
+ * An explicit `--fallback` chain does NOT disarm rotation failover: the
+ * synthesized same-agent entries are unshifted AHEAD of the user's cross-agent
+ * entries, so a rate limit exhausts the other accounts of the same agent
+ * before cascading to a different CLI. Profile fallbacks never reach here —
+ * strategy resolution is skipped for profiles, so hasRotation is false.
+ *
  * Pure so the arming matrix is unit-testable without invoking the run command.
  */
 export interface FailoverArmingContext {
     hasRotation: boolean;
     hasVersion: boolean;
     hasPrompt: boolean;
-    explicitFallback: boolean;
     interactive: boolean;
     acp: boolean;
     loop: boolean;

package/dist/lib/rotate.js

@@ -440,7 +440,6 @@ export function shouldArmRotationFailover(ctx) {
     return (ctx.hasRotation &&
         ctx.hasVersion &&
         ctx.hasPrompt &&
-        !ctx.explicitFallback &&
         !ctx.interactive &&
         !ctx.acp &&
         !ctx.loop &&

package/dist/lib/routines.d.ts

@@ -91,6 +91,17 @@ export interface JobConfig {
      * overdue; everywhere else it is inert and `run` refuses with a pointer.
      */
     devices?: string[];
+    /**
+     * Execution placement — run the job body on this machine over SSH (a
+     * registered host, device, capability tag, or user@host) instead of locally.
+     * Distinct from `devices`: `devices` says which daemon may FIRE the job,
+     * `host` says where the dispatched run EXECUTES. CLI flag: `--run-on`
+     * (`--host` on routines commands already means "manage routines on that
+     * machine" via the remote passthrough).
+     */
+    host?: string;
+    /** Working directory on the host for `host:`-placed runs. */
+    remoteCwd?: string;
     variables?: Record<string, string>;
     sandbox?: boolean;
     allow?: JobAllowConfig;
@@ -123,6 +134,11 @@ export interface RunMeta {
     startedAt: string;
     completedAt: string | null;
     exitCode: number | null;
+    /** Set for `host:`-placed runs — where the job body executes (no local pid). */
+    host?: string;
+    /** The host-task sidecar id backing a `host:` run; the daemon monitor
+     *  finalizes the run by reconciling it against the remote `.exit`. */
+    hostTaskId?: string;
 }
 /**
  * True when the job may execute on this machine: no `devices` allowlist (or

package/dist/lib/routines.js

@@ -363,6 +363,25 @@ export function validateJob(config) {
     if (config.device !== undefined) {
         errors.push('singular "device" key is no longer supported — replace with devices: [<name>] (an array)');
     }
+    if (config.host !== undefined) {
+        if (typeof config.host !== 'string' || config.host.trim() === '') {
+            errors.push('host must be a non-empty machine name (a registered host, device, capability tag, or user@host)');
+        }
+        // v1: the workflow bundle and the loop driver (with its signal files) live
+        // on the firing machine — neither can cross SSH to the target yet.
+        if (config.workflow) {
+            errors.push("host: can't be combined with workflow: yet (the bundle lives on the firing machine) — run the workflow locally or convert it to a plain prompt");
+        }
+        if (config.loop) {
+            errors.push("host: can't be combined with loop: yet (the loop driver and its signal files live on the firing machine)");
+        }
+        if (config.command) {
+            errors.push("host: can't be combined with command: yet (a plain shell command has no agent to place remotely) — run it locally, or convert it to a prompt");
+        }
+    }
+    if (config.remoteCwd !== undefined && config.host === undefined) {
+        errors.push('remoteCwd only applies to host:-placed routines — set host: too, or drop it');
+    }
     if (config.devices !== undefined) {
         if (!Array.isArray(config.devices)) {
             errors.push('devices must be an array of device names (as shown by `agents devices`)');

package/dist/lib/runner.d.ts

@@ -77,6 +77,7 @@ export declare function buildRoutineSpawnEnv(baseEnv: Record<string, string>, ag
  */
 export declare function executeJob(config: JobConfig, deps?: LoopDeps): Promise<RunResult>;
 /** Spawn a job as a detached process and return immediately with run metadata. */
+/** Spawn a job as a detached process and return immediately with run metadata. */
 export declare function executeJobDetached(config: JobConfig): Promise<RunMeta>;
 /** Extract the final assistant message from a stream-JSON log file as a markdown report. */
 export declare function extractReport(stdoutPath: string, agentType: AgentId): string | null;

package/dist/lib/runner.js

@@ -23,6 +23,8 @@ import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { createTimer, maybeRotate, redactPrompt } from './events.js';
 import { normalizeMode, buildExecEnv, detectRateLimit, } from './exec.js';
+import { loadTask as loadHostTask } from './hosts/tasks.js';
+import { reconcileTask as reconcileHostTask } from './hosts/reconcile.js';
 import { backgroundSpawnOptions } from './platform/process.js';
 import { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js';
 import { getConfiguredRunStrategy, resolveRunVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
@@ -448,6 +450,12 @@ export async function executeJob(config, deps) {
     if (eligibility) {
         throw new Error(eligibility.message);
     }
+    // `host:` placement — the job body runs on another machine over SSH; local
+    // version selection / sandbox / spawn do not apply. Sync callers (manual
+    // `routines run`, catchup) follow the remote run to completion.
+    if (config.host) {
+        return executeJobOnHost(config, { detached: false });
+    }
     // Command-mode: run a plain shell command directly (no agent, no rotation,
     // no pinning, no sandbox overlay). Reuses the run-record machinery so
     // list/runs/overdue keep working.
@@ -617,15 +625,67 @@ export async function executeJob(config, deps) {
     timer.end({ status: 'failed', exitCode: 1, runId });
     return { meta, reportPath: null };
 }
-/**
- * Foreground execution for a command-mode routine (`config.command`). Runs a
- * plain shell command in the REAL environment (no sandbox), captures stdout+
- * stderr to `stdout.log`, awaits completion, and honors `config.timeout` with
- * the same SIGTERM→SIGKILL kill mechanism the agent path uses. No agent is
- * spawned; the run record carries `command` instead of `agent`. There is no
- * agent report to extract, so `reportPath` is always null (the stdout log is
- * the artifact — same location the agent path writes).
- */
+async function executeJobOnHost(config, opts) {
+    if (config.workflow) {
+        throw new Error(`Routine '${config.name}' runs a workflow bundle, which can't execute on a host yet — remove 'host:' or 'workflow:'.`);
+    }
+    if (config.loop) {
+        throw new Error(`Routine '${config.name}' uses 'loop:', which can't execute on a host yet — remove 'host:' or 'loop:'.`);
+    }
+    if (config.command) {
+        throw new Error(`Routine '${config.name}' uses 'command:', which can't execute on a host yet — remove 'host:' or 'command:'.`);
+    }
+    const { resolveHostRunTarget, dispatchPromptToHost } = await import('./hosts/run-target.js');
+    const host = await resolveHostRunTarget(config.host);
+    const timer = createTimer('agent.run', {
+        agent: config.agent,
+        jobName: config.name,
+        mode: config.mode,
+        host: host.name,
+        ...redactPrompt(config.prompt),
+        schedule: config.schedule,
+    });
+    const runId = generateRunId();
+    const runDir = getRunDir(config.name, runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    const meta = {
+        jobName: config.name,
+        runId,
+        agent: config.agent,
+        pid: null, // no local process — the run lives on the host
+        spawnedAt: Date.now(),
+        status: 'running',
+        startedAt: new Date().toISOString(),
+        completedAt: null,
+        exitCode: null,
+        host: host.name,
+    };
+    writeRunMeta(meta);
+    const { task, exitCode } = await dispatchPromptToHost(host, {
+        agent: config.agent,
+        prompt: resolveJobPrompt(config),
+        mode: normalizeMode(config.mode),
+        effort: config.effort,
+        model: config.config?.model,
+        timeout: config.timeout, // enforced by the REMOTE agents run
+        remoteCwd: config.remoteCwd,
+        name: config.name,
+        cwd: runDir,
+        follow: !opts.detached,
+    });
+    meta.hostTaskId = task.id;
+    // Sync path: a real exit code finalizes now. -1 (follow window closed) and
+    // the detached path leave the meta `running` for the monitor to reconcile.
+    if (!opts.detached && exitCode !== null && exitCode !== undefined && exitCode !== -1) {
+        meta.status = exitCode === 0 ? 'completed' : 'failed';
+        meta.exitCode = exitCode;
+        meta.completedAt = new Date().toISOString();
+    }
+    writeRunMeta(meta);
+    timer.end({ status: meta.status, exitCode: meta.exitCode ?? undefined, runId });
+    return { meta, reportPath: null };
+}
+/** Spawn a job as a detached process and return immediately with run metadata. */
 async function executeCommandJobForeground(config) {
     const timer = createTimer('agent.run', {
         jobName: config.name,
@@ -712,12 +772,18 @@ async function executeCommandJobForeground(config) {
     return { meta, reportPath: null };
 }
 /** Spawn a job as a detached process and return immediately with run metadata. */
+/** Spawn a job as a detached process and return immediately with run metadata. */
 export async function executeJobDetached(config) {
     const eligibility = checkJobDeviceEligibility(config);
     if (eligibility) {
         process.stderr.write(`[agents] daemon: skipping '${config.name}' — ${eligibility.message}\n`);
         throw new Error(eligibility.message);
     }
+    // `host:` placement — dispatch over SSH and return; the monitor finalizes.
+    if (config.host) {
+        const { meta } = await executeJobOnHost(config, { detached: true });
+        return meta;
+    }
     // Command-mode: fire a plain shell command detached (no agent, no rotation,
     // no pinning, no sandbox overlay). Still writes a run record so the daemon,
     // list/runs, and overdue tracking keep working.
@@ -994,6 +1060,26 @@ function isPidOurs(pid, spawnedAt) {
         return true;
     }
 }
+/**
+ * Finalize one `host:`-placed run by healing its host-task sidecar against the
+ * remote `.exit` (lib/hosts/reconcile.ts). Mutates + persists the meta only
+ * when the sidecar reached a terminal state.
+ */
+function finalizeHostRun(meta) {
+    try {
+        const task = loadHostTask(meta.hostTaskId);
+        if (!task)
+            return;
+        const healed = reconcileHostTask(task);
+        if (healed.status !== 'completed' && healed.status !== 'failed')
+            return;
+        meta.status = healed.status;
+        meta.exitCode = healed.exitCode ?? (healed.status === 'completed' ? 0 : 1);
+        meta.completedAt = healed.finishedAt ?? new Date().toISOString();
+        writeRunMeta(meta);
+    }
+    catch { /* unreachable host or unreadable sidecar — retry next sweep */ }
+}
 /** Scan all runs marked "running" and finalize any whose process has exited. */
 export function monitorRunningJobs() {
     const runsDir = getRunsDir();
@@ -1013,6 +1099,13 @@ export function monitorRunningJobs() {
                 const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
                 if (meta.status !== 'running')
                     continue;
+                // `host:`-placed run — no local pid to watch. Reconcile against the
+                // remote `.exit` (completion is confirmed, never guessed: an
+                // unreachable host leaves the run `running` for the next sweep).
+                if (meta.hostTaskId) {
+                    finalizeHostRun(meta);
+                    continue;
+                }
                 if (!meta.pid)
                     continue;
                 const runDirPath = path.join(jobRunsPath, runDirEntry.name);