@phnx-labs/agents-cli 1.22.117 → 1.22.119

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

@@ -89,9 +89,9 @@ export declare const ALL_AGENT_IDS: AgentId[];
  * import (runner.ts already imports from routines.ts).
  *
  * This is a curated subset of AGENT_COMMANDS, not "every harness that can run
- * headlessly". Expanding it is a product change (gemini is hard-deprecated and
- * is deliberately absent). Argv itself is baked from AGENT_COMMANDS in
- * daemon/runner.ts bakeRoutineArgv — do not reintroduce a second token table.
+ * headlessly". Expanding it is a product change. Argv itself is baked from
+ * AGENT_COMMANDS in daemon/runner.ts bakeRoutineArgv — do not reintroduce a
+ * second token table.
  */
 export declare const ROUTINE_AGENT_IDS: readonly string[];
 /** Agents that can receive managed installs, imports, and resource sync writes. */
@@ -222,7 +222,7 @@ export declare function formatClaudeOrgLabel(orgType: string | null | undefined)
  */
 export declare function accountOrgBadge(info?: Pick<AccountInfo, 'organizationType' | 'organizationName'> | null): string | null;
 /** Agents whose local credential formats expose enough state for account selection. */
-export declare const ACCOUNT_INSPECTION_AGENT_IDS: readonly ["claude", "codex", "gemini", "cursor", "grok", "antigravity", "kimi", "droid", "opencode", "muse"];
+export declare const ACCOUNT_INSPECTION_AGENT_IDS: readonly ["claude", "codex", "cursor", "grok", "antigravity", "kimi", "droid", "opencode", "muse"];
 /** Whether agents-cli can determine this agent's per-version sign-in state. */
 export declare function supportsAccountInspection(agentId: AgentId): boolean;
 /**
@@ -573,9 +573,8 @@ export declare function stripJsonComments(content: string): string;
  *
  * All three MCP path resolvers read `MCP_TARGETS`, so the file the writer
  * targets, the file the parser reads, and the file the staleness detector
- * watches cannot drift apart. An agent with no MCP target (the hard-deprecated
- * `gemini`) keeps the historical settings.json default so old configs still
- * parse.
+ * watches cannot drift apart. An agent with no MCP target keeps the historical
+ * settings.json default so old configs still parse.
  */
 export declare function getUserMcpConfigPath(agentId: AgentId): string;
 /**

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

@@ -268,6 +268,8 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
+        nativePluginSkills: true,
+        ownedSkillDirs: ['synced'],
         // Claude Code grew a native `claude --cloud "<prompt>"` (Anthropic-managed
         // infra, claude.ai/code; requires claude.ai subscription auth). Routing
         // still goes to Rush Cloud deliberately — it keeps cloud tasks in one
@@ -305,46 +307,6 @@ export const AGENTS = {
         // ~/.codex/agents/*.toml (name, description, developer_instructions).
         capabilities: { hooks: { since: '0.116.0' }, mcp: true, mcpHttp: true, mcpHeaders: false, allowlist: { since: '0.138.0' }, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, subagents: { since: '0.117.0' }, rules: { file: 'AGENTS.md' }, workflows: false, memory: true, modes: ['plan', 'edit', 'auto', 'skip'], interactiveRepl: true },
     },
-    gemini: {
-        id: 'gemini',
-        name: 'Gemini',
-        sessionDir: ['.gemini', 'tmp'],
-        sessionFileExt: '.json',
-        versionStdoutMatch: 'semver',
-        unmanagedBinary: 'path',
-        mcpRegister: 'cli',
-        mcpAddHttp: 'transport',
-        mcpAddStdio: 'simple',
-        mcpConfigWrite: 'json-mcpServers',
-        color: 'blue',
-        cliCommand: 'gemini',
-        npmPackage: '@google/gemini-cli',
-        configDir: path.join(HOME, '.gemini'),
-        commandsDir: path.join(HOME, '.gemini', 'commands'),
-        commandsSubdir: 'commands',
-        skillsDir: path.join(HOME, '.gemini', 'skills'),
-        hooksDir: 'hooks',
-        instructionsFile: 'GEMINI.md',
-        format: 'toml',
-        variableSyntax: '{{args}}',
-        supportsHooks: true,
-        nativeAgentsSkillsDir: true,
-        // Google retired the Gemini CLI (announced at Google I/O 2026, May 19); the `gemini`
-        // command stopped serving free/Pro/Ultra requests on June 18, 2026. Antigravity CLI
-        // (`agy`) is the official successor. Hard deprecation keeps legacy Gemini
-        // sessions/config parseable while blocking install/import/sync.
-        deprecated: {
-            by: 'Google',
-            date: 'June 18, 2026',
-            reason: 'The Gemini CLI was retired for free, Pro, and Ultra tiers and no longer serves requests (announced at Google I/O 2026 on May 19).',
-            replacement: 'antigravity',
-            url: 'https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/',
-            hard: true,
-        },
-        // gemini hooks: shipped in v0.26.0 (Jan 2026); older binaries silently ignore the `hooks` key.
-        // extensions: gemini-extension.json bundles shipped in v0.8.0; custom subagents in v0.36.0.
-        capabilities: { hooks: { since: '0.26.0' }, mcp: true, mcpHttp: true, mcpHeaders: false, allowlist: true, skills: true, commands: true, plugins: { since: '0.8.0' }, subagents: { since: '0.36.0' }, rules: { file: 'GEMINI.md' }, workflows: false, memory: false, modes: ['plan', 'edit', 'skip'], rulesImports: true, interactiveRepl: false },
-    },
     cursor: {
         id: 'cursor',
         name: 'Cursor',
@@ -1019,16 +981,13 @@ export const ALL_AGENT_IDS = Object.keys(AGENTS);
  * import (runner.ts already imports from routines.ts).
  *
  * This is a curated subset of AGENT_COMMANDS, not "every harness that can run
- * headlessly". Expanding it is a product change (gemini is hard-deprecated and
- * is deliberately absent). Argv itself is baked from AGENT_COMMANDS in
- * daemon/runner.ts bakeRoutineArgv — do not reintroduce a second token table.
+ * headlessly". Expanding it is a product change. Argv itself is baked from
+ * AGENT_COMMANDS in daemon/runner.ts bakeRoutineArgv — do not reintroduce a
+ * second token table.
  */
 export const ROUTINE_AGENT_IDS = Object.freeze([
     'claude',
     'codex',
-    // gemini is hard-deprecated (Antigravity replaced it) — no routine target. A
-    // legacy gemini routine now fails validateJob loud instead of firing a
-    // retired backend; the id survives only for reading old sessions/config.
     'cursor',
     'kimi',
     'droid',
@@ -1338,7 +1297,6 @@ export function accountOrgBadge(info) {
 export const ACCOUNT_INSPECTION_AGENT_IDS = [
     'claude',
     'codex',
-    'gemini',
     'cursor',
     'grok',
     'antigravity',
@@ -1429,7 +1387,6 @@ function resolveAccountCredentialPath(base, ...segments) {
 const CREDENTIAL_FILE_SEGMENTS = {
     claude: [['.claude', '.claude.json'], ['.claude.json']],
     codex: [['.codex', 'auth.json']],
-    gemini: [['.gemini', 'google_accounts.json']],
     grok: [['.grok', 'auth.json']],
     kimi: [['.kimi-code', 'credentials', 'kimi-code.json']],
     droid: [['.factory', 'auth.v2.file']],
@@ -2028,7 +1985,6 @@ export async function getAccountInfo(agentId, home) {
     const configFiles = {
         claude: path.join(base, '.claude.json'),
         codex: path.join(base, '.codex', 'auth.json'),
-        gemini: path.join(base, '.gemini', 'google_accounts.json'),
         // OpenCode keeps every session in ONE sqlite file rather than a directory of
         // per-session transcripts, so the session-file walk resolveLastActive runs
         // for other agents finds nothing. Its mtime fallback is the right read here:
@@ -2151,11 +2107,6 @@ export async function getAccountInfo(agentId, home) {
                     signedIn: !!email,
                 };
             }
-            case 'gemini': {
-                const data = JSON.parse(await fs.promises.readFile(path.join(base, '.gemini', 'google_accounts.json'), 'utf-8'));
-                const email = data.active || null;
-                return { ...empty, email, signedIn: !!email, lastActive };
-            }
             case 'cursor': {
                 // Cursor CLI keeps account metadata in ~/.cursor/cli-config.json
                 // (authInfo: { email, userId, authId }) and its OAuth tokens SEPARATELY
@@ -2902,9 +2853,8 @@ function parseMcpFromOpenCodeConfig(configPath) {
  *
  * All three MCP path resolvers read `MCP_TARGETS`, so the file the writer
  * targets, the file the parser reads, and the file the staleness detector
- * watches cannot drift apart. An agent with no MCP target (the hard-deprecated
- * `gemini`) keeps the historical settings.json default so old configs still
- * parse.
+ * watches cannot drift apart. An agent with no MCP target keeps the historical
+ * settings.json default so old configs still parse.
  */
 export function getUserMcpConfigPath(agentId) {
     return getMcpConfigPathForHome(agentId, HOME);
@@ -3036,9 +2986,6 @@ const AGENT_NAME_ALIASES = {
     codex: 'codex',
     'openai-codex': 'codex',
     cx: 'codex',
-    gemini: 'gemini',
-    'gemini-cli': 'gemini',
-    gx: 'gemini',
     cursor: 'cursor',
     'cursor-agent': 'cursor',
     cr: 'cursor',

package/dist/lib/auth-health.d.ts

@@ -19,10 +19,21 @@ import { type ProviderProbe } from './accounting/usage.js';
  *                   endpoint cannot prove live for a known non-revocation
  *                   reason (Claude setup-token usage-scope gap — RUSH-2392),
  *                   OR a throttled probe with no fresh previous verdict (PHNX-4051).
+ * - `no_evidence` — a credential is present on disk but THIS box has no evidence,
+ *                   either way, that it can authenticate: no probe was possible
+ *                   (a worker's setup-token box does not probe the usage endpoint)
+ *                   and no run outcome has been recorded here yet. Distinct from
+ *                   `unverified` (which is "signed in, no probe endpoint exists for
+ *                   this harness") — `no_evidence` is "we did not look", the exact
+ *                   state PHNX-4116 stops rendering as a verdict word. A worker
+ *                   never PUBLISHES this row (it is dropped in
+ *                   {@link probeLocalFleetAuth}); it surfaces only as an in-memory
+ *                   account-catalog verdict whose display is a FACT (token presence
+ *                   + recorded run outcomes), never the word "no_evidence".
  * - `unconfigured`— no usable credential on disk.
  * - `error`       — network/other failure; verdict indeterminate (keep the last known one).
  */
-export type AuthVerdict = 'live' | 'revoked' | 'expired' | 'rate_limited' | 'unverified' | 'unconfigured' | 'error';
+export type AuthVerdict = 'live' | 'revoked' | 'expired' | 'rate_limited' | 'unverified' | 'no_evidence' | 'unconfigured' | 'error';
 export interface AuthHealth {
     verdict: AuthVerdict;
     /** epoch ms of the probe. */
@@ -33,6 +44,15 @@ export interface AuthHealth {
     account?: string;
     /** Stable registered account id. Display labels are never used as identity. */
     accountId?: string;
+    /**
+     * How this row was observed (PHNX-4116). `probe` (default when absent) is a
+     * network/usage-endpoint probe the daemon ran; `run` is a REAL agent run
+     * outcome recorded on exit — a successful inference (`live`) or an auth failure
+     * (`revoked`/`expired`/`rate_limited`). The auth FACT `agents view` renders
+     * (`last used ok 12m ago` vs `last auth failure 401 …`) reads this so a token's
+     * usability is stated as evidence, not inferred from a stale usage file.
+     */
+    source?: 'probe' | 'run';
 }
 /** Maximum age of an auth verdict used for automatic routing decisions. */
 export declare const AUTH_PROBE_MAX_AGE_MS: number;
@@ -284,4 +304,52 @@ export declare function probeLocalFleetAuth(opts?: {
  * merges as before.
  */
 export declare function writeFleetAuthRows(host: string, rows: AuthProbeRow[], installed?: ReadonlySet<string>): void;
+/**
+ * The installed-version label a run outcome falls back to when the account has no
+ * slot on this box: the explicit `version`, else the label derived from `home` (a
+ * version home is `<versionDir>/home`, so the label is its parent dir's basename).
+ * Null when neither resolves. Pure (no fs) so it is unit-tested directly.
+ */
+export declare function runOutcomeVersionKey(opts: {
+    version?: string | null;
+    home?: string | null;
+}): string | null;
+/** A real agent-run outcome — the evidence behind `last used ok` / `last auth failure`. */
+export type RunAuthOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    verdict: 'revoked' | 'expired' | 'rate_limited' | 'error';
+    detail?: string;
+    resetsAt?: number | null;
+};
+/**
+ * Record a REAL run's auth outcome into the auth-health cache with
+ * `source: 'run'`. Best-effort and never throws: an unattributable run (no
+ * accountId/version/home) writes nothing, and the underlying write already
+ * swallows IO errors. Keyed exactly as the catalog reads, so the recorded fact
+ * surfaces on the same account row.
+ */
+export declare function recordRunAuthOutcome(opts: {
+    agent: AgentId | string;
+    accountId?: string | null;
+    version?: string | null;
+    home?: string | null;
+    account?: string;
+    outcome: RunAuthOutcome;
+    host?: string;
+    now?: number;
+}): void;
+/** `Sep 20 14:02` — the fact timestamp for an auth failure. */
+export declare function factTimestamp(ms: number): string;
+/**
+ * The auth FACT `agents view` / `agents accounts` render per account per box
+ * (PHNX-4116): what actually happened here, with its time — never a word that
+ * means "we did not look". A `live` row (a recorded run OR a real probe) reads
+ * `last used ok <age>`; a server rejection reads `last auth failure <detail>
+ * <time>`; a throttle reads `rate-limited <detail> (<time>)`; anything with no
+ * usable evidence — including `no_evidence`/`unverified` — reads `not used on
+ * this box yet`.
+ */
+export declare function formatAuthFact(health: AuthHealth | null | undefined, now?: number): string;
 export {};

package/dist/lib/auth-health.js

@@ -27,6 +27,7 @@ import { getVersionHomePath, listInstalledVersions } from './installations/versi
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
 import { selfConfiguredDeviceRole } from './device-config.js';
 import { mayIssueUsageEndpointProbe, trySpendUsageApiCall } from './usage-refresh.js';
+import { machineId } from './machine-id.js';
 /** Maximum age of an auth verdict used for automatic routing decisions. */
 export const AUTH_PROBE_MAX_AGE_MS = 20 * 60_000;
 /** Agents with a live network probe wired up today. The rest are best-effort. */
@@ -82,6 +83,7 @@ const VERDICT_GLYPHS = {
     expired: '○', // ○
     rate_limited: '◐', // ◐
     unverified: '◐', // ◐
+    no_evidence: '◌', // ◌ — credential present, no evidence either way
     unconfigured: '·', // ·
     error: '·', // ·
 };
@@ -97,6 +99,7 @@ export function verdictLabel(verdict) {
         case 'expired': return 'expired';
         case 'rate_limited': return 'limited';
         case 'unverified': return 'unverified';
+        case 'no_evidence': return 'no evidence';
         case 'unconfigured': return '—';
         case 'error': return '?';
     }
@@ -109,7 +112,7 @@ export function summarizeVerdicts(verdicts) {
     for (const v of verdicts) {
         if (v === 'live')
             live++;
-        else if (v === 'unverified')
+        else if (v === 'unverified' || v === 'no_evidence')
             present++;
         else if (v === 'revoked')
             bad++;
@@ -132,6 +135,7 @@ export function verdictColor(verdict) {
         case 'live': return 'green';
         case 'revoked': return 'red';
         case 'unverified': return 'gray';
+        case 'no_evidence': return 'gray';
         case 'unconfigured': return 'dim';
         default: return 'yellow'; // expired / rate_limited / error — soft, self-healing/indeterminate
     }
@@ -188,6 +192,9 @@ export function summarizeHostAuth(cache, host) {
             case 'unverified':
                 present++;
                 break; // signed in, no probe — benign
+            case 'no_evidence':
+                present++;
+                break; // credential present, no evidence — benign
             case 'revoked':
                 revoked++;
                 break; // server said no — re-login
@@ -437,6 +444,14 @@ function verdictFromFreshUsage(usageKey, signedIn, now) {
     const capturedAt = snapshot?.capturedAt?.getTime();
     if (!capturedAt || now - capturedAt >= FRESH_USAGE_VERDICT_MAX_AGE_MS)
         return null;
+    // A `sync`-sourced snapshot arrived from ANOTHER box's poller over the fleet
+    // store — it proves the shared setup-token works SOMEWHERE, not that THIS box
+    // can authenticate (PHNX-4116). Deriving `live` from it is exactly the false
+    // "we did not look here, but a synced file is fresh, so call it live" the
+    // ticket removes. Only a reading THIS box captured itself (statusline/poll)
+    // is admissible live evidence.
+    if (snapshot?.freshness?.source === 'sync')
+        return null;
     const ageMin = Math.max(1, Math.round((now - capturedAt) / 60_000));
     return { verdict: 'live', checkedAt: now, detail: `token proven live by a usage fetch ${ageMin}m ago` };
 }
@@ -461,15 +476,21 @@ export async function probeAuthHealth(agent, home, opts) {
             role: selfConfiguredDeviceRole(),
             forceLive: opts?.forceLive,
         })) {
+            // A worker's setup-token cannot read the usage endpoint (RUSH-2392), so this
+            // box has no probe evidence for the account. This is NOT `unverified` (which
+            // conflated it with codex/grok's permanent no-probe-endpoint state): it is
+            // "we did not look here". A worker never publishes it — probeLocalFleetAuth
+            // drops `no_evidence` like `unconfigured` — so the account's facts come from
+            // token presence + recorded run outcomes instead (PHNX-4116).
             return {
-                verdict: 'unverified',
+                verdict: 'no_evidence',
                 checkedAt,
                 detail: 'setup-token box does not probe the usage endpoint',
             };
         }
         if (opts?.forceLive !== true && usageScope && !trySpendUsageApiCall(usageScope, agent, checkedAt)) {
             return {
-                verdict: 'unverified',
+                verdict: 'no_evidence',
                 checkedAt,
                 detail: 'usage-endpoint budget already spent this hour',
             };
@@ -573,7 +594,12 @@ export async function probeLocalFleetAuth(opts) {
         const health = await probeAuthHealth(rep.agent, rep.home, { cliVersion: opts?.cliVersion, info: rep.info, forceLive: opts?.forceLive, signal: opts?.signal });
         health.account = authAccountLabel(rep.info);
         health.accountId = rep.accountId;
-        if (health.verdict === 'unconfigured') {
+        health.source = 'probe';
+        // `unconfigured` (no credential) and `no_evidence` (a worker that cannot probe)
+        // both write NO row: the first has nothing to say, the second says only "we
+        // did not look", which is not a fleet-publishable verdict — the account's
+        // facts come from token presence + recorded run outcomes instead (PHNX-4116).
+        if (health.verdict === 'unconfigured' || health.verdict === 'no_evidence') {
             perGroup.push([]);
         }
         else {
@@ -618,3 +644,106 @@ export function writeFleetAuthRows(host, rows, installed) {
         : undefined;
     writeAuthHealthEntries(entries, drop);
 }
+// ---------------------------------------------------------------------------
+// Run-outcome recording + auth-fact rendering (PHNX-4116)
+//
+// A worker never probes, so the honest evidence that its token authenticates is
+// a REAL run: a successful inference (`live`) or an auth failure. These rows are
+// written with `source: 'run'` and read back as a FACT — `last used ok 12m ago`
+// / `last auth failure 401 Sep 20 14:02` / `not used on this box yet` — instead
+// of the misleading verdict word the ticket removes.
+// ---------------------------------------------------------------------------
+/**
+ * The installed-version label a run outcome falls back to when the account has no
+ * slot on this box: the explicit `version`, else the label derived from `home` (a
+ * version home is `<versionDir>/home`, so the label is its parent dir's basename).
+ * Null when neither resolves. Pure (no fs) so it is unit-tested directly.
+ */
+export function runOutcomeVersionKey(opts) {
+    if (opts.version)
+        return opts.version;
+    if (opts.home) {
+        const label = path.basename(path.dirname(opts.home));
+        if (label && label !== '.' && label !== path.sep)
+            return label;
+    }
+    return null;
+}
+/**
+ * Record a REAL run's auth outcome into the auth-health cache with
+ * `source: 'run'`. Best-effort and never throws: an unattributable run (no
+ * accountId/version/home) writes nothing, and the underlying write already
+ * swallows IO errors. Keyed exactly as the catalog reads, so the recorded fact
+ * surfaces on the same account row.
+ */
+export function recordRunAuthOutcome(opts) {
+    // Key exactly as the account catalog READS (slot key first, then the version
+    // label) so the fact lands on the row: the slot key ONLY when a slot dir
+    // actually exists for this account on this box (workers), else the installed
+    // version label (headed native logins have no slot). A last-resort slot key
+    // keeps an attributable-by-id run recorded even with no version hint.
+    const slotKey = opts.accountId && readSlots(readMeta())[opts.accountId]
+        ? slotAuthVersionKey(opts.accountId)
+        : null;
+    const versionKey = slotKey
+        ?? runOutcomeVersionKey(opts)
+        ?? (opts.accountId ? slotAuthVersionKey(opts.accountId) : null);
+    if (!versionKey)
+        return;
+    const checkedAt = opts.now ?? Date.now();
+    const host = opts.host ?? machineId();
+    let detail;
+    if (opts.outcome.ok) {
+        detail = 'run ok';
+    }
+    else if (opts.outcome.verdict === 'rate_limited' && opts.outcome.resetsAt) {
+        detail = `until ${factClock(opts.outcome.resetsAt)}`;
+    }
+    else {
+        detail = opts.outcome.detail;
+    }
+    const health = {
+        verdict: opts.outcome.ok ? 'live' : opts.outcome.verdict,
+        checkedAt,
+        source: 'run',
+        ...(detail ? { detail } : {}),
+        ...(opts.account ? { account: opts.account } : {}),
+        ...(opts.accountId ? { accountId: opts.accountId } : {}),
+    };
+    writeAuthHealthEntries({ [authCacheKey(host, opts.agent, versionKey)]: health });
+}
+const FACT_MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/** `HH:MM` local clock — used for a throttle reset time. */
+function factClock(ms) {
+    const d = new Date(ms);
+    return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+}
+/** `Sep 20 14:02` — the fact timestamp for an auth failure. */
+export function factTimestamp(ms) {
+    const d = new Date(ms);
+    return `${FACT_MONTHS[d.getMonth()]} ${d.getDate()} ${factClock(ms)}`;
+}
+/**
+ * The auth FACT `agents view` / `agents accounts` render per account per box
+ * (PHNX-4116): what actually happened here, with its time — never a word that
+ * means "we did not look". A `live` row (a recorded run OR a real probe) reads
+ * `last used ok <age>`; a server rejection reads `last auth failure <detail>
+ * <time>`; a throttle reads `rate-limited <detail> (<time>)`; anything with no
+ * usable evidence — including `no_evidence`/`unverified` — reads `not used on
+ * this box yet`.
+ */
+export function formatAuthFact(health, now = Date.now()) {
+    if (!health)
+        return 'not used on this box yet';
+    switch (health.verdict) {
+        case 'live':
+            return `last used ok ${formatCheckedAge(health.checkedAt, now)}`;
+        case 'revoked':
+        case 'expired':
+            return `last auth failure${health.detail ? ` ${health.detail}` : ''} ${factTimestamp(health.checkedAt)}`;
+        case 'rate_limited':
+            return `rate-limited${health.detail ? ` ${health.detail}` : ''} (${factTimestamp(health.checkedAt)})`;
+        default:
+            return 'not used on this box yet';
+    }
+}

package/dist/lib/browser/context.d.ts

@@ -0,0 +1,82 @@
+/**
+ * context.ts — everything agents-cli knows that the standalone `browser` engine
+ * cannot work out for itself, serialized as one JSON object onto fd 3.
+ *
+ * This is the whole contract of the consumer half (browser-cli integration
+ * contract §1). The engine accepts exactly this shape:
+ *
+ *   version        `1`. The engine matches on it; a field added later must be
+ *                  optional so an older engine keeps working.
+ *   target         the `--device <name>` target, resolved against the fleet:
+ *                  device registry, ssh identity, platform. The engine matches
+ *                  its own `--device <alias>` against this instead of reading a
+ *                  registry it does not have, then falls back to `~/.ssh/config`.
+ *                  Absent for a local invocation.
+ *   session        who is acting — actor id and agent session — so an action
+ *                  lands in the right session history.
+ *   remoteControl  whether THIS machine consents to being driven by a peer.
+ *                  agents-cli owns the policy; browser-cli enforces the flag.
+ *
+ * WHAT IS DELIBERATELY NOT HERE. The CDP/BiDi/Arc endpoint, the IPC socket, the
+ * chrome-data store and the profile declarations are the ENGINE's: browser-cli
+ * keeps every on-disk path the in-repo subsystem used (integration contract §4)
+ * and hydrates its own transport from them. agents-cli publishing an endpoint
+ * here would be a second, drifting copy of that answer.
+ *
+ * The context is PUSHED (written and closed) rather than exposed as a callback,
+ * so the engine never re-enters agents-cli and there is exactly one direction of
+ * dependency.
+ */
+/** A `--device <name>` target, resolved against the fleet. */
+export interface BrowserTargetContext {
+    /** The device name as the user typed it. */
+    alias: string;
+    /** `user@host`, already validated against ssh option injection. */
+    host: string;
+    user: string;
+    /** Bare host — the ssh-config Host name or address, without the user. */
+    hostname: string;
+    platform: string;
+    /** Per-device ssh identity flags, in argv order. Possibly empty. */
+    sshArgs: string[];
+}
+/** Who is acting, so the engine can stamp the action it reports back. */
+interface BrowserSessionContext {
+    sessionId?: string;
+    launchId?: string;
+    actor: string;
+}
+interface BrowserContext {
+    version: 1;
+    target?: BrowserTargetContext;
+    session: BrowserSessionContext;
+    remoteControl: {
+        allowed: boolean;
+    };
+}
+/**
+ * Whether this machine allows other fleet machines to drive its browser. Reads
+ * the device-scope `browser.remote-control` config key. Unset = off (deny).
+ * browser-cli reads and writes the same key, so a `remote-control on` typed at
+ * either surface agrees.
+ */
+export declare function remoteControlEnabled(): boolean;
+interface BuildContextOptions {
+    /** `--device <name>`, if given (only meaningful on `start`). */
+    device?: string;
+    /**
+     * A precomputed target, when the caller already resolved the device. When
+     * present, `device` need not be re-resolved.
+     */
+    target?: BrowserTargetContext;
+}
+/**
+ * Resolve `--device <name>` to a fleet target and build the context handed to
+ * the engine on fd 3.
+ *
+ * Unlike `agents computer`, browser drives ANY platform, so `resolveRemoteDevice`
+ * is called with no platform expectation — a `--device` pointing at a Mac, Linux
+ * box or Windows host all resolve.
+ */
+export declare function buildBrowserContext(opts?: BuildContextOptions): Promise<BrowserContext>;
+export {};

package/dist/lib/browser/context.js

@@ -0,0 +1,88 @@
+/**
+ * context.ts — everything agents-cli knows that the standalone `browser` engine
+ * cannot work out for itself, serialized as one JSON object onto fd 3.
+ *
+ * This is the whole contract of the consumer half (browser-cli integration
+ * contract §1). The engine accepts exactly this shape:
+ *
+ *   version        `1`. The engine matches on it; a field added later must be
+ *                  optional so an older engine keeps working.
+ *   target         the `--device <name>` target, resolved against the fleet:
+ *                  device registry, ssh identity, platform. The engine matches
+ *                  its own `--device <alias>` against this instead of reading a
+ *                  registry it does not have, then falls back to `~/.ssh/config`.
+ *                  Absent for a local invocation.
+ *   session        who is acting — actor id and agent session — so an action
+ *                  lands in the right session history.
+ *   remoteControl  whether THIS machine consents to being driven by a peer.
+ *                  agents-cli owns the policy; browser-cli enforces the flag.
+ *
+ * WHAT IS DELIBERATELY NOT HERE. The CDP/BiDi/Arc endpoint, the IPC socket, the
+ * chrome-data store and the profile declarations are the ENGINE's: browser-cli
+ * keeps every on-disk path the in-repo subsystem used (integration contract §4)
+ * and hydrates its own transport from them. agents-cli publishing an endpoint
+ * here would be a second, drifting copy of that answer.
+ *
+ * The context is PUSHED (written and closed) rather than exposed as a callback,
+ * so the engine never re-enters agents-cli and there is exactly one direction of
+ * dependency.
+ */
+import { resolveActor } from '../actor.js';
+import { resolveRemoteDevice } from '../ssh-tunnel.js';
+import { getConfigValue } from '../device-config.js';
+/**
+ * Which agent session is acting. The harness-native id first, then agents' own —
+ * the same precedence `lib/computer/context.ts` uses.
+ */
+function agentSessionId(env = process.env) {
+    return env.CODEX_THREAD_ID
+        || env.CLAUDE_CODE_SESSION_ID
+        || env.CLAUDE_SESSION_ID
+        || env.AGENTS_SESSION_ID
+        || env.AGENT_SESSION_ID
+        || env.AGENTS_RUN_ID
+        || undefined;
+}
+/**
+ * Whether this machine allows other fleet machines to drive its browser. Reads
+ * the device-scope `browser.remote-control` config key. Unset = off (deny).
+ * browser-cli reads and writes the same key, so a `remote-control on` typed at
+ * either surface agrees.
+ */
+export function remoteControlEnabled() {
+    return getConfigValue('browser.remote-control').value === true;
+}
+/**
+ * Resolve `--device <name>` to a fleet target and build the context handed to
+ * the engine on fd 3.
+ *
+ * Unlike `agents computer`, browser drives ANY platform, so `resolveRemoteDevice`
+ * is called with no platform expectation — a `--device` pointing at a Mac, Linux
+ * box or Windows host all resolve.
+ */
+export async function buildBrowserContext(opts = {}) {
+    let target = opts.target;
+    if (!target && opts.device && opts.device !== 'local') {
+        const resolved = await resolveRemoteDevice(opts.device);
+        target = {
+            alias: opts.device,
+            host: resolved.target,
+            user: resolved.user,
+            hostname: resolved.host,
+            platform: resolved.device.platform,
+            sshArgs: resolved.identityArgs,
+        };
+    }
+    return {
+        version: 1,
+        // Spread rather than assigned: a local invocation must not ship a `target`
+        // key at all, so the engine never has to distinguish absent from null.
+        ...(target ? { target } : {}),
+        session: {
+            sessionId: agentSessionId(),
+            launchId: process.env.AGENT_LAUNCH_ID,
+            actor: resolveActor().id,
+        },
+        remoteControl: { allowed: remoteControlEnabled() },
+    };
+}

package/dist/lib/browser/paths.d.ts

@@ -0,0 +1,25 @@
+/**
+ * paths.ts — the on-disk browser layout the CONSUMER still reads.
+ *
+ * browser-cli owns the browser process, drivers and IPC, but it keeps every
+ * on-disk path the in-repo subsystem used (integration contract §4). So
+ * `agents browser sessions` (`sessions-list.ts`) and the feed's browser tool
+ * rows (`feed/tool-activity.ts`) read a profile's captures straight off disk —
+ * no daemon, no engine — and need just these path helpers. They were the pure
+ * path corner of the deleted `profiles.ts` / `runtime-state.ts` engine files.
+ *
+ * A profile's live tasks and captures may live under a COMPOSITE runtime dir
+ * (`<profile>@<endpoint>`, `<profile>@<endpoint>.<fork>`), not the bare
+ * `<profile>` dir, so `listProfileCacheDirs` matches every dir that belongs to a
+ * profile — the same last-`@` rule browser-cli names them with.
+ */
+export { getBrowserDurableDir } from '../state.js';
+/** Root of the browser runtime cache — `~/.agents/.cache/browser/`. */
+export declare function getBrowserRuntimeDir(): string;
+/** The runtime cache dir for one profile's bare name. */
+export declare function getProfileRuntimeDir(name: string): string;
+/**
+ * Every runtime-cache dir that belongs to a profile, composite forms included.
+ * Empty when the root does not exist yet.
+ */
+export declare function listProfileCacheDirs(profileName: string): string[];