@phnx-labs/agents-cli 1.20.63 → 1.20.65

package/dist/lib/agents.d.ts

@@ -127,9 +127,43 @@ export interface AccountInfo {
     } | null;
     lastActive: Date | null;
     signedIn: boolean;
+    organizationType?: string | null;
+    organizationName?: string | null;
 }
+/**
+ * Human-readable label for a Claude account's organizationType as read from
+ * .claude.json's oauthAccount ("claude_team" -> "Team"). Unrecognized values
+ * (future tiers) are rendered by stripping the "claude_" prefix and
+ * title-casing the rest — an unfamiliar-but-visible label beats silence.
+ * Returns null for missing input.
+ */
+export declare function formatClaudeOrgLabel(orgType: string | null | undefined): string | null;
+/**
+ * Short badge identifying which org an account belongs to: "Turing Labs · Team"
+ * for multi-seat orgs, just the tier label ("Max") for personal plans — a
+ * personal org's name is auto-generated boilerplate ("<email>'s Organization"),
+ * not identity. Returns null when the account carries no organizationType
+ * (signed out, non-Claude agents, configs predating the field).
+ */
+export declare function accountOrgBadge(info?: Pick<AccountInfo, 'organizationType' | 'organizationName'> | null): string | null;
 /** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;
+/** Decrypted contents of Droid's auth.v2.file (subset we consume). */
+export interface DroidAuthPayload {
+    access_token?: string;
+    active_organization_id?: string | null;
+}
+/**
+ * Factory Droid stores its OAuth credential encrypted at ~/.factory/auth.v2.file
+ * (AES-256-GCM, format `ivB64:tagB64:ctB64`) with the 32-byte key base64-stored
+ * in ~/.factory/auth.v2.key. On the keyfile-v2 source there is no OS-keychain /
+ * device binding — the key is on disk — so we can decrypt locally with no
+ * network call. Every failure (missing key file — e.g. a keyring-v2/legacy
+ * login with no on-disk key, a bad GCM tag, or malformed JSON) returns null.
+ * Never throws. Shared by account identity below and the Droid usage fetcher
+ * in usage.ts.
+ */
+export declare function decryptDroidAuthPayload(base: string): DroidAuthPayload | null;
 /**
  * Antigravity (`agy`) stores its OAuth token via the Go keyring library
  * (zalando/go-keyring), which is platform-split:
@@ -173,6 +207,8 @@ export declare function resolveLastActive(agentId: AgentId, base: string, config
  * Used during init to show approximate session count to user.
  */
 export declare function countSessionFiles(agentId: AgentId): number;
