@phnx-labs/agents-cli 1.20.64 → 1.20.65

package/dist/lib/monitors/state.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Native per-monitor state-diff store.
+ *
+ * This is the one genuinely new primitive monitors add over routines: a
+ * last-observed-*value* store. Routines persist per-*run* metadata but have no
+ * last-seen value, so hand-built watchers (the RUSH-1107 SSL watcher) re-invented
+ * state-diffing through a markdown memory file every time. This store kills that.
+ *
+ * Layout (sibling of the runs layout, atomic writes like writeRunMeta):
+ *   ~/.agents/.history/monitors/<name>/state.json      # last-seen hash/value + fire bookkeeping
+ *   ~/.agents/.history/monitors/<name>/fires/<id>/…    # fire history
+ */
+import type { MonitorEvent } from './config.js';
+/** Persisted last-seen state for one monitor. */
+export interface MonitorState {
+    monitorName: string;
+    /** Hash of the last-seen de-dupe signature (see hasChanged). */
+    lastHash: string;
+    /** The last-seen raw observation (truncated for storage). */
+    lastValue: string;
+    /** RFC3339 timestamp of the last observation. */
+    lastSeenAt: string;
+    /** RFC3339 timestamp of the last fire, when the monitor has ever fired. */
+    lastFiredAt?: string;
+    /** Epoch-ms timestamps of recent fires, for the rate-limit / firehose guard. */
+    fireTimes?: number[];
+}
+/** Per-monitor history root, with the (untrusted) name contained to one segment. */
+export declare function getMonitorHistoryDir(name: string): string;
+/** Directory holding a monitor's fire history. */
+export declare function getMonitorFiresDir(name: string): string;
+/** Read a monitor's last-seen state, or null if it has never been observed. */
+export declare function readState(name: string): MonitorState | null;
+/** Persist a monitor's state atomically (temp file + rename, like writeRunMeta). */
+export declare function writeStateRaw(state: MonitorState): void;
+/**
+ * Record a new observation as the monitor's last-seen state, preserving fire
+ * bookkeeping. Truncates the stored raw value so a firehose can't bloat disk.
+ */
+export declare function writeState(name: string, value: string, dedupeKey?: string, extra?: Partial<Pick<MonitorState, 'lastFiredAt' | 'fireTimes'>>): MonitorState;
+/**
+ * The de-dupe signature for an observation. When `dedupeKey` is set, the
+ * signature is the first regex match of dedupeKey against the observation (so
+ * "the same event" is same matched token); otherwise it is the full observation.
+ * An unmatched dedupeKey falls back to the full observation.
+ */
+export declare function dedupeSignature(observation: string, dedupeKey?: string): string;
+/**
+ * True when `observation`'s de-dupe signature differs from the monitor's
+ * last-seen signature (or the monitor has never been observed). Pure read — the
+ * caller persists the new value via writeState only on a real fire.
+ */
+export declare function hasChanged(name: string, observation: string, dedupeKey?: string): boolean;
+/**
+ * Append a fire timestamp and return the pruned window (fires within `windowMs`).
+ * The engine uses the returned length to decide whether the rate limit tripped.
+ */
+export declare function recordFireTime(name: string, now: number, windowMs: number): number[];
+/** Write a fire record to fires/<id>/event.json and return the fire id. */
+export declare function writeFireRecord(event: MonitorEvent, meta?: Record<string, unknown>): string;
+/** A single fire history entry (as read back from disk). */
+export interface FireRecord extends MonitorEvent {
+    runId?: string;
+    action?: string;
+    ok?: boolean;
+    error?: string;
+}
+/** List a monitor's fire history, chronologically ascending. */
+export declare function listFires(name: string): FireRecord[];

package/dist/lib/monitors/state.js

