@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/lib/actor.js

@@ -0,0 +1,166 @@
+/**
+ * Actor provenance -- who initiated a run.
+ *
+ * One shared account means every session, commit, and event otherwise shows up
+ * as the same person. `resolveActor()` answers "which human is behind this run"
+ * by looking at how the process was reached:
+ *
+ *   - Over SSH (the shared-fleet case): `tailscale whois` the SSH client IP to
+ *     the connecting tailnet identity -- a real name + login email.
+ *   - Locally (non-SSH): we can't honestly say who is at the box, so the id is
+ *     `UNRESOLVED@<host>` and no personal git identity is claimed.
+ *   - Inherited: a child spawn trusts the `AGENTS_ACTOR*` env its parent
+ *     stamped rather than re-resolving, so the whole spawn tree shares one actor.
+ *
+ * The resolved actor rides the child-process env (`actorEnv()`, merged into
+ * `buildExecEnv`). When the actor is a resolved human, that env also carries
+ * `GIT_AUTHOR_*` / `GIT_COMMITTER_*`, so the agent's own `git commit` is credited
+ * to the person instead of the shared account.
+ *
+ * The optional `actors:` map in agents.yaml enriches or overrides a resolved
+ * identity (pin a work email, add a github handle, mark an entry as an agent).
+ */
+import { spawnSync } from 'child_process';
+import { machineId } from './machine-id.js';
+import { parseSshConnection } from './session/provenance.js';
+import { readMeta } from './state.js';
+/** Hard cap on the whois shell-out — it runs on the spawn hot path. */
+const WHOIS_TIMEOUT_MS = 2000;
+/**
+ * Resolve the tailnet identity behind an IP via `tailscale whois`. Returns
+ * undefined when tailscale is absent, the peer is unknown, the call fails, or it
+ * exceeds WHOIS_TIMEOUT_MS -- every one of those falls back to an unresolved
+ * actor, never an error and never a hang (a wedged tailscaled is timed out, not
+ * waited on, since this sits in buildExecEnv on every agent spawn).
+ */
+function tailscaleWhois(ip) {
+    try {
+        const res = spawnSync('tailscale', ['whois', '--json', ip], {
+            encoding: 'utf-8',
+            windowsHide: true,
+            timeout: WHOIS_TIMEOUT_MS,
+        });
+        // A timeout leaves status null (child killed by SIGTERM) -- the status guard
+        // below treats it as an unresolved actor, same as any other failure.
+        if (res.status !== 0 || !res.stdout)
+            return undefined;
+        const data = JSON.parse(res.stdout);
+        const up = data.UserProfile;
+        if (!up)
+            return undefined;
+        return { login: up.LoginName, displayName: up.DisplayName };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the actors map from config, tolerant of a missing/unreadable config. */
+function readActors() {
+    try {
+        return readMeta().actors ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Find the actors-map entry for a resolved tailnet login. Matches on an entry's
+ * explicit `login`, its map key, or its `email` (all case-insensitive).
+ */
+function findActorConfig(login, actors) {
+    const needle = login.toLowerCase();
+    for (const [key, cfg] of Object.entries(actors)) {
+        const candidates = [cfg.login, key, cfg.email].filter((v) => !!v);
+        if (candidates.some((c) => c.toLowerCase() === needle))
+            return cfg;
+    }
+    return undefined;
+}
+/**
+ * Map a resolved tailnet identity (+ the actors map) to a ResolvedActor. Pure --
+ * the impure whois/config reads happen in computeActor -- so the enrich/override
+ * path is fully testable. No login (local, or an unnameable peer) yields the
+ * honest `UNRESOLVED@<host>`; a login without a config entry still credits git
+ * from the tailnet DisplayName + login email.
+ */
+export function actorFromIdentity(who, host, actors) {
+    const login = who?.login;
+    if (!login) {
+        return { id: `UNRESOLVED@${host}`, kind: 'human' };
+    }
+    const cfg = findActorConfig(login, actors);
+    const emailFromLogin = login.includes('@') ? login : undefined;
+    return {
+        id: login,
+        kind: cfg?.kind ?? 'human',
+        name: cfg?.name ?? who?.displayName,
+        email: cfg?.email ?? emailFromLogin,
+        github: cfg?.github,
+    };
+}
+/** Reconstruct an actor an ancestor process already resolved into the env. */
+function inheritedActor(env) {
+    const id = env.AGENTS_ACTOR;
+    if (!id)
+        return undefined;
+    return {
+        id,
+        kind: env.AGENTS_ACTOR_KIND === 'agent' ? 'agent' : 'human',
+        name: env.AGENTS_ACTOR_NAME || undefined,
+        email: env.AGENTS_ACTOR_EMAIL || undefined,
+        github: env.AGENTS_ACTOR_GITHUB || undefined,
+    };
+}
+/**
+ * Compute the actor for a given environment. Pure with respect to `env` (the
+ * only impurity is the `tailscale whois` / config read on the fresh-SSH path),
+ * so tests can drive every branch by passing an env explicitly.
+ */
+export function computeActor(env = process.env) {
+    const inherited = inheritedActor(env);
+    if (inherited)
+        return inherited;
+    const ssh = env.SSH_CONNECTION ? parseSshConnection(env.SSH_CONNECTION) : undefined;
+    const who = ssh?.clientIp ? tailscaleWhois(ssh.clientIp) : undefined;
+    return actorFromIdentity(who, machineId(), readActors());
+}
+let cached;
+/**
+ * Resolve the actor for the current process, cached for the process lifetime
+ * (the SSH `whois` shell-out runs at most once).
+ */
+export function resolveActor() {
+    if (!cached)
+        cached = computeActor(process.env);
+    return cached;
+}
+/** Clear the per-process cache. For tests, and for env changes within a run. */
+export function resetActorCache() {
+    cached = undefined;
+}
+/**
+ * The env an actor propagates to child processes. Always carries the actor id +
+ * kind (so children inherit and don't re-resolve). For a resolved human with a
+ * real name and email, it also carries `GIT_AUTHOR_*` / `GIT_COMMITTER_*` so the
+ * agent's own commits are credited to the person, not the shared account. An
+ * unresolved actor sets no git identity -- git keeps its ambient config.
+ */
+export function actorEnv(actor) {
+    const env = {
+        AGENTS_ACTOR: actor.id,
+        AGENTS_ACTOR_KIND: actor.kind,
+    };
+    if (actor.name)
+        env.AGENTS_ACTOR_NAME = actor.name;
+    if (actor.email)
+        env.AGENTS_ACTOR_EMAIL = actor.email;
+    if (actor.github)
+        env.AGENTS_ACTOR_GITHUB = actor.github;
+    if (actor.kind === 'human' && actor.name && actor.email) {
+        env.GIT_AUTHOR_NAME = actor.name;
+        env.GIT_AUTHOR_EMAIL = actor.email;
+        env.GIT_COMMITTER_NAME = actor.name;
+        env.GIT_COMMITTER_EMAIL = actor.email;
+    }
+    return env;
+}

package/dist/lib/agent-spec/provider.js

@@ -1,9 +1,10 @@
 // The production VersionProvider: the only fs/meta-coupled file in the engine.
 // Everything else in this module is pure and testable without it.
-import { listInstalledVersions, getGlobalDefault, getProjectVersion, isVersionInstalled, } from '../versions.js';
+import { listInstalledVersions, getGlobalDefault, getIsolatedDefault, getProjectVersion, isVersionInstalled, } from '../versions.js';
 export const defaultVersionProvider = {
     listInstalled: (agent) => listInstalledVersions(agent),
     getProjectVersion: (agent, cwd) => getProjectVersion(agent, cwd),
     getGlobalDefault: (agent) => getGlobalDefault(agent),
+    getIsolatedDefault: (agent) => getIsolatedDefault(agent),
     isInstalled: (agent, version) => isVersionInstalled(agent, version),
 };

package/dist/lib/agent-spec/resolve.js

@@ -66,6 +66,15 @@ export function resolveAgentTargets(spec, provider, opts = {}) {
                 push(agent, glob, 'global-default');
                 continue;
             }
+            // An isolated-only agent never has a global default — that is the point — so
+            // without this step `--agents codex` threw "No default version set" at a user
+            // who had explicitly run `agents use codex@<v>`. resolveVersion already had
+            // this fallback; the two resolvers had drifted apart.
+            const iso = provider.getIsolatedDefault(agent);
+            if (iso) {
+                push(agent, iso, 'isolated-default');
+                continue;
+            }
             const installed = provider.listInstalled(agent);
             if (installed.length === 0) {
                 push(agent, null, 'none');
@@ -81,13 +90,17 @@ export function resolveAgentTargets(spec, provider, opts = {}) {
             }
             throw new AgentSpecError(`No default version set for ${name}. Specify one (${agent}@<version>) or set it: agents use ${agent}@<version>.`, 'no-default', agent, installed);
         }
-        // ----- @pinned / @default: the configured global default -----
+        // ----- @pinned / @default: the configured default (global, else isolated) -----
         if (qualifier === 'pinned' || qualifier === 'default') {
-            const def = provider.getGlobalDefault(agent);
+            const glob = provider.getGlobalDefault(agent);
+            // Report which kind it was: an isolated default owns none of the launcher /
+            // shim / config-symlink machinery a global default does, and callers that log
+            // the source shouldn't claim otherwise.
+            const def = glob ?? provider.getIsolatedDefault(agent);
             if (!def) {
                 throw new AgentSpecError(`No default version set for ${name}. Run: agents use ${agent}@<version>`, 'no-default', agent, provider.listInstalled(agent));
             }
-            push(agent, def, 'global-default(@pinned)');
+            push(agent, def, glob ? 'global-default(@pinned)' : 'isolated-default');
             continue;
         }
         // ----- @all: every installed version -----
@@ -168,7 +181,8 @@ export function resolveListFilter(agent, qualifier, provider, opts = {}) {
     const q = qualifier?.trim();
     if (!q || q === 'any')
         return undefined;
-    if (q === 'default' || q === 'pinned')
-        return provider.getGlobalDefault(agent) ?? undefined;
+    if (q === 'default' || q === 'pinned') {
+        return provider.getGlobalDefault(agent) ?? provider.getIsolatedDefault(agent) ?? undefined;
+    }
     return resolveSingleAgentTarget(`${agent}@${q}`, provider, { ...opts, availableAgents: [agent] }).version;
 }

package/dist/lib/agent-spec/types.d.ts

@@ -1,6 +1,6 @@
 import type { AgentId } from '../types.js';
 /** How a resolved version was arrived at — for provenance, display, and error rendering. */
-export type VersionSource = 'explicit' | 'project-pin' | 'global-default' | 'global-default(@pinned)' | 'sole-installed' | 'newest-installed' | 'alias-latest' | 'alias-oldest' | 'none';
+export type VersionSource = 'explicit' | 'project-pin' | 'global-default' | 'isolated-default' | 'global-default(@pinned)' | 'sole-installed' | 'newest-installed' | 'alias-latest' | 'alias-oldest' | 'none';
 export interface AgentTarget {
     agent: AgentId;
     /** Resolved exact version, or null when the agent has no installed versions yet. */
@@ -32,6 +32,14 @@ export interface VersionProvider {
     getProjectVersion(agent: AgentId, cwd: string): string | null;
     /** The configured global default version, or null. */
     getGlobalDefault(agent: AgentId): string | null;
+    /**
+     * The preferred isolated copy. Kept separate from getGlobalDefault on purpose: a
+     * global default owns the launcher, the bare shim and the real ~/.<agent> config
+     * symlink, and an isolated version must never acquire any of those. Folding the
+     * two together here would hand an isolated version back to every caller that
+     * reasonably assumes a global default means "the one that owns the launcher".
+     */
+    getIsolatedDefault(agent: AgentId): string | null;
     /** Whether an exact version is installed. */
     isInstalled(agent: AgentId, version: string): boolean;
 }

package/dist/lib/agents.d.ts

@@ -265,6 +265,27 @@ export declare function __resetAntigravityKeychainCacheForTest(): void;
  * Sync, no Keychain, no network — safe on the `agents run` hot path.
  */
 export declare function isClaudeCredentialFileBlank(base: string, platform?: NodeJS.Platform): boolean;
+/**
+ * Whether a Claude version home holds its OWN on-disk credential — a non-blank
+ * `.claude/.credentials.json` (the store Claude Code writes on login off macOS)
+ * or a `.claude/.oauth_token` file (the keychain-less shim fallback, shims.ts).
+ *
+ * RUSH-1979: the routines daemon injects one ambient `CLAUDE_CODE_OAUTH_TOKEN`
+ * (RUSH-1759) so a token-less default account still authenticates. But Claude —
+ * and the Linux shim's own `-z CLAUDE_CODE_OAUTH_TOKEN` guard — both prefer that
+ * env var over a pinned account's config dir, so when balanced rotation pins a
+ * specific account's `CLAUDE_CONFIG_DIR` the ambient token shadows it: the pool
+ * is inert and every fire 401s on the one stale token. A routine spawn drops the
+ * ambient token when the pinned account has its own credential (this returns
+ * true) so the account authenticates itself; when it does not (the RUSH-1759
+ * default), the injected token is kept.
+ *
+ * Off-darwin only, mirroring {@link isClaudeCredentialFileBlank}: on macOS the
+ * login Keychain is the canonical store and probing it raises an auth sheet, and
+ * there the daemon injects no token to shadow (broker-only, usually absent), so
+ * returning false changes nothing. Sync, no Keychain, no network.
+ */
+export declare function claudeHomeHasOwnCredential(base: string, platform?: NodeJS.Platform): boolean;
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
 /**
  * Determine when the agent was last used by checking session file mtimes,

package/dist/lib/agents.js

@@ -320,8 +320,8 @@ export const AGENTS = {
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
-        supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: { since: '1.1.1' }, skills: true, commands: true, plugins: true, subagents: true, rules: { file: 'AGENTS.md' }, workflows: false, memory: false, modes: ['plan', 'edit'] },
+        supportsHooks: true,
+        capabilities: { hooks: { since: '0.3.130' }, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: { since: '1.1.1' }, skills: true, commands: true, plugins: true, subagents: true, rules: { file: 'AGENTS.md' }, workflows: false, memory: false, modes: ['plan', 'edit'] },
     },
     openclaw: {
         id: 'openclaw',
@@ -479,6 +479,8 @@ export const AGENTS = {
     // ~/.grok/hooks/ (+ project .grok/hooks/) — events PreToolUse, PostToolUse, etc.
     // Plugins live in ~/.grok/plugins/ with marketplaces. Permissions: --allow/--deny
     // CLI flags or [permission] TOML block in ~/.grok/config.toml.
+    // Workflows (native Rhai orchestration) enabled by default as of v0.2.111 —
+    // projected into ~/.grok/workflows/<name>.rhai (under GROK_HOME isolation).
     grok: {
         id: 'grok',
         name: 'Grok',
@@ -487,8 +489,12 @@ export const AGENTS = {
         npmPackage: '',
         installScript: 'curl -fsSL https://x.ai/cli/install.sh | bash',
         configDir: path.join(HOME, '.grok'),
-        commandsDir: '', // Grok primarily uses skills + slash commands from skills
-        commandsSubdir: '',
+        // Grok discovers file-based slash commands from ~/.agents/commands/ (the
+        // cross-agent compat dir it mirrors from Claude Code) as well as the legacy
+        // ~/.claude/commands/ symlink. We write there directly so the per-agent
+        // install path and the central user repo stay in sync.
+        commandsDir: path.join(HOME, '.agents', 'commands'),
+        commandsSubdir: path.join('..', '.agents', 'commands'),
         skillsDir: path.join(HOME, '.grok', 'skills'),
         hooksDir: path.join(HOME, '.grok', 'hooks'),
         instructionsFile: 'AGENTS.md',
@@ -502,11 +508,13 @@ export const AGENTS = {
             mcpHeaders: false,
             allowlist: true, // maps to Grok's granular Bash/Edit/Write/Read/Grep/WebFetch/MCPTool rules
             skills: true,
-            commands: false, // covered by skills
+            commands: true, // Grok >= 0.2.111: file-based slash commands from ~/.agents/commands/ (docs) + ~/.claude/commands/ (Claude Code compat)
             plugins: true,
             subagents: true, // ~/.grok/agents/*.md (Claude-compatible agent defs)
             rules: { file: 'AGENTS.md' },
-            workflows: false,
+            // Native workflows (`.rhai` under ~/.grok/workflows/) shipped on-by-default
+            // in v0.2.111 (2026-07-22). See transformWorkflowForGrok in workflows.ts.
+            workflows: { since: '0.2.111' },
             memory: true,
             modes: ['plan', 'edit', 'skip'],
             // grok's `--permission-mode plan` silently stalls a headless `-p` run at
@@ -583,6 +591,24 @@ export const AGENTS = {
     // `.factory-plugin/` (it also reads `.claude-plugin/` for compatibility) — set
     // pluginManifestDir so syncPluginToVersion mirrors the manifest into it, the
     // same pattern codex uses with `.codex-plugin`.
+    //
+    // Workflows / Factory Missions (RUSH-1864, probed droid v0.177.0; ticket cited
+    // v0.161.0 — self-updating, no pinnable semver): Factory ships genuine multi-
+    // step orchestration ("Missions") via `/missions` (interactive) and
+    // `droid exec --mission` (headless; optional `-f <prompt.md>` is a *prompt*
+    // file, not a named mission template). Docs:
+    // https://docs.factory.ai/cli/features/missions and
+    // https://docs.factory.ai/docs/droid-exec/overview (Mission Mode).
+    //
+    // Mission state may land under `~/.factory/missions/<sessionId>/` at runtime
+    // (`getMissionsDir` = join(home, ".factory", "missions") + per-session
+    // mission.md / features.json / progress_log.jsonl) — that is **session
+    // runtime state**, not a discovery directory of installable named workflows.
+    // There is no discoverMission / template registry, and a cold install has no
+    // `~/.factory/missions/` until a mission is run. agents-cli's workflows
+    // capability means "sync WORKFLOW.md into an auto-discovered dir" — Droid
+    // has no such dir, so workflows stays false (invoke-only; do not fabricate a
+    // writer target).
     droid: {
         id: 'droid',
         name: 'Droid',
@@ -615,6 +641,7 @@ export const AGENTS = {
             plugins: true,
             subagents: true,
             rules: { file: 'AGENTS.md' },
+            // Factory Missions are invoke-only — no installable discovery dir (RUSH-1864).
             workflows: false,
             memory: false,
             modes: ['plan', 'edit', 'auto', 'skip'],
@@ -1377,6 +1404,43 @@ export function isClaudeCredentialFileBlank(base, platform = process.platform) {
         return false;
     }
 }
+/**
+ * Whether a Claude version home holds its OWN on-disk credential — a non-blank
+ * `.claude/.credentials.json` (the store Claude Code writes on login off macOS)
+ * or a `.claude/.oauth_token` file (the keychain-less shim fallback, shims.ts).
+ *
+ * RUSH-1979: the routines daemon injects one ambient `CLAUDE_CODE_OAUTH_TOKEN`
+ * (RUSH-1759) so a token-less default account still authenticates. But Claude —
+ * and the Linux shim's own `-z CLAUDE_CODE_OAUTH_TOKEN` guard — both prefer that
+ * env var over a pinned account's config dir, so when balanced rotation pins a
+ * specific account's `CLAUDE_CONFIG_DIR` the ambient token shadows it: the pool
+ * is inert and every fire 401s on the one stale token. A routine spawn drops the
+ * ambient token when the pinned account has its own credential (this returns
+ * true) so the account authenticates itself; when it does not (the RUSH-1759
+ * default), the injected token is kept.
+ *
+ * Off-darwin only, mirroring {@link isClaudeCredentialFileBlank}: on macOS the
+ * login Keychain is the canonical store and probing it raises an auth sheet, and
+ * there the daemon injects no token to shadow (broker-only, usually absent), so
+ * returning false changes nothing. Sync, no Keychain, no network.
+ */
+export function claudeHomeHasOwnCredential(base, platform = process.platform) {
+    if (platform === 'darwin')
+        return false;
+    if (fs.existsSync(path.join(base, '.claude', '.oauth_token')))
+        return true;
+    try {
+        const raw = fs.readFileSync(path.join(base, '.claude', '.credentials.json'), 'utf-8');
+        const oauth = JSON.parse(raw).claudeAiOauth;
+        if (!oauth)
+            return false;
+        const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0;
+        return nonEmpty(oauth.accessToken) || nonEmpty(oauth.refreshToken);
+    }
+    catch {
+        return false;
+    }
+}
 export async function getAccountInfo(agentId, home) {
     const base = home || os.homedir();
     const empty = {

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

@@ -24,3 +24,5 @@ export declare class CodexCloudProvider implements CloudProvider {
     cancel(_taskId: string): Promise<void>;
     message(_taskId: string, _content: string): Promise<void>;
 }
+/** Extract a task ID from codex CLI output (JSON field, key:value line, or UUID pattern). */
+export declare function extractTaskId(output: string): string | undefined;

package/dist/lib/cloud/codex.js

@@ -127,8 +127,19 @@ export class CodexCloudProvider {
         if (code !== 0) {
             throw new Error(`codex cloud exec failed: ${stderr || stdout}`);
         }
-        // Parse task ID from output. Codex typically prints the task ID.
-        const taskId = extractTaskId(stdout) ?? `codex-${Date.now()}`;
+        // The task id is the ONLY handle to the just-created execution — status,
+        // list, and the session-index reconcile all key on it. Codex prints it to
+        // stdout (JSON or a task_/id: line); some builds route it to stderr, so scan
+        // both. A synthetic `codex-<ts>` id was the old fallback here — it can never
+        // match the real execution, so it silently broke every follow-up. If the id
+        // genuinely can't be parsed, fail loudly and point at `agents cloud list`
+        // (which recovers the newest execution) rather than persist a bogus id.
+        const taskId = extractTaskId(stdout) ?? extractTaskId(stderr);
+        if (!taskId) {
+            throw new Error('codex cloud exec did not report a task id — the run may have dispatched, but ' +
+                'without the id it cannot be tracked. Find it with `agents cloud list --provider codex`, ' +
+                `then \`agents cloud status <id>\`.\nRaw output: ${(stdout || stderr).trim().slice(0, 400)}`);
+        }
         const now = new Date().toISOString();
         return {
             id: taskId,
@@ -232,7 +243,7 @@ export class CodexCloudProvider {
     }
 }
 /** Extract a task ID from codex CLI output (JSON field, key:value line, or UUID pattern). */
-function extractTaskId(output) {
+export function extractTaskId(output) {
     // Try JSON first
     try {
         const data = JSON.parse(output);

package/dist/lib/cloud/session-index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Register cloud-dispatched tasks into the LOCAL session index, keyed by the
+ * real execution id, so a launch is mappable to a session immediately.
+ *
+ * The cloud store (`tasks.db`) and the session index (`sessions` table) were two
+ * disjoint stores: a `agents cloud run` wrote only the store, and the session
+ * index learned about the run only later, via `discoverCloudSessions` hitting the
+ * proxy. Until that discovery ran there was no launch→session mapping at all —
+ * the run was orphaned in `agents sessions` exactly like the non-Claude host runs.
+ *
+ * This mirrors hosts/session-index.ts: the transcript is remote (fetched on
+ * demand by session/cloud.ts), so the row is registered with an EMPTY `file_path`
+ * — the sentinel db.js's stale-row filter treats as "always live" — and a
+ * `[cloud/<status>]` label. The row is written at dispatch and refreshed on every
+ * status poll so the label tracks the task's lifecycle. Non-session-agent cloud
+ * providers (a task whose agent has no transcript format) are skipped: there is
+ * nothing to resolve or resume by id.
+ */
+import type { CloudTask } from './types.js';
+/** Context a cloud task needs to become a session row — the LOCAL dir it was launched from. */
+export interface CloudSessionContext {
+    /** Local directory `agents cloud run` was invoked from. Defaults to process.cwd(). */
+    cwd?: string;
+}
+/**
+ * Register (or refresh) a cloud task in the local session index. No-op when the
+ * task's agent isn't a known session agent, or its id isn't a usable execution id
+ * (never a fabricated `codex-<ts>` — codex.ts fails loud instead of minting one,
+ * but guard here too so a bad id can never seed a bogus row). Best-effort: a
+ * failed index write must never break the dispatch/poll it rides on.
+ */
+export declare function registerCloudSession(task: CloudTask, ctx?: CloudSessionContext): void;

package/dist/lib/cloud/session-index.js

@@ -0,0 +1,58 @@
+/**
+ * Register cloud-dispatched tasks into the LOCAL session index, keyed by the
+ * real execution id, so a launch is mappable to a session immediately.
+ *
+ * The cloud store (`tasks.db`) and the session index (`sessions` table) were two
+ * disjoint stores: a `agents cloud run` wrote only the store, and the session
+ * index learned about the run only later, via `discoverCloudSessions` hitting the
+ * proxy. Until that discovery ran there was no launch→session mapping at all —
+ * the run was orphaned in `agents sessions` exactly like the non-Claude host runs.
+ *
+ * This mirrors hosts/session-index.ts: the transcript is remote (fetched on
+ * demand by session/cloud.ts), so the row is registered with an EMPTY `file_path`
+ * — the sentinel db.js's stale-row filter treats as "always live" — and a
+ * `[cloud/<status>]` label. The row is written at dispatch and refreshed on every
+ * status poll so the label tracks the task's lifecycle. Non-session-agent cloud
+ * providers (a task whose agent has no transcript format) are skipped: there is
+ * nothing to resolve or resume by id.
+ */
+import { upsertSession } from '../session/db.js';
+import { isSessionTrackedAgent } from '../session/types.js';
+import { deriveShortId } from '../session/short-id.js';
+/** The execution-id charset the session index will accept as a row id. */
+const EXECUTION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/;
+/**
+ * Register (or refresh) a cloud task in the local session index. No-op when the
+ * task's agent isn't a known session agent, or its id isn't a usable execution id
+ * (never a fabricated `codex-<ts>` — codex.ts fails loud instead of minting one,
+ * but guard here too so a bad id can never seed a bogus row). Best-effort: a
+ * failed index write must never break the dispatch/poll it rides on.
+ */
+export function registerCloudSession(task, ctx = {}) {
+    if (!task.agent || !isSessionTrackedAgent(task.agent))
+        return;
+    if (!task.id || !EXECUTION_ID_RE.test(task.id))
+        return;
+    try {
+        upsertSession({
+            id: task.id,
+            shortId: deriveShortId(task.id),
+            agent: task.agent,
+            timestamp: task.createdAt,
+            lastActivity: task.updatedAt,
+            cwd: ctx.cwd ?? process.cwd(),
+            project: task.repo ?? task.repos?.[0],
+            // Remote transcript — no local file yet. Empty file_path is the sentinel
+            // the DB stale-filter treats as "always live" (see hosts/session-index.ts).
+            filePath: '',
+            topic: task.prompt.split('\n')[0]?.slice(0, 120) || undefined,
+            // Mirrors session/cloud.ts's discovered label, so the dispatch-time row and
+            // a later proxy-discovered row read the same in `agents sessions`.
+            label: `[cloud/${task.status}]${task.branch ? ` ${task.branch}` : ''}`,
+            prUrl: task.prUrl,
+        }, '');
+    }
+    catch {
+        /* index write is best-effort; the task is already persisted in the cloud store */
+    }
+}

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

@@ -6,6 +6,13 @@
  * remote provider each time.
  */
 import type { CloudTask, CloudProviderId, CloudTaskStatus } from './types.js';
+/**
+ * Release the tasks.db connection so the file (and its WAL sidecars) can be
+ * removed. The mirror of `closeDB()` in `../session/db.ts`, which this module
+ * had no counterpart for — on Windows an open handle makes the file
+ * un-unlinkable, so anything tearing down a temp home must close this too.
+ */
+export declare function closeStore(): void;
 /** Persist a task snapshot, replacing any existing row with the same ID. */
 export declare function insertTask(task: CloudTask): void;
 /** Update a task's status and optionally patch summary, PR URL, or branch. */

package/dist/lib/cloud/store.js

@@ -9,6 +9,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import Database from '../sqlite.js';
 import { getCloudDir } from '../state.js';
+import { registerCloudSession } from './session-index.js';
 const CLOUD_DIR = getCloudDir();
 const DB_PATH = path.join(CLOUD_DIR, 'tasks.db');
 const SCHEMA = `
@@ -41,12 +42,29 @@ function db() {
     _db.exec(SCHEMA);
     return _db;
 }
+/**
+ * Release the tasks.db connection so the file (and its WAL sidecars) can be
+ * removed. The mirror of `closeDB()` in `../session/db.ts`, which this module
+ * had no counterpart for — on Windows an open handle makes the file
+ * un-unlinkable, so anything tearing down a temp home must close this too.
+ */
+export function closeStore() {
+    if (_db) {
+        _db.close();
+        _db = null;
+    }
+}
 /** Persist a task snapshot, replacing any existing row with the same ID. */
 export function insertTask(task) {
     db().prepare(`
     INSERT OR REPLACE INTO tasks (id, provider, status, agent, prompt, repo, branch, pr_url, summary, created_at, updated_at)
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(task.id, task.provider, task.status, task.agent ?? null, task.prompt, task.repo ?? null, task.branch ?? null, task.prUrl ?? null, task.summary ?? null, task.createdAt, task.updatedAt);
+    // Every cloud dispatch flows through here, so this is the one chokepoint that
+    // reconciles the cloud store with the session index: register a session row
+    // keyed by the real execution id so the launch is mappable to a session
+    // immediately, not only after a later proxy discovery (see session-index.ts).
+    registerCloudSession(task);
 }
 /** Update a task's status and optionally patch summary, PR URL, or branch. */
 export function updateTaskStatus(id, status, extra) {
@@ -67,6 +85,13 @@ export function updateTaskStatus(id, status, extra) {
     }
     params.push(id);
     db().prepare(`UPDATE tasks SET ${sets.join(', ')} WHERE id = ?`).run(...params);
+    // Keep the session index in lockstep with the store on every poll: refresh the
+    // row so its `[cloud/<status>]` label tracks the task's lifecycle (and picks up
+    // a newly-opened PR url). Reads the just-written row so the label reflects the
+    // update we just made, not a stale snapshot.
+    const updated = getTaskById(id);
+    if (updated)
+        registerCloudSession(updated);
 }
 /** Fetch a single task by its provider-assigned ID, or null if not found locally. */
 export function getTaskById(id) {

package/dist/lib/config-transfer.js

@@ -38,6 +38,10 @@ export function copyDirStrippingAgentsSymlinks(source, dest, agentsDir) {
     const inside = agentsDir + path.sep;
     fs.cpSync(source, dest, {
         recursive: true,
+        // `force: true` is Node's default, but Bun drops it when a `filter` is supplied —
+        // existing files are then silently left alone. `dist/bin/agents` is bun-compiled,
+        // so this is a production path, not just a test artifact. State it explicitly.
+        force: true,
         filter: (src) => {
             try {
                 const st = fs.lstatSync(src);

package/dist/lib/daemon.d.ts

@@ -81,6 +81,15 @@ export declare function runDaemon(): Promise<void>;
 export declare function readDaemonClaudeOAuthToken(opts?: {
     allowPrompt?: boolean;
 }): string | null;
+/**
+ * Read the FULL `claude` bundle env — the main `CLAUDE_CODE_OAUTH_TOKEN` plus any
+ * per-account `CLAUDE_CODE_OAUTH_TOKEN_<slug>` setup-tokens. Same resolution and
+ * never-throws contract as {@link readDaemonClaudeOAuthToken}; returns `{}` when
+ * the bundle can't be read (broker-only headless miss, absent bundle, etc.).
+ */
+export declare function readDaemonClaudeBundleEnv(opts?: {
+    allowPrompt?: boolean;
+}): Record<string, string>;
 /**
  * Write a launchd plist or systemd unit with owner-only permissions atomically.
  *
@@ -139,7 +148,7 @@ export declare function ensureDaemonStarted(): {
  * the daemon then passes it to every routine run it spawns. An already-set
  * value (e.g. inherited from launchd) is left untouched.
  */
-export declare function buildDetachedDaemonEnv(baseEnv?: NodeJS.ProcessEnv, oauthToken?: string | null): NodeJS.ProcessEnv;
+export declare function buildDetachedDaemonEnv(baseEnv?: NodeJS.ProcessEnv, bundleEnv?: Record<string, string>): NodeJS.ProcessEnv;
 /**
  * Resolve how to launch the daemon: `node <entry> __daemon-run`, matching the
  * exact form that works under a direct `__daemon-run`.