+/** Decode the payload section of a JWT token without verifying its signature. */
+export declare function decodeJwtPayload(token: string): Record<string, any> | null;
 /** Register an MCP server with an agent's CLI via `mcp add`. */
 export declare function registerMcp(agentId: AgentId, name: string, command: string, scope?: 'user' | 'project', transport?: string, options?: {
     home?: string;

package/dist/lib/agents.js

@@ -17,7 +17,7 @@ import * as os from 'os';
 import * as TOML from 'smol-toml';
 import * as yaml from 'yaml';
 import chalk from 'chalk';
-import { needsWindowsShell } from './platform/index.js';
+import { execFileShellSpec } from './platform/index.js';
 import { latestFileMtimeMs } from './fs-walk.js';
 import { damerauLevenshtein } from './fuzzy.js';
 import { getCacheDir, getVersionsDir, getShimsDir, getCliVersionCachePath } from './state.js';
@@ -943,6 +943,48 @@ export function ensureSkillsDir(agentId) {
 export function agentConfigDirName(agentId) {
     return path.relative(HOME, AGENTS[agentId].configDir);
 }
+/**
+ * Human-readable label for a Claude account's organizationType as read from
+ * .claude.json's oauthAccount ("claude_team" -> "Team"). Unrecognized values
+ * (future tiers) are rendered by stripping the "claude_" prefix and
+ * title-casing the rest — an unfamiliar-but-visible label beats silence.
+ * Returns null for missing input.
+ */
+export function formatClaudeOrgLabel(orgType) {
+    if (!orgType)
+        return null;
+    const known = {
+        claude_max: 'Max',
+        claude_pro: 'Pro',
+        claude_team: 'Team',
+        claude_enterprise: 'Enterprise',
+        claude_free: 'Free',
+    };
+    if (known[orgType])
+        return known[orgType];
+    return orgType
+        .replace(/^claude_/, '')
+        .split('_')
+        .filter(Boolean)
+        .map((w) => w[0].toUpperCase() + w.slice(1))
+        .join(' ');
+}
+/**
+ * Short badge identifying which org an account belongs to: "Turing Labs · Team"
+ * for multi-seat orgs, just the tier label ("Max") for personal plans — a
+ * personal org's name is auto-generated boilerplate ("<email>'s Organization"),
+ * not identity. Returns null when the account carries no organizationType
+ * (signed out, non-Claude agents, configs predating the field).
+ */
+export function accountOrgBadge(info) {
+    const label = formatClaudeOrgLabel(info?.organizationType);
+    if (!label)
+        return null;
+    const isMultiSeat = info?.organizationType === 'claude_team' || info?.organizationType === 'claude_enterprise';
+    if (isMultiSeat && info?.organizationName)
+        return `${info.organizationName} · ${label}`;
+    return label;
+}
 /** Return the email address associated with the agent's auth config, or null. */
 export async function getAccountEmail(agentId, home) {
     const info = await getAccountInfo(agentId, home);
@@ -984,15 +1026,12 @@ function resolveAccountCredentialPath(base, ...segments) {
  * (AES-256-GCM, format `ivB64:tagB64:ctB64`) with the 32-byte key base64-stored
  * in ~/.factory/auth.v2.key. On the keyfile-v2 source there is no OS-keychain /
  * device binding — the key is on disk — so we can decrypt locally with no
- * network call. The decrypted JSON credential's `access_token` is a WorkOS JWT
- * carrying an `email` claim (plus org_id / role). We decode the claim WITHOUT
- * verifying `exp`: the email is stable identity for display, not an
- * authorization decision, so an expired token still yields the right address.
- * Every failure (missing key file — e.g. a keyring-v2/legacy login with no
- * on-disk key, a bad GCM tag, malformed JSON, or no email claim) returns null so
- * the caller falls back to the file-presence signed-in signal. Never throws.
+ * network call. Every failure (missing key file — e.g. a keyring-v2/legacy
+ * login with no on-disk key, a bad GCM tag, or malformed JSON) returns null.
+ * Never throws. Shared by account identity below and the Droid usage fetcher
+ * in usage.ts.
  */
-function decryptDroidCredential(base) {
+export function decryptDroidAuthPayload(base) {
     const filePath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.file');
     const keyPath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.key');
     if (!filePath || !keyPath)
@@ -1012,19 +1051,32 @@ function decryptDroidCredential(base) {
             decipher.final(),
         ]).toString('utf-8');
         const cred = JSON.parse(plaintext);
-        const claims = typeof cred?.access_token === 'string' ? decodeJwtPayload(cred.access_token) : null;
-        if (!claims)
-            return null;
-        return {
-            email: typeof claims.email === 'string' ? claims.email : null,
-            orgId: normalizeIdentityPart(claims.org_id ?? cred.active_organization_id),
-            role: typeof claims.role === 'string' ? claims.role : null,
-        };
+        return cred && typeof cred === 'object' ? cred : null;
     }
     catch {
         return null;
     }
 }
+/**
+ * Derive Droid account identity from the decrypted credential. The
+ * `access_token` is a WorkOS JWT carrying an `email` claim (plus org_id /
+ * role). We decode the claim WITHOUT verifying `exp`: the email is stable
+ * identity for display, not an authorization decision, so an expired token
+ * still yields the right address. Returns null when the credential can't be
+ * decrypted or has no decodable claims, so the caller falls back to the
+ * file-presence signed-in signal.
+ */
+function decryptDroidCredential(base) {
+    const cred = decryptDroidAuthPayload(base);
+    const claims = typeof cred?.access_token === 'string' ? decodeJwtPayload(cred.access_token) : null;
+    if (!claims)
+        return null;
+    return {
+        email: typeof claims.email === 'string' ? claims.email : null,
+        orgId: normalizeIdentityPart(claims.org_id ?? cred?.active_organization_id),
+        role: typeof claims.role === 'string' ? claims.role : null,
+    };
+}
 let cachedAgyKeychainSignedIn;
 /**
  * Antigravity (`agy`) stores its OAuth token via the Go keyring library
@@ -1238,6 +1290,8 @@ export async function getAccountInfo(agentId, home) {
                     overageCredits,
                     lastActive,
                     signedIn: !!email,
+                    organizationType: oa?.organizationType ?? null,
+                    organizationName: oa?.organizationName ?? null,
                 };
             }
             case 'codex': {
@@ -1564,7 +1618,7 @@ export function countSessionFiles(agentId) {
     return count;
 }
 /** Decode the payload section of a JWT token without verifying its signature. */
-function decodeJwtPayload(token) {
+export function decodeJwtPayload(token) {
     const payload = token.split('.')[1];
     if (!payload)
         return null;
@@ -1649,7 +1703,10 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
         // On Windows a bare command name / `.cmd` wrapper (the npm-installed agent
         // CLI) can't be exec'd directly — it needs shell:true for PATHEXT/cmd. Off
         // Windows this is always false, so the no-shell argv path is unchanged.
-        await execFileAsync(bin, args, { ...(env ? { env } : {}), shell: needsWindowsShell(bin) });
+        // RUSH-1752: when shell is needed, compose a fully-quoted command line and
+        // pass EMPTY argv so user-controlled MCP command/args never reach cmd.exe unescaped.
+        const spec = execFileShellSpec(bin, args);
+        await execFileAsync(spec.command, spec.args, { ...(env ? { env } : {}), shell: spec.shell });
         return { success: true };
     }
     catch (err) {
@@ -1677,7 +1734,10 @@ export async function unregisterMcp(agentId, name, options) {
     try {
         const bin = options?.binary || agent.cliCommand;
         const env = options?.home ? { ...process.env, HOME: options.home } : undefined;
-        await execFileAsync(bin, ['mcp', 'remove', name], { ...(env ? { env } : {}), shell: needsWindowsShell(bin) });
+        // RUSH-1752: same shell-safe path as registerMcp — attacker-controlled MCP
+        // `name` must not reach cmd.exe unescaped when shell:true is required.
+        const spec = execFileShellSpec(bin, ['mcp', 'remove', name]);
+        await execFileAsync(spec.command, spec.args, { ...(env ? { env } : {}), shell: spec.shell });
         return { success: true };
     }
     catch (err) {

package/dist/lib/auto-dispatch-provider.js

@@ -9,7 +9,7 @@
 import { resolveProvider } from './cloud/registry.js';
 export function createProviderDispatcher() {
     return {
-        async dispatch({ agent, prompt, repo, provider }) {
+        async dispatch({ agent, prompt, repo, provider, host }) {
             const p = resolveProvider(provider, agent);
             const caps = p.capabilities();
             if (!caps.available) {
@@ -18,7 +18,12 @@ export function createProviderDispatcher() {
             if (!caps.dispatch) {
                 throw new Error(`cloud provider '${p.id}' does not support dispatch`);
             }
-            const task = await p.dispatch({ agent, prompt, repo });
+            // The host provider clones nothing — a repo target is meaningless there
+            // and its dispatch() rejects it; a ticket project pinned to 'host' relies
+            // on the machine's own checkout (the project's `host` names the machine).
+            const task = p.id === 'host'
+                ? await p.dispatch({ agent, prompt, providerOptions: { host } })
+                : await p.dispatch({ agent, prompt, repo });
             return { id: task.id };
         },
     };

package/dist/lib/auto-dispatch.d.ts

@@ -22,6 +22,7 @@ export interface AutoDispatchProject {
     autoDispatch?: boolean;
     maxAgents?: number;
     provider?: string;
+    host?: string;
 }
 /** A Linear issue that is a candidate for dispatch. */
 export interface DelegatedIssue {
@@ -36,6 +37,7 @@ export interface PlannedDispatch {
     projectId: string;
     repoSlug?: string;
     provider?: string;
+    host?: string;
     issueId: string;
     identifier: string;
     title: string;
@@ -73,6 +75,7 @@ export interface Dispatcher {
         prompt: string;
         repo?: string;
         provider?: string;
+        host?: string;
     }): Promise<{
         id: string;
     }>;

package/dist/lib/auto-dispatch.js

@@ -46,6 +46,7 @@ export function readAutoDispatchProjects() {
             autoDispatch: o.autoDispatch === true,
             maxAgents: typeof o.maxAgents === 'number' ? o.maxAgents : undefined,
             provider: typeof o.provider === 'string' ? o.provider : undefined,
+            host: typeof o.host === 'string' ? o.host : undefined,
         });
     }
     return out;
@@ -76,6 +77,7 @@ export function planAutoDispatch(projects, inFlightByProject, delegatedTodoByPro
                 projectId: p.id,
                 repoSlug: p.repoSlug,
                 provider: p.provider,
+                host: p.host,
                 issueId: issue.id,
                 identifier: issue.identifier,
                 title: issue.title,
@@ -122,6 +124,7 @@ export async function autoDispatchTick(deps) {
                 prompt: dispatchPrompt(d.identifier, d.title),
                 repo: d.repoSlug,
                 provider: d.provider,
+                host: d.host,
             });
             // Bookkeeping only — dispatch already happened; moving to Doing keeps the
             // ticket out of the next Todo poll. A failure here is non-fatal.

package/dist/lib/browser/chrome.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { getProfileRuntimeDir } from './profiles.js';
 import { discoverBrowserWsUrl, registerPipeTransport } from './cdp.js';
-import { readAndResolveBundleEnv, bundleExists } from '../secrets/bundles.js';
+import { readAndResolveBundleEnv, bundleExists, isHeadlessSecretsContext } from '../secrets/bundles.js';
 import { writeProfileRuntime, readProfileRuntime } from './runtime-state.js';
 // Windows install roots. Resolve from the environment (fall back to the usual
 // defaults) so per-user installs under %LOCALAPPDATA% and 64-bit Program Files
@@ -260,7 +260,7 @@ isElectron = false) {
     let env = { ...process.env };
     if (secrets && bundleExists(secrets)) {
         try {
-            const { env: bundleEnv } = readAndResolveBundleEnv(secrets, { caller: 'browser profile' });
+            const { env: bundleEnv } = readAndResolveBundleEnv(secrets, { caller: 'browser profile', agentOnly: isHeadlessSecretsContext() });
             env = { ...env, ...bundleEnv };
         }
         catch {

package/dist/lib/browser/drivers/ssh.js

@@ -9,7 +9,7 @@ import { writeProfileRuntime, clearProfileRuntime } from '../runtime-state.js';
 // is the shared hardened baseline (BatchMode + ConnectTimeout + keepalive) —
 // reuse it so the raw-ssh spawns below fail fast on an unreachable host instead
 // of hanging on the default ~127s TCP timeout, rather than re-listing options.
-import { shellQuote, SSH_OPTS } from '../../ssh-exec.js';
+import { shellQuote, SSH_OPTS, assertValidSshTarget } from '../../ssh-exec.js';
 export { shellQuote };
 // The `ssh -L` tunnel spawn is shared with `agents computer --host`; it lives in
 // the single ssh-tunnel helper. Calling it with no options preserves this
@@ -292,6 +292,12 @@ export function buildKillCmd(remoteOs, port) {
     return `pids=$(lsof -ti ${shellQuote(`:${port}`)} 2>/dev/null); [ -z "$pids" ] || kill -9 $pids 2>/dev/null || true`;
 }
 export async function ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
+    // `user`/`host` derive from an ssh:// profile endpoint (git-tracked user
+    // config). Validate the composed target before it reaches the raw `ssh` spawn:
+    // an endpoint like `ssh://-Fattack@victim` would otherwise place `-Fattack` at
+    // the target position, where OpenSSH parses it as `-F <file>` and an
+    // attacker-supplied ssh config's ProxyCommand yields local code execution.
+    assertValidSshTarget(`${user}@${host}`);
     const remoteCmd = buildLaunchCmd(remoteOs, browserType, port, customBinary);
     return new Promise((resolve, reject) => {
         // Capture stderr so a real launch failure (missing exe, auth denied, bad
@@ -362,7 +368,18 @@ export function killRemoteBrowser(user, host, remoteOs, port) {
     return runSSHCommand(user, host, buildKillCmd(remoteOs, port));
 }
 function runSSHCommand(user, host, cmd) {
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
+        // Reject an option-injecting target (e.g. a `-`-leading user from a crafted
+        // ssh:// profile) before it reaches the raw `ssh` spawn. Reject rather than
+        // throw synchronously so `killRemoteBrowser(...).catch()` stays best-effort.
+        // See ensureRemoteBrowser.
+        try {
+            assertValidSshTarget(`${user}@${host}`);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
         // Reuse the shared hardened baseline so a hung TCP SYN to an unreachable
         // host is bounded by ConnectTimeout (the local 3s kill below only bounds a
         // connected-but-slow command, not the connect itself). Options precede the

package/dist/lib/cloud/antigravity.js

@@ -20,7 +20,7 @@
  * back to GEMINI_API_KEY / GOOGLE_API_KEY in the environment.
  */
 import { resolveDispatchRepos, normalizeProviderStatus } from './types.js';
-import { readAndResolveBundleEnv } from '../secrets/bundles.js';
+import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../secrets/bundles.js';
 const INTERACTIONS_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions';
 const DEFAULT_MODEL = 'antigravity-preview-05-2026';
 const KEY_NAMES = ['GEMINI_API_KEY', 'GOOGLE_API_KEY'];
@@ -65,7 +65,7 @@ export class AntigravityCloudProvider {
     resolveApiKey() {
         if (this.secretsBundle) {
             try {
-                const { env } = readAndResolveBundleEnv(this.secretsBundle, { caller: 'cloud:antigravity' });
+                const { env } = readAndResolveBundleEnv(this.secretsBundle, { caller: 'cloud:antigravity', agentOnly: isHeadlessSecretsContext() });
                 for (const k of KEY_NAMES) {
                     if (env[k])
                         return env[k];

package/dist/lib/cloud/host.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Host cloud provider — your own machines as a task-execution backend.
+ *
+ * A thin adapter over the hosts subsystem (lib/hosts/*): `agents cloud run
+ * --provider host --host <name>` dispatches through the SAME detached-SSH
+ * launch as `agents run --host`, and the resulting task shows up in BOTH
+ * `agents cloud ps` and `agents hosts ps` — one store (the host-task sidecars
+ * under ~/.agents/.cache/hosts/), two views. No new transport, no relay: SSH
+ * is the only wire, exactly like the rest of the hosts design (docs/hosts.md).
+ *
+ * Status semantics follow reconcile.ts's prime rule: completion is only ever
+ * CONFIRMED from the remote `.exit` file — an unreachable host leaves a task
+ * `running`, never guessed as failed. The cloud SQLite store row is a cached
+ * index (the `cloud list` refresh loop upserts what `status()` returns); the
+ * sidecar stays the source of truth. Reachability is memoized per target for
+ * the life of the process so a down host costs ONE short timeout, not one per
+ * task ("care around the cloud status-refresh path", lib/hosts/tasks.ts).
+ */
+import type { CloudEvent, CloudProvider, CloudTarget, CloudTask, CloudTaskStatus, DispatchOptions, ProviderCapabilities } from './types.js';
+import type { HostTask } from '../hosts/tasks.js';
+/** Project a host-task sidecar into the cloud task shape. */
+export declare function hostTaskToCloudTask(task: HostTask): CloudTask;
+export declare class HostCloudProvider implements CloudProvider {
+    readonly id: "host";
+    readonly name = "Host (your machines)";
+    readonly targetKind: "host";
+    /**
+     * Reachability memo, per target, for the life of this process. The cloud
+     * refresh loop calls `status()` once per active task; without the memo a
+     * down host would cost one ~6s ssh timeout PER task instead of one total.
+     * CLI processes are short-lived, so staleness is bounded by the invocation.
+     */
+    private reachable;
+    capabilities(): ProviderCapabilities;
+    dispatch(options: DispatchOptions): Promise<CloudTask>;
+    status(taskId: string): Promise<CloudTask>;
+    list(filter?: {
+        status?: CloudTaskStatus;
+    }): Promise<CloudTask[]>;
+    /**
+     * `reconcileTask` with the per-process reachability memo folded in: probe a
+     * target at most once per process; a down host leaves its tasks `running`.
+     */
+    private reconcileMemoized;
+    /**
+     * Offset-tail the remote log (the same one-round-trip fetch the `run --host`
+     * follow uses) and yield it as `text` events until the `.exit` file lands.
+     */
+    stream(taskId: string): AsyncIterable<CloudEvent>;
+    cancel(taskId: string): Promise<void>;
+    /**
+     * Follow-up message = resume the run's session on the same host. Only runs
+     * that captured a session id (Claude — the one agent that takes
+     * `--session-id`) can be resumed; others get an actionable refusal.
+     */
+    message(taskId: string, content: string): Promise<void>;
+    /** The unified host pool (enrolled hosts ∪ devices), dispatchable ones only. */
+    listTargets(): Promise<CloudTarget[]>;
+}

package/dist/lib/cloud/host.js

@@ -0,0 +1,224 @@
+/**
+ * Host cloud provider — your own machines as a task-execution backend.
+ *
+ * A thin adapter over the hosts subsystem (lib/hosts/*): `agents cloud run
+ * --provider host --host <name>` dispatches through the SAME detached-SSH
+ * launch as `agents run --host`, and the resulting task shows up in BOTH
+ * `agents cloud ps` and `agents hosts ps` — one store (the host-task sidecars
+ * under ~/.agents/.cache/hosts/), two views. No new transport, no relay: SSH
+ * is the only wire, exactly like the rest of the hosts design (docs/hosts.md).
+ *
+ * Status semantics follow reconcile.ts's prime rule: completion is only ever
+ * CONFIRMED from the remote `.exit` file — an unreachable host leaves a task
+ * `running`, never guessed as failed. The cloud SQLite store row is a cached
+ * index (the `cloud list` refresh loop upserts what `status()` returns); the
+ * sidecar stays the source of truth. Reachability is memoized per target for
+ * the life of the process so a down host costs ONE short timeout, not one per
+ * task ("care around the cloud status-refresh path", lib/hosts/tasks.ts).
+ */
+import { MissingTargetError, resolveDispatchRepos } from './types.js';
+import { listTasks, loadTask, terminalPatch, updateTask } from '../hosts/tasks.js';
+import { readRemoteExit } from '../hosts/reconcile.js';
+import { sshReachable } from '../ssh-exec.js';
+import { fetchProgress } from '../hosts/progress.js';
+import { dispatchPromptToHost, resolveHostRunTarget } from '../hosts/run-target.js';
+import { listAllHosts } from '../hosts/registry.js';
+import { terminateDispatchedTask } from '../hosts/dispatch.js';
+/** Host-task lifecycle → canonical cloud enum. `unknown` stays `running`
+ *  (completion is confirmed, never guessed — reconcile.ts's rule). */
+function toCloudStatus(status) {
+    switch (status) {
+        case 'completed': return 'completed';
+        case 'failed': return 'failed';
+        case 'running':
+        case 'unknown':
+        default:
+            return 'running';
+    }
+}
+/** Project a host-task sidecar into the cloud task shape. */
+export function hostTaskToCloudTask(task) {
+    return {
+        id: task.id,
+        provider: 'host',
+        status: toCloudStatus(task.status),
+        agent: task.agent,
+        prompt: task.prompt,
+        createdAt: task.createdAt,
+        updatedAt: task.finishedAt ?? task.createdAt,
+        summary: `on ${task.host}${task.name ? ` as "${task.name}"` : ''}`,
+    };
+}
+export class HostCloudProvider {
+    id = 'host';
+    name = 'Host (your machines)';
+    targetKind = 'host';
+    /**
+     * Reachability memo, per target, for the life of this process. The cloud
+     * refresh loop calls `status()` once per active task; without the memo a
+     * down host would cost one ~6s ssh timeout PER task instead of one total.
+     * CLI processes are short-lived, so staleness is bounded by the invocation.
+     */
+    reachable = new Map();
+    capabilities() {
+        return {
+            available: true, // ssh is the only dependency; per-host reachability is probed at dispatch
+            dispatch: true,
+            status: true,
+            list: true,
+            stream: true,
+            cancel: true,
+            message: true, // gated per task: needs the sessionId only Claude runs carry
+            multiRepo: false,
+            skills: false,
+            images: false,
+        };
+    }
+    async dispatch(options) {
+        const hostName = options.providerOptions?.host;
+        if (!hostName) {
+            throw new MissingTargetError('host', 'No host given. Pass --host <name> (a registered host, a device, a capability tag, or user@host).', 'List your machines: agents hosts list  ·  register more: agents devices sync / agents hosts add');
+        }
+        if (resolveDispatchRepos(options).length > 0) {
+            throw new Error('--repo has no meaning for --provider host — the run executes in a directory on the machine, not a cloned repo. ' +
+                'Pass the working directory via providerOptions.remoteCwd (CLI: --remote-cwd) instead.');
+        }
+        if (options.branch) {
+            throw new Error('--branch has no meaning for --provider host (no clone step). Check out the branch on the host, or use --remote-cwd.');
+        }
+        // DeviceOffloadUnsupportedError / HostResolutionError propagate — both carry
+        // actionable messages the CLI prints verbatim.
+        const host = await resolveHostRunTarget(hostName, {
+            any: options.providerOptions?.any === true,
+        });
+        const { task } = await dispatchPromptToHost(host, {
+            agent: options.agent ?? 'claude',
+            prompt: options.prompt,
+            mode: options.providerOptions?.mode,
+            model: options.model,
+            timeout: options.timeout,
+            remoteCwd: options.providerOptions?.remoteCwd,
+            name: options.providerOptions?.name,
+            follow: false, // the cloud pipeline streams via stream(); never block dispatch
+        });
+        return hostTaskToCloudTask(task);
+    }
+    async status(taskId) {
+        const task = loadTask(taskId);
+        if (!task)
+            throw new Error(`Unknown host task: ${taskId}`);
+        return hostTaskToCloudTask(this.reconcileMemoized(task));
+    }
+    async list(filter) {
+        const tasks = listTasks().map((t) => hostTaskToCloudTask(this.reconcileMemoized(t)));
+        return filter?.status ? tasks.filter((t) => t.status === filter.status) : tasks;
+    }
+    /**
+     * `reconcileTask` with the per-process reachability memo folded in: probe a
+     * target at most once per process; a down host leaves its tasks `running`.
+     */
+    reconcileMemoized(task) {
+        if (task.status !== 'running')
+            return task;
+        if (!this.reachable.has(task.target)) {
+            this.reachable.set(task.target, sshReachable(task.target, 6000));
+        }
+        if (!this.reachable.get(task.target))
+            return task;
+        const st = readRemoteExit(task.target, task.remoteExit);
+        if (st.state !== 'done')
+            return task;
+        return updateTask(task.id, terminalPatch(st.code)) ?? task;
+    }
+    /**
+     * Offset-tail the remote log (the same one-round-trip fetch the `run --host`
+     * follow uses) and yield it as `text` events until the `.exit` file lands.
+     */
+    async *stream(taskId) {
+        const task = loadTask(taskId);
+        if (!task)
+            throw new Error(`Unknown host task: ${taskId}`);
+        if (task.status !== 'running') {
+            yield { type: 'status', status: toCloudStatus(task.status) };
+            yield { type: 'done', status: toCloudStatus(task.status) };
+            return;
+        }
+        let offset = 0;
+        const fastPollMs = 1500;
+        const maxPollMs = 6000;
+        let pollMs = fastPollMs;
+        for (;;) {
+            const fetched = fetchProgress(task.target, {
+                remoteLog: task.remoteLog,
+                remoteExit: task.remoteExit,
+                taskId: task.id,
+                offset,
+            });
+            if (fetched) {
+                if (fetched.logChunk.length > 0) {
+                    offset += fetched.logChunk.length;
+                    pollMs = fastPollMs; // output is flowing — snap back to the fast poll
+                    yield { type: 'text', content: fetched.logChunk.toString('utf8') };
+                }
+                else {
+                    pollMs = Math.min(Math.round(pollMs * 1.5), maxPollMs); // idle backoff
+                }
+                const exit = fetched.exit.trim();
+                if (exit !== '') {
+                    const code = Number.parseInt(exit, 10);
+                    const finished = updateTask(task.id, terminalPatch(Number.isFinite(code) ? code : 0));
+                    const status = toCloudStatus(finished?.status ?? (code === 0 ? 'completed' : 'failed'));
+                    yield { type: 'done', status };
+                    return;
+                }
+            }
+            await new Promise((r) => setTimeout(r, pollMs));
+        }
+    }
+    async cancel(taskId) {
+        const task = loadTask(taskId);
+        if (!task)
+            throw new Error(`Unknown host task: ${taskId}`);
+        terminateDispatchedTask(task);
+    }
+    /**
+     * Follow-up message = resume the run's session on the same host. Only runs
+     * that captured a session id (Claude — the one agent that takes
+     * `--session-id`) can be resumed; others get an actionable refusal.
+     */
+    async message(taskId, content) {
+        const task = loadTask(taskId);
+        if (!task)
+            throw new Error(`Unknown host task: ${taskId}`);
+        if (!task.sessionId) {
+            throw new Error(`Host task ${taskId} has no session id to resume (only Claude runs capture one). ` +
+                `Start a follow-up run instead: agents run ${task.agent} "<prompt>" --host ${task.host}`);
+        }
+        const host = await resolveHostRunTarget(task.host);
+        await dispatchPromptToHost(host, {
+            agent: task.agent,
+            prompt: content,
+            resume: task.sessionId,
+            name: task.name,
+            follow: false,
+        });
+    }
+    /** The unified host pool (enrolled hosts ∪ devices), dispatchable ones only. */
+    async listTargets() {
+        const hosts = await listAllHosts();
+        return hosts
+            .filter((h) => h.dispatchable !== false)
+            .map((h) => ({
+            id: h.name,
+            label: [
+                h.provider === 'devices' ? 'device' : h.source,
+                h.os,
+                h.status && h.status !== 'unknown' ? h.status : undefined,
+                h.caps?.length ? `caps: ${h.caps.join(',')}` : undefined,
+            ]
+                .filter(Boolean)
+                .join(' · '),
+            kind: 'host',
+        }));
+    }
+}