@@ -0,0 +1,144 @@
+/**
+ * Native per-monitor state-diff store.
+ *
+ * This is the one genuinely new primitive monitors add over routines: a
+ * last-observed-*value* store. Routines persist per-*run* metadata but have no
+ * last-seen value, so hand-built watchers (the RUSH-1107 SSL watcher) re-invented
+ * state-diffing through a markdown memory file every time. This store kills that.
+ *
+ * Layout (sibling of the runs layout, atomic writes like writeRunMeta):
+ *   ~/.agents/.history/monitors/<name>/state.json      # last-seen hash/value + fire bookkeeping
+ *   ~/.agents/.history/monitors/<name>/fires/<id>/…    # fire history
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'crypto';
+import { getMonitorsHistoryDir, ensureAgentsDir } from '../state.js';
+import { safeJoin } from '../paths.js';
+const MAX_STORED_VALUE = 4096;
+/** Per-monitor history root, with the (untrusted) name contained to one segment. */
+export function getMonitorHistoryDir(name) {
+    return safeJoin(getMonitorsHistoryDir(), name);
+}
+function getStatePath(name) {
+    return path.join(getMonitorHistoryDir(name), 'state.json');
+}
+/** Directory holding a monitor's fire history. */
+export function getMonitorFiresDir(name) {
+    return path.join(getMonitorHistoryDir(name), 'fires');
+}
+/** Read a monitor's last-seen state, or null if it has never been observed. */
+export function readState(name) {
+    const statePath = getStatePath(name);
+    if (!fs.existsSync(statePath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist a monitor's state atomically (temp file + rename, like writeRunMeta). */
+export function writeStateRaw(state) {
+    ensureAgentsDir();
+    const dir = getMonitorHistoryDir(state.monitorName);
+    fs.mkdirSync(dir, { recursive: true });
+    const statePath = path.join(dir, 'state.json');
+    const tmp = `${statePath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf-8');
+    fs.renameSync(tmp, statePath);
+}
+/**
+ * Record a new observation as the monitor's last-seen state, preserving fire
+ * bookkeeping. Truncates the stored raw value so a firehose can't bloat disk.
+ */
+export function writeState(name, value, dedupeKey, extra = {}) {
+    const prev = readState(name);
+    const state = {
+        monitorName: name,
+        lastHash: hashSignature(value, dedupeKey),
+        lastValue: value.length > MAX_STORED_VALUE ? value.slice(0, MAX_STORED_VALUE) : value,
+        lastSeenAt: new Date().toISOString(),
+        ...(prev?.lastFiredAt ? { lastFiredAt: prev.lastFiredAt } : {}),
+        ...(prev?.fireTimes ? { fireTimes: prev.fireTimes } : {}),
+        ...extra,
+    };
+    writeStateRaw(state);
+    return state;
+}
+/**
+ * The de-dupe signature for an observation. When `dedupeKey` is set, the
+ * signature is the first regex match of dedupeKey against the observation (so
+ * "the same event" is same matched token); otherwise it is the full observation.
+ * An unmatched dedupeKey falls back to the full observation.
+ */
+export function dedupeSignature(observation, dedupeKey) {
+    if (!dedupeKey)
+        return observation;
+    try {
+        const m = new RegExp(dedupeKey).exec(observation);
+        if (m)
+            return m[1] ?? m[0];
+    }
+    catch {
+        /* invalid regex — fall back to full observation */
+    }
+    return observation;
+}
+function hashSignature(observation, dedupeKey) {
+    return createHash('sha256').update(dedupeSignature(observation, dedupeKey)).digest('hex');
+}
+/**
+ * True when `observation`'s de-dupe signature differs from the monitor's
+ * last-seen signature (or the monitor has never been observed). Pure read — the
+ * caller persists the new value via writeState only on a real fire.
+ */
+export function hasChanged(name, observation, dedupeKey) {
+    const prev = readState(name);
+    if (!prev)
+        return true;
+    return prev.lastHash !== hashSignature(observation, dedupeKey);
+}
+/**
+ * Append a fire timestamp and return the pruned window (fires within `windowMs`).
+ * The engine uses the returned length to decide whether the rate limit tripped.
+ */
+export function recordFireTime(name, now, windowMs) {
+    const prev = readState(name);
+    const times = [...(prev?.fireTimes ?? []), now].filter((t) => now - t <= windowMs);
+    return times;
+}
+/** Write a fire record to fires/<id>/event.json and return the fire id. */
+export function writeFireRecord(event, meta = {}) {
+    ensureAgentsDir();
+    const fireId = event.firedAt.replace(/[:.]/g, '-');
+    const fireDir = safeJoin(getMonitorFiresDir(event.monitorName), fireId);
+    fs.mkdirSync(fireDir, { recursive: true });
+    fs.writeFileSync(path.join(fireDir, 'event.json'), JSON.stringify({ ...event, ...meta }, null, 2), 'utf-8');
+    return fireId;
+}
+/** List a monitor's fire history, chronologically ascending. */
+export function listFires(name) {
+    const dir = getMonitorFiresDir(name);
+    if (!fs.existsSync(dir))
+        return [];
+    const ids = fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort();
+    const fires = [];
+    for (const id of ids) {
+        const eventPath = path.join(dir, id, 'event.json');
+        if (!fs.existsSync(eventPath))
+            continue;
+        try {
+            fires.push(JSON.parse(fs.readFileSync(eventPath, 'utf-8')));
+        }
+        catch {
+            /* skip corrupt record */
+        }
+    }
+    return fires;
+}

package/dist/lib/platform/exec.d.ts

@@ -66,3 +66,19 @@ export declare function quoteWin32ExecArg(arg: string): string;
  * line is byte-identical to the old unquoted join for the common case.
  */
 export declare function composeWin32CommandLine(command: string, args: string[]): string;
+/**
+ * DEP0190-safe execFile/spawn spec when the binary may need `shell: true` on Windows.
+ *
+ * When `needsWindowsShell(bin)` is true, compose ONE fully-quoted command line via
+ * `composeWin32CommandLine` and return an EMPTY args array so Node never concatenates
+ * user-controlled argv (MCP command/args, prompts, …) into the cmd.exe line unescaped.
+ * Off that path the original bin+args are returned unchanged.
+ *
+ * Call as: `const s = execFileShellSpec(bin, args); execFile(s.command, s.args, { shell: s.shell })`.
+ * Pure; optional `platform` override keeps the win32 branch unit-testable on any host.
+ */
+export declare function execFileShellSpec(bin: string, args: string[], platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+    shell: boolean;
+};

package/dist/lib/platform/exec.js

@@ -119,3 +119,20 @@ export function quoteWin32ExecArg(arg) {
 export function composeWin32CommandLine(command, args) {
     return [command, ...args].map(quoteWin32ExecArg).join(' ');
 }
+/**
+ * DEP0190-safe execFile/spawn spec when the binary may need `shell: true` on Windows.
+ *
+ * When `needsWindowsShell(bin)` is true, compose ONE fully-quoted command line via
+ * `composeWin32CommandLine` and return an EMPTY args array so Node never concatenates
+ * user-controlled argv (MCP command/args, prompts, …) into the cmd.exe line unescaped.
+ * Off that path the original bin+args are returned unchanged.
+ *
+ * Call as: `const s = execFileShellSpec(bin, args); execFile(s.command, s.args, { shell: s.shell })`.
+ * Pure; optional `platform` override keeps the win32 branch unit-testable on any host.
+ */
+export function execFileShellSpec(bin, args, platform = process.platform) {
+    if (!needsWindowsShell(bin, platform)) {
+        return { command: bin, args, shell: false };
+    }
+    return { command: composeWin32CommandLine(bin, args), args: [], shell: true };
+}

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);

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;