@phnx-labs/agents-cli 1.20.52 → 1.20.53

package/dist/lib/plugins.js

@@ -98,6 +98,7 @@ export function buildDiscoveredPlugin(pluginRoot, manifest, spec = { kind: 'user
         scripts: discoverPluginScripts(pluginRoot),
         commands: discoverPluginCommands(pluginRoot),
         agentDefs: discoverPluginAgentDefs(pluginRoot),
+        memory: discoverPluginMemory(pluginRoot),
         bin: discoverPluginBin(pluginRoot),
         mcpServers: discoverPluginMcpServers(pluginRoot),
         lspServers: discoverPluginLspServers(pluginRoot),
@@ -118,6 +119,7 @@ export function pluginResourceGroups(plugin) {
         { label: 'commands', items: plugin.commands.map((c) => `/${plugin.name}:${c}`) },
         { label: 'subagents', items: plugin.agentDefs },
         { label: 'hooks', items: plugin.hooks },
+        { label: 'memory', items: plugin.memory },
         { label: 'mcp', items: plugin.mcpServers },
         { label: 'lsp', items: plugin.lspServers },
         { label: 'monitors', items: plugin.monitors },
@@ -225,6 +227,22 @@ export function pluginSupportsAgent(plugin, agent) {
     return true;
 }
 // ─── Discovery helpers ────────────────────────────────────────────────────────
+/** Fact basenames (no .md) from a plugin's memory/ directory. */
+export function discoverPluginMemory(pluginRoot) {
+    const dir = path.join(pluginRoot, 'memory');
+    if (!fs.existsSync(dir))
+        return [];
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.md') && f.toLowerCase() !== 'memory.md')
+            .map((f) => f.replace(/\.md$/i, ''))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
 function discoverPluginSkills(pluginRoot) {
     const skillsDir = path.join(pluginRoot, 'skills');
     if (!fs.existsSync(skillsDir))
@@ -475,6 +493,24 @@ export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
     if (!pluginSupportsAgent(plugin, agent)) {
         return result;
     }
+    // OpenCode uses TS/JS modules under ~/.config/opencode/plugins/, not the
+    // Claude marketplace layout. Install those modules and return early.
+    if (agent === 'opencode') {
+        const ok = installOpenCodePlugin(plugin, versionHome);
+        result.success = ok;
+        if (ok)
+            result.skills.push(plugin.name);
+        return result;
+    }
+    // Goose loads Open Plugins from $HOME/.agents/plugins/<name>/ (same layout as
+    // agents-cli's source tree). Under the shim HOME is the version home.
+    if (agent === 'goose') {
+        const ok = installGoosePlugin(plugin, versionHome);
+        result.success = ok;
+        if (ok)
+            result.skills.push(plugin.name);
+        return result;
+    }
     const userConfig = loadUserConfig(plugin.name);
     // Route every marketplace op through the plugin's own marketplace, so a plugin
     // discovered in an extra/project repo installs under its own
@@ -740,6 +776,167 @@ function migrateLegacyFlatLayout(plugin, agent, versionHome) {
         catch { /* ignore */ }
     }
 }
+// ─── OpenCode plugins (TS/JS modules) ─────────────────────────────────────────
+/**
+ * OpenCode loads JS/TS modules from `$HOME/.config/opencode/plugins/` (global)
+ * and `<project>/.opencode/plugins/` (project). Under agents-cli version
+ * isolation HOME is the version home, so we write:
+ *   {versionHome}/.config/opencode/plugins/
+ *
+ * Claude-style marketplace plugins are NOT auto-converted; we install modules
+ * from (in order):
+ *   1. pluginRoot/opencode/*.{ts,js,mjs,cjs}
+ *   2. pluginRoot/plugins/*.{ts,js,mjs,cjs}
+ *   3. pluginRoot/*.{ts,js,mjs,cjs} (excluding *.test.* / *.spec.*)
+ * If none exist, install still succeeds by writing a marker + copying any
+ * package.json so empty plugins don't break sync; opencode simply has nothing
+ * to load until a real module appears.
+ */
+export function openCodePluginsDir(versionHome) {
+    return path.join(versionHome, '.config', 'opencode', 'plugins');
+}
+// OpenCode's local-plugin loader only auto-loads direct *.ts / *.js files under
+// plugins/ — not nested dirs and not .mjs/.cjs (see opencode.ai/docs/plugins).
+const OPENCODE_MODULE_RE = /\.(ts|js)$/i;
+const OPENCODE_TEST_RE = /\.(test|spec)\./i;
+function listOpenCodeModules(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    // readdir without recursion — only loader-visible direct children.
+    return fs.readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isFile() && OPENCODE_MODULE_RE.test(e.name) && !OPENCODE_TEST_RE.test(e.name) && !e.name.startsWith('.'))
+        .map((e) => e.name);
+}
+/** Resolve source module files for an agents-cli plugin to install into OpenCode. */
+export function resolveOpenCodePluginSources(pluginRoot) {
+    for (const sub of ['opencode', 'plugins']) {
+        const dir = path.join(pluginRoot, sub);
+        const files = listOpenCodeModules(dir);
+        if (files.length > 0)
+            return files.map((f) => path.join(dir, f));
+    }
+    return listOpenCodeModules(pluginRoot).map((f) => path.join(pluginRoot, f));
+}
+export function installOpenCodePlugin(plugin, versionHome) {
+    const destDir = openCodePluginsDir(versionHome);
+    fs.mkdirSync(destDir, { recursive: true });
+    const sources = resolveOpenCodePluginSources(plugin.root);
+    const destPluginDir = path.join(destDir, plugin.name);
+    // Clean previous install of this plugin name (file or dir)
+    const bareTs = path.join(destDir, `${plugin.name}.ts`);
+    const bareJs = path.join(destDir, `${plugin.name}.js`);
+    for (const p of [bareTs, bareJs, destPluginDir]) {
+        try {
+            if (fs.existsSync(p))
+                fs.rmSync(p, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+    }
+    if (sources.length === 0) {
+        // No TS/JS modules — still create a managed marker so isPluginSynced can
+        // track that we processed the plugin (and so re-sync is idempotent).
+        fs.mkdirSync(destPluginDir, { recursive: true });
+        fs.writeFileSync(path.join(destPluginDir, '.agents-cli-managed'), `plugin=${plugin.name}\n# no opencode modules found under ${plugin.root}\n`, 'utf-8');
+        return true;
+    }
+    // Install each module as a direct file under plugins/ so the loader sees it.
+    // Multi-module plugins get `<name>` or `<name>-<stem>` basenames (never a
+    // nested directory — OpenCode does not scan nested plugin dirs).
+    for (let i = 0; i < sources.length; i++) {
+        const src = sources[i];
+        const ext = path.extname(src);
+        const stem = path.basename(src, ext);
+        const destName = sources.length === 1
+            ? `${plugin.name}${ext}`
+            : (stem === 'index' || stem === plugin.name
+                ? `${plugin.name}${ext}`
+                : `${plugin.name}-${stem}${ext}`);
+        fs.copyFileSync(src, path.join(destDir, destName));
+    }
+    // Marker file so isOpenCodePluginInstalled / remove can track multi-file installs.
+    fs.mkdirSync(destPluginDir, { recursive: true });
+    fs.writeFileSync(path.join(destPluginDir, '.agents-cli-managed'), `plugin=${plugin.name}\nfiles=${sources.map((s) => path.basename(s)).join(',')}\n`, 'utf-8');
+    return true;
+}
+export function isOpenCodePluginInstalled(pluginName, versionHome) {
+    const destDir = openCodePluginsDir(versionHome);
+    if (!fs.existsSync(destDir))
+        return false;
+    for (const candidate of [
+        path.join(destDir, `${pluginName}.ts`),
+        path.join(destDir, `${pluginName}.js`),
+        path.join(destDir, `${pluginName}.mjs`),
+        path.join(destDir, `${pluginName}.cjs`),
+        path.join(destDir, pluginName),
+    ]) {
+        if (fs.existsSync(candidate))
+            return true;
+    }
+    return false;
+}
+export function removeOpenCodePlugin(pluginName, versionHome) {
+    const destDir = openCodePluginsDir(versionHome);
+    let removed = false;
+    for (const candidate of [
+        path.join(destDir, `${pluginName}.ts`),
+        path.join(destDir, `${pluginName}.js`),
+        path.join(destDir, pluginName),
+    ]) {
+        if (fs.existsSync(candidate)) {
+            fs.rmSync(candidate, { recursive: true, force: true });
+            removed = true;
+        }
+    }
+    // Flat multi-module installs: <name>-<stem>.ts/js next to the marker dir.
+    if (fs.existsSync(destDir)) {
+        for (const entry of fs.readdirSync(destDir)) {
+            if (entry.startsWith(`${pluginName}-`) && /\.(ts|js)$/i.test(entry)) {
+                try {
+                    fs.rmSync(path.join(destDir, entry), { force: true });
+                    removed = true;
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    return removed;
+}
+// ─── Goose plugins (Open Plugins under .agents/plugins/) ─────────────────────
+/**
+ * Goose auto-discovers Open Plugins at `$HOME/.agents/plugins/<name>/`.
+ * Under agents-cli version isolation HOME is the version home, so we install to:
+ *   {versionHome}/.agents/plugins/<name>/
+ *
+ * Full plugin directory copy (not marketplace) — same layout goose and
+ * agents-cli share for source plugins.
+ */
+export function goosePluginsDir(versionHome) {
+    return path.join(versionHome, '.agents', 'plugins');
+}
+export function installGoosePlugin(plugin, versionHome) {
+    const destRoot = path.join(goosePluginsDir(versionHome), plugin.name);
+    try {
+        if (fs.existsSync(destRoot)) {
+            fs.rmSync(destRoot, { recursive: true, force: true });
+        }
+        fs.cpSync(plugin.root, destRoot, { recursive: true });
+        fs.writeFileSync(path.join(destRoot, '.agents-cli-managed'), `plugin=${plugin.name}\n`, 'utf-8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isGoosePluginInstalled(pluginName, versionHome) {
+    return fs.existsSync(path.join(goosePluginsDir(versionHome), pluginName));
+}
+export function removeGoosePlugin(pluginName, versionHome) {
+    const destRoot = path.join(goosePluginsDir(versionHome), pluginName);
+    if (!fs.existsSync(destRoot))
+        return false;
+    fs.rmSync(destRoot, { recursive: true, force: true });
+    return true;
+}
 // ─── Sync status ──────────────────────────────────────────────────────────────
 /**
  * Check if a plugin is synced to a version. True when the plugin lives at the
@@ -749,6 +946,12 @@ function migrateLegacyFlatLayout(plugin, agent, versionHome) {
 export function isPluginSynced(plugin, agent, versionHome) {
     if (!isCapable(agent, 'plugins'))
         return false;
+    if (agent === 'opencode') {
+        return isOpenCodePluginInstalled(plugin.name, versionHome);
+    }
+    if (agent === 'goose') {
+        return isGoosePluginInstalled(plugin.name, versionHome);
+    }
     const spec = marketplaceSpecForName(plugin.marketplace);
     if (!isInstalledInMarketplace(plugin.name, spec, agent, versionHome))
         return false;
@@ -776,6 +979,20 @@ export function removePluginFromVersion(pluginName, pluginRoot, agent, versionHo
         permissions: 0,
         mcp: 0,
     };
+    // OpenCode: remove TS/JS modules from ~/.config/opencode/plugins/.
+    if (agent === 'opencode') {
+        if (removeOpenCodePlugin(pluginName, versionHome)) {
+            result.skills.push(pluginName);
+        }
+        return result;
+    }
+    // Goose: remove Open Plugin directory from versionHome/.agents/plugins/.
+    if (agent === 'goose') {
+        if (removeGoosePlugin(pluginName, versionHome)) {
+            result.skills.push(pluginName);
+        }
+        return result;
+    }
     // 1. Remove the plugin from every marketplace it's installed under. A name can
     //    appear in more than one (collision across repos), so we sweep them all.
     let removedAny = false;

package/dist/lib/remote-agents-json.d.ts

@@ -0,0 +1,14 @@
+export interface RemoteAgentsJsonOptions<T> {
+    args: string[];
+    noFanoutEnv: string;
+    hosts?: string[];
+    parse: (stdout: string, machine: string) => T[];
+}
+export interface RemoteAgentsJsonResult<T> {
+    items: T[];
+    deviceCount: number;
+}
+/** Build the command one peer runs, with a guard that prevents recursive fan-out. */
+export declare function remoteAgentsJsonCommand(args: string[], noFanoutEnv: string, os?: string): string;
+/** Query explicit hosts, or every registered online peer when hosts is omitted. */
+export declare function gatherRemoteAgentsJson<T>(options: RemoteAgentsJsonOptions<T>): Promise<RemoteAgentsJsonResult<T>>;

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

@@ -0,0 +1,94 @@
+/**
+ * Shared cross-machine fan-out for JSON-producing `agents` commands.
+ *
+ * Registered online devices are queried in parallel over the canonical SSH
+ * transport. A recursion-guard environment variable makes each peer answer for
+ * itself, and version-skewed or unreachable peers are skipped without hiding
+ * healthy results from the rest of the fleet.
+ */
+import { spawn } from 'child_process';
+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 { remoteShellFor, buildWindowsAgentsCommand } from './hosts/remote-cmd.js';
+import { machineId, normalizeHost } from './machine-id.js';
+const REMOTE_TIMEOUT_MS = 12_000;
+/** Build the command one peer runs, with a guard that prevents recursive fan-out. */
+export function remoteAgentsJsonCommand(args, noFanoutEnv, os) {
+    if (remoteShellFor(os) === 'powershell') {
+        return buildWindowsAgentsCommand({ args, env: { [noFanoutEnv]: '1' } });
+    }
+    const inner = `${noFanoutEnv}=1 agents ${args.map(shellQuote).join(' ')}`;
+    return `bash -lc ${shellQuote(inner)}`;
+}
+function sshCapture(target, remoteCmd) {
+    assertValidSshTarget(target);
+    return new Promise((resolve) => {
+        const args = [...SSH_OPTS, ...controlOpts(), target, remoteCmd];
+        const child = spawn('ssh', args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        let settled = false;
+        const done = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ code, stdout });
+        };
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            done(null);
+        }, REMOTE_TIMEOUT_MS);
+        child.stdout.on('data', (data) => { stdout += data.toString(); });
+        child.on('error', () => done(null));
+        child.on('close', (code) => done(code));
+    });
+}
+/** Query explicit hosts, or every registered online peer when hosts is omitted. */
+export async function gatherRemoteAgentsJson(options) {
+    const self = machineId();
+    const targets = [];
+    if (options.hosts && options.hosts.length > 0) {
+        targets.push(...await resolveExplicitTargets(options.hosts));
+    }
+    else {
+        let devices;
+        try {
+            devices = await loadDevices();
+        }
+        catch {
+            return { items: [], deviceCount: 0 };
+        }
+        for (const device of Object.values(devices)) {
+            if (device.tailscale?.online !== true)
+                continue;
+            if (normalizeHost(device.name) === self)
+                continue;
+            if (!['windows', 'linux', 'macos'].includes(device.platform))
+                continue;
+            try {
+                targets.push({
+                    target: sshTargetFor(device),
+                    machine: normalizeHost(device.name),
+                    name: device.name,
+                    os: device.platform,
+                });
+            }
+            catch {
+                // A registered profile without a dialable address is not a peer yet.
+            }
+        }
+    }
+    const results = await Promise.all(targets.map(async (target) => {
+        const command = remoteAgentsJsonCommand(options.args, options.noFanoutEnv, target.os);
+        const result = await sshCapture(target.target, command);
+        if (result.code !== 0) {
+            process.stderr.write(chalk.gray(`  ${target.name}: unreachable or no agents CLI — skipped\n`));
+            return [];
+        }
+        return options.parse(result.stdout, target.machine);
+    }));
+    return { items: results.flat(), deviceCount: targets.length };
+}

package/dist/lib/resources/mcp.js

@@ -123,6 +123,10 @@ export function getMcpConfigPath(agent, versionHome) {
             return path.join(versionHome, '.gemini', 'antigravity-cli', 'mcp_config.json');
         case 'grok':
             return path.join(versionHome, '.grok', 'mcp.json');
+        case 'hermes':
+            return path.join(versionHome, '.hermes', 'config.yaml');
+        case 'forge':
+            return path.join(versionHome, '.forge', '.mcp.json');
         default:
             return null;
     }
@@ -271,6 +275,38 @@ function syncToGrokConfig(configPath, items) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
 }
+function syncToHermesConfig(configPath, items) {
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            const parsed = yaml.parse(fs.readFileSync(configPath, 'utf-8'));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                config = parsed;
+            }
+        }
+        catch {
+            config = {};
+        }
+    }
+    const mcpServers = {};
+    for (const item of items) {
+        if (item.transport === 'stdio') {
+            mcpServers[item.name] = {
+                command: item.command,
+                args: item.args || [],
+                ...(item.env && { env: item.env }),
+            };
+        }
+        else {
+            mcpServers[item.name] = {
+                url: item.url,
+            };
+        }
+    }
+    config.mcp_servers = mcpServers;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, yaml.stringify(config), 'utf-8');
+}
 /**
  * Write MCP servers to OpenCode opencode.jsonc format.
  */
@@ -502,6 +538,12 @@ export const McpHandler = {
             case 'grok':
                 syncToGrokConfig(configPath, mcpItems);
                 break;
+            case 'hermes':
+                syncToHermesConfig(configPath, mcpItems);
+                break;
+            case 'forge':
+                syncToCursorConfig(configPath, mcpItems);
+                break;
         }
     },
     format(agent) {
@@ -509,6 +551,8 @@ export const McpHandler = {
             case 'codex':
             case 'grok':
                 return 'toml';
+            case 'hermes':
+                return 'yaml';
             default:
                 return 'json';
         }

package/dist/lib/resources/memory.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Memory resource handler — knowledge/facts store (not rules/instructions).
+ *
+ * Canonical source: layered `memory/` dirs under project/user/system agents
+ * roots. Sync copies into each capable agent's version home (see memory.ts).
+ */
+import type { ResourceHandler } from './types.js';
+export interface MemoryItem {
+    name: string;
+    content: string;
+    summary: string;
+}
+export declare const MemoryHandler: ResourceHandler<MemoryItem>;
+/** Convenience: list fact names for a cwd. */
+export declare function listMemoryNames(cwd?: string): string[];

package/dist/lib/resources/memory.js

@@ -0,0 +1,46 @@
+/**
+ * Memory resource handler — knowledge/facts store (not rules/instructions).
+ *
+ * Canonical source: layered `memory/` dirs under project/user/system agents
+ * roots. Sync copies into each capable agent's version home (see memory.ts).
+ */
+import * as fs from 'fs';
+import { listMemoryFacts, readMemoryFact, syncMemoryToVersionHome, memoryTargetDir, } from '../memory.js';
+function toItem(fact) {
+    let content = '';
+    try {
+        content = fs.readFileSync(fact.path, 'utf-8');
+    }
+    catch {
+        content = '';
+    }
+    return {
+        name: fact.name,
+        item: { name: fact.name, content, summary: fact.summary },
+        layer: fact.layer,
+        path: fact.path,
+    };
+}
+export const MemoryHandler = {
+    kind: 'memory',
+    listAll(_agent, cwd) {
+        return listMemoryFacts(cwd).map(toItem);
+    },
+    resolve(_agent, name, cwd) {
+        const fact = readMemoryFact(name, cwd);
+        return fact ? toItem(fact) : null;
+    },
+    sync(agent, versionHome, cwd) {
+        syncMemoryToVersionHome(agent, versionHome, cwd);
+    },
+    format(_agent) {
+        return 'md';
+    },
+    targetDir(agent) {
+        return memoryTargetDir(agent);
+    },
+};
+/** Convenience: list fact names for a cwd. */
+export function listMemoryNames(cwd) {
+    return listMemoryFacts(cwd).map((f) => f.name);
+}

package/dist/lib/resources/types.d.ts

@@ -5,9 +5,9 @@
  * - Union: All resources from all layers are combined
  * - Override on name conflict: Higher layer wins (project > user > system)
  */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'antigravity' | 'grok' | 'kimi';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'antigravity' | 'grok' | 'kimi' | 'hermes' | 'forge';
 export type Layer = 'system' | 'user' | 'project';
-export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent' | 'workflow';
+export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent' | 'workflow' | 'memory';
 /** A resolved resource with its origin layer. */
 export interface ResolvedItem<T> {
     name: string;

package/dist/lib/runner.d.ts

@@ -5,10 +5,19 @@
  * sandboxed or unsandboxed environments, captures stdout to log files,
  * enforces timeouts, and extracts the final assistant report from the
  * agent's stream-JSON output.
+ *
+ * Version/account selection mirrors `agents run`: when a routine does not pin
+ * `version:`, the runner uses the configured run strategy (default `balanced`)
+ * to pick a healthy install, pins the absolute binary via `getBinaryPath`, and
+ * arms same-agent failover across other healthy accounts when a rate/usage
+ * limit is detected mid-run (foreground `executeJob` only — detached daemon
+ * fires once with the pre-flight pick).
  */
 import type { JobConfig, RunMeta } from './routines.js';
 import type { AgentId } from './types.js';
+import { type FallbackEntry } from './exec.js';
 import type { LoopDeps } from './loop.js';
+import { type RotateResult } from './rotate.js';
 /** Result of a completed job execution, including metadata and optional report. */
 export interface RunResult {
     meta: RunMeta;
@@ -16,6 +25,37 @@ export interface RunResult {
 }
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export declare function buildJobCommand(config: JobConfig, resolvedPrompt: string): string[];
+/** Pre-flight version/account selection for a routine job. */
+export interface RoutineLaunchPlan {
+    /** Ordered attempts: primary first, then same-agent failover accounts. */
+    chain: FallbackEntry[];
+    /** Full rotation result when strategy selected among healthy accounts; null when pinned. */
+    rotation: RotateResult | null;
+    /** True when `config.version` pinned the target (no rotation). */
+    pinned: boolean;
+}
+/**
+ * Resolve the version/account chain for a routine the same way `agents run`
+ * does: honor an explicit `version:` pin; otherwise use the configured run
+ * strategy (default `balanced`) so credit-exhausted / rate-limited accounts
+ * are skipped pre-flight, and synthesize a same-agent failover chain from the
+ * other healthy accounts for mid-run rate limits.
+ *
+ * Workflows are left alone — `agents run <workflow>` owns selection.
+ */
+export declare function resolveRoutineLaunch(config: JobConfig, cwd?: string): Promise<RoutineLaunchPlan>;
+/**
+ * Rewrite `cmd[0]` to the absolute binary for `agent@version` when installed.
+ * Bypasses the bare-name shim so a sandboxed HOME / missing default pin cannot
+ * surface as "agents: no version of X configured".
+ */
+export declare function pinJobBinary(cmd: string[], agent: AgentId, version: string | undefined): string[];
+/**
+ * Merge sandbox/base env with the canonical per-version exec env
+ * (CLAUDE_CONFIG_DIR / CODEX_HOME / …) so routines share account isolation
+ * with `agents run`.
+ */
+export declare function buildRoutineSpawnEnv(baseEnv: Record<string, string>, agent: AgentId, version: string | undefined, timezone?: string): Record<string, string>;
 /**
  * Execute a job synchronously (waits for completion or timeout before resolving).
  *
@@ -24,6 +64,9 @@ export declare function buildJobCommand(config: JobConfig, resolvedPrompt: strin
  * workflow `loop:` blocks (issue #400). The optional `deps` parameter provides
  * injectable seams (runIteration, sleep, writeCheckpoint) used by tests; production
  * callers omit it and get the defaults.
+ *
+ * Single-shot path: pre-flight version/account selection + mid-run rate-limit
+ * failover across healthy same-agent accounts (RUSH-1016).
  */
 export declare function executeJob(config: JobConfig, deps?: LoopDeps): Promise<RunResult>;
 /** Spawn a job as a detached process and return immediately with run metadata. */