@phnx-labs/agents-cli 1.22.77 → 1.22.79

package/dist/lib/accounts/connect.js

@@ -0,0 +1,383 @@
+import * as crypto from 'node:crypto';
+import { nativeAccountCapability, nativeAccountNamingRefusal } from '../account-capabilities.js';
+import { listNativeAccounts } from '../account-registry.js';
+import { readMeta } from '../state.js';
+import { acquireAuthOperationLock } from './auth-operation-lock.js';
+/**
+ * `agents accounts connect <harness> [name]` — the stable-account front door
+ * (PHNX-3940).
+ *
+ * An account is stable INDEPENDENT of releases: connecting a NEW account mints a
+ * fresh opaque installation label, installs the current release into that
+ * label's isolated home (even when the same release is already installed under
+ * another label), and launches the harness's own native login there — no
+ * credential is copied or refreshed, the OAuth login stays owned by the harness.
+ * Reconnecting a NAMED EXISTING account reuses that account's existing home and
+ * fails CLOSED if the completed login is a different identity, so a reconnect can
+ * never overwrite some other account's home.
+ *
+ * This module owns the release-independent decision (plan), the opaque label,
+ * and the fail-closed identity check. The actual install + login spawn is
+ * injected (`ConnectRunners`) so the pure decision path is testable without a
+ * network install or a TTY, and so the parent can own the real E2E login+verify.
+ */
+/**
+ * Ambient provider-credential env vars stripped before a native login spawn, so
+ * the OAuth flow authenticates as the human's identity rather than being
+ * short-circuited by an injected API key / setup-token that would impersonate a
+ * different account into the fresh home.
+ */
+const PROVIDER_AUTH_ENV_KEYS = [
+    'ANTHROPIC_API_KEY',
+    'CLAUDE_CODE_OAUTH_TOKEN',
+    'ANTHROPIC_AUTH_TOKEN',
+    'OPENAI_API_KEY',
+    'CODEX_API_KEY',
+];
+/**
+ * Native-login invocation per harness. Only harnesses with a REAL, finite login
+ * COMMAND are listed — connect fails clearly for anything else rather than faking
+ * a flow that never signs the user in. Verified against the installed CLIs
+ * (PHNX-3940): `claude auth login --help` → "Sign in to your Anthropic account"
+ * with `--email`; `codex login` drives the OAuth flow. A harness is added here
+ * only once its isolated login command is verified.
+ */
+const LOGIN_INVOCATIONS = {
+    claude: { args: ['auth', 'login'], emailFlag: '--email', hint: 'Complete the Claude sign-in in your browser.' },
+    codex: { args: ['login'] },
+};
+/** Whether `connect` can drive this harness (isolation + a real native login). */
+export function connectSupported(agent) {
+    const cap = nativeAccountCapability(agent);
+    return cap.scope === 'version' && !!LOGIN_INVOCATIONS[agent];
+}
+/**
+ * Named reason connect refuses a harness, or null when supported. Distinguishes
+ * "cannot isolate/name this login" (capability) from "no native login command
+ * wired yet" so the message is honest about which limit was hit.
+ */
+export function connectRefusal(agent) {
+    const capabilityRefusal = nativeAccountNamingRefusal(agent);
+    if (capabilityRefusal)
+        return capabilityRefusal;
+    const cap = nativeAccountCapability(agent);
+    if (cap.scope !== 'version') {
+        return `${agent} authentication is ${cap.scope}-scoped; connect creates per-account isolated homes, which needs a version-scoped login.`;
+    }
+    if (!LOGIN_INVOCATIONS[agent]) {
+        const supported = Object.keys(LOGIN_INVOCATIONS).sort().join(', ');
+        return `connect does not yet drive ${agent}'s native login. Supported: ${supported}.`;
+    }
+    return null;
+}
+export function assertConnectSupported(agent) {
+    const reason = connectRefusal(agent);
+    if (reason)
+        throw new Error(reason);
+}
+export function loginInvocation(agent) {
+    const invocation = LOGIN_INVOCATIONS[agent];
+    if (!invocation)
+        throw new Error(`No native login command is wired for ${agent}.`);
+    return invocation;
+}
+/**
+ * Mint a fresh, opaque installation slot. `acct-<hex>` — alnum + hyphen only, so
+ * it satisfies VERSION_RE, and is visibly an account slot, not a release. It is
+ * RANDOM, never derived from the account name or identity: a name-derived slot
+ * recomputes an already-occupied home after a rename and lets a new connect
+ * overwrite another account's login (PHNX-3940 security fix). Retry-idempotency
+ * is instead provided by the device-scoped pending-connect map, and collision
+ * safety by allocating around occupied slots — see `allocateConnectSlot`.
+ */
+export function mintConnectLabel() {
+    return `acct-${crypto.randomBytes(6).toString('hex')}`;
+}
+/**
+ * Resolve the home to reuse for reconnecting an existing account: THIS box's
+ * recorded connect home first (device-scoped, survives an expired credential),
+ * else a currently-signed-in local home carrying its identity. Returns null when
+ * neither is known — a legacy account with no recorded or live home, for which
+ * connect adopts a fresh home.
+ */
+export function resolveExistingHomeLabel(existing, deviceHome, signedInHomes) {
+    if (deviceHome)
+        return deviceHome;
+    const match = signedInHomes.find(h => h.agent === existing.agent && h.identityKey === existing.identityKey);
+    return match?.label ?? null;
+}
+/**
+ * Decide the release-independent connect plan (pure). `existing` is the native
+ * account the name resolves to for THIS harness (or null for a new connect);
+ * `existingHomeLabel` is its reusable home from {@link resolveExistingHomeLabel};
+ * `freshSlot` is a safely-allocated opaque slot (see `allocateConnectSlot`) used
+ * for a new connect or an adopted reconnect home — NEVER a name-derived label.
+ */
+export function planConnect(input) {
+    if (input.existing) {
+        const reuse = input.existingHomeLabel;
+        return {
+            mode: 'reconnect',
+            agent: input.agent,
+            label: reuse ?? input.freshSlot,
+            name: input.existing.name,
+            existing: input.existing,
+            adoptedHome: !reuse,
+        };
+    }
+    return { mode: 'new', agent: input.agent, label: input.freshSlot, name: input.name };
+}
+/**
+ * Safely allocate the opaque slot for a NEW connect or an ADOPTED reconnect home
+ * (PHNX-3940 security fix). Never reuses an identity-bearing slot:
+ *
+ * - `occupied` is every slot already owned by an account's home OR currently
+ *   signed in — an allocated slot is guaranteed disjoint from it, so a new
+ *   connect can never land on another account's home (the rename-collision flaw).
+ * - A named connect first reuses its device-scoped PENDING slot (a prior
+ *   failed/cancelled attempt) IF that slot is not occupied, so a retry lands in
+ *   the same fresh home instead of orphaning a new one.
+ * - Otherwise it mints random slots until one is neither occupied nor installed.
+ */
+export function allocateConnectSlot(input) {
+    const mint = input.mint ?? mintConnectLabel;
+    // Retry reuse is only for a NEW named connect (pending is keyed by name); a
+    // pending slot that has since become occupied is abandoned, never overwritten.
+    if (!input.existing && input.name && input.pending && !input.occupied.has(input.pending)) {
+        return input.pending;
+    }
+    let slot = mint();
+    while (input.occupied.has(slot) || input.installedLabels.has(slot))
+        slot = mint();
+    return slot;
+}
+/**
+ * Fail-closed identity check after the login completes (pure).
+ *
+ * - Not signed in (no live credential) → the login did not complete; a metadata
+ *   identity key alone is NOT proof, so `signedIn` is required.
+ * - Reconnect whose completed identity differs from the account's → REFUSE
+ *   registering the binding. The native credential in that home DID change (the
+ *   user signed in), so the message says the account BINDING is left unchanged —
+ *   it does not claim nothing happened.
+ * A new connect accepts whatever identity signed in (that is the account being
+ * created); the caller registers it.
+ */
+export function verifyConnectedIdentity(plan, observed) {
+    if (!observed.signedIn || !observed.identityKey) {
+        throw new Error(`No ${plan.agent} login completed in ${plan.agent}@${plan.label} (no live credential). Nothing was connected.`);
+    }
+    if (plan.mode === 'reconnect' && plan.existing && observed.identityKey !== plan.existing.identityKey) {
+        throw new Error(`The ${plan.agent} login that just completed in ${plan.agent}@${plan.label} is a different identity `
+            + `(${observed.identityKey}) than account '${plan.existing.name}' (${plan.existing.identityKey}). `
+            + `Account '${plan.existing.name}' still points at its original identity (binding unchanged); `
+            + `connect a NEW account for this login instead.`);
+    }
+}
+/** Resolve the existing native account a connect `name` refers to for a harness. */
+export function findConnectAccount(agent, name, meta) {
+    if (!name)
+        return null;
+    const needle = name.toLowerCase();
+    return listNativeAccounts(meta).find(a => a.agent === agent && (a.id === name || a.name.toLowerCase() === needle || a.identityLabel?.toLowerCase() === needle)) ?? null;
+}
+/**
+ * Drive one `agents accounts connect`. Pure decisions (plan, fail-closed verify)
+ * come from the helpers above; the install + login + identity read are injected.
+ *
+ * The default runners are loaded via dynamic import so this module — reachable
+ * from `account-registry` consumers — never statically pulls in the install
+ * engine or exec path and closes an import cycle (the intended pattern here).
+ *
+ * `stateDir` is only for tests: override the runtime-state dir used by the
+ * per-harness auth-operation mutex (defaults to the real runtime state dir).
+ */
+export async function runConnect(agent, name, opts, runners) {
+    assertConnectSupported(agent);
+    // Acquire the per-harness auth-operation mutex BEFORE any meta read, slot
+    // allocation, or name validation — two parallel connects for the same harness
+    // would otherwise both see "name available" and "slot free", then race to
+    // register the same slot or the same name, overwriting one account's home.
+    const lock = acquireAuthOperationLock(agent, opts.stateDir);
+    try {
+        return await _runConnectLocked(agent, name, opts, lock, runners);
+    }
+    finally {
+        lock.release();
+    }
+}
+async function _runConnectLocked(agent, name, opts, lock, runners) {
+    const run = runners ?? await defaultConnectRunners();
+    const registry = await import('../account-registry.js');
+    lock.assertHeld();
+    // Re-read meta AFTER acquiring the lock so we see any writes a concurrent
+    // connect committed before we were serialized past it. `opts.meta` was a
+    // snapshot taken before the lock was available and must not be used here.
+    const meta = readMeta();
+    const existing = findConnectAccount(agent, name, meta);
+    // Validate the requested NAME and its collisions BEFORE any install or login,
+    // so a bad name never mints an orphan home and drives a login that can't be
+    // recorded. Only a genuinely NEW named connect needs this (a reconnect names an
+    // account that already passed the check).
+    if (!existing && name)
+        registry.assertNativeAccountNameAvailable(name, agent);
+    const signedIn = await run.signedInHomes();
+    lock.assertHeld();
+    const existingHomeLabel = existing
+        ? resolveExistingHomeLabel(existing, registry.nativeAccountHome(existing.id, meta), signedIn)
+        : null;
+    // SECURITY (PHNX-3940): allocate a fresh slot that is DISJOINT from every
+    // occupied home — a slot already owned by an account OR currently signed in.
+    // This is what stops a NEW connect (e.g. `connect work` after `work` was
+    // renamed `personal`) from landing on and overwriting another account's login.
+    const occupied = new Set([
+        ...registry.ownedConnectHomeLabels(meta),
+        ...signedIn.filter(h => h.agent === agent).map(h => h.label),
+    ]);
+    const freshSlot = allocateConnectSlot({
+        agent,
+        name,
+        existing,
+        occupied,
+        installedLabels: new Set(run.installedLabels(agent)),
+        pending: (!existing && name) ? registry.pendingConnectSlot(agent, name, meta) : null,
+    });
+    // Record the in-flight slot for a named connect so a failed retry reuses it.
+    if (!existing && name && freshSlot !== registry.pendingConnectSlot(agent, name, meta)) {
+        registry.setPendingConnectSlot(agent, name, freshSlot);
+    }
+    const plan = planConnect({ agent, name, existing, existingHomeLabel, freshSlot });
+    // Pre-launch guard (both modes): if the chosen home is already installed AND
+    // signed in, refuse to launch a login that would OVERWRITE its identity —
+    // unless it is the SAME identity we are (re)connecting. For a NEW connect any
+    // signed-in identity is a stranger; for a reconnect only a DIFFERENT one is.
+    if (run.installedLabels(agent).includes(plan.label)) {
+        const current = await run.observeIdentity(agent, plan.label);
+        lock.assertHeld();
+        const intended = existing?.identityKey;
+        if (current.signedIn && current.identityKey && current.identityKey !== intended) {
+            throw new Error(`${agent}@${plan.label} is currently signed in as ${current.identityKey}`
+                + `${existing ? ` (not account '${existing.name}')` : ''}. `
+                + `Refusing to launch a login that would overwrite it.`);
+        }
+    }
+    // Install the current release into the account's home. A reconnect that reuses
+    // an already-installed home skips the install (reuse, don't re-mint); a new
+    // account (or an adopted reconnect home) installs the current release under its
+    // opaque label even when the same release is already installed elsewhere. A
+    // retried named connect reuses the same pending slot rather than orphaning.
+    const alreadyInstalled = run.installedLabels(agent).includes(plan.label);
+    lock.assertHeld();
+    if (!(alreadyInstalled && (plan.mode === 'reconnect' || !!name))) {
+        opts.onProgress?.(`Installing ${agent} into ${plan.label}…`);
+        const install = await run.install(agent, plan.label, opts.onProgress);
+        lock.assertHeld();
+        if (!install.success)
+            throw new Error(`Could not install ${agent} for the account home: ${install.error ?? 'unknown error'}`);
+    }
+    const invocation = loginInvocation(agent);
+    if (invocation.hint)
+        opts.onProgress?.(invocation.hint);
+    const loginEmail = existing?.identityLabel;
+    lock.assertHeld();
+    const login = await run.launchLogin(agent, plan.label, invocation, loginEmail, lock.signal);
+    lock.assertHeld();
+    // A cancelled or failed login exits non-zero — do NOT read stale metadata and
+    // report success. A NAMED connect can retry the same home (its slot is pending);
+    // an UNNAMED connect has no pending slot, so a re-run allocates a new home.
+    if (login.code !== 0) {
+        const retry = name ? 're-run to retry the same home' : 're-run to try again (a new home is allocated)';
+        throw new Error(`${agent} login did not complete (exit ${login.code ?? 'null'}) in ${agent}@${plan.label}. Nothing was recorded; ${retry}.`);
+    }
+    const observed = await run.observeIdentity(agent, plan.label);
+    lock.assertHeld();
+    verifyConnectedIdentity(plan, observed);
+    const identityKey = observed.identityKey;
+    // Persist THIS box's account⇄home binding (device-scoped) so a later reconnect
+    // reuses this exact home even after the credential expires, and clear the
+    // in-flight pending slot now that it is a real account home.
+    let becameDefault = false;
+    let nameHint;
+    if (plan.mode === 'new') {
+        if (name) {
+            const account = registry.addNativeAccount(name, agent, identityKey, observed.email ?? undefined, 'version');
+            registry.setNativeAccountHome(account.id, plan.label);
+            registry.clearPendingConnectSlot(agent, name);
+            // Select this account as the harness default ONLY if none is configured —
+            // never override an existing choice, and never force a duplicate name.
+            becameDefault = registry.setDefaultAccountIfAbsent(agent, account.name);
+        }
+        else {
+            // No name was given: do not invent/force one. Point the user at the command
+            // that names this login so it becomes selectable and default-eligible.
+            nameHint = `agents accounts label ${agent} <name>`;
+        }
+    }
+    else if (existing) {
+        registry.setNativeAccountHome(existing.id, plan.label);
+    }
+    return {
+        mode: plan.mode,
+        agent,
+        label: plan.label,
+        name: plan.name ?? name,
+        identityKey,
+        email: observed.email,
+        releaseVersion: observed.releaseVersion,
+        becameDefault,
+        nameHint,
+    };
+}
+/** Real runners: the install engine, an inherited-stdio login spawn, and identity read. */
+async function defaultConnectRunners() {
+    const [{ installVersion, getVersionHomePath, listInstalledVersions }, store, agentsMod, execMod] = await Promise.all([
+        import('../installations/versions.js'),
+        import('../installations/store.js'),
+        import('../agents.js'),
+        import('../exec.js'),
+    ]);
+    const { readInstallation } = store;
+    const { getAccountInfo } = agentsMod;
+    const { buildExecEnv } = execMod;
+    const { nativeAccountCapability, nativeIdentityKey } = await import('../account-capabilities.js');
+    const { runNativeAccountCommand } = await import('../installations/native-command.js');
+    return {
+        installedLabels: (agent) => listInstalledVersions(agent),
+        install: async (agent, label, onProgress) => {
+            const result = await installVersion(agent, 'latest', onProgress, { installationLabel: label });
+            return { success: result.success, error: result.error };
+        },
+        launchLogin: async (agent, label, invocation, email, signal) => {
+            // Pin the harness's own config-dir env (CLAUDE_CONFIG_DIR / CODEX_HOME) to
+            // this label's isolated home so the native login lands there — no
+            // credential is copied; the login writes into the home it authenticates.
+            const env = buildExecEnv({ agent, version: label, configVersion: label, interactive: true, mode: 'auto', effort: 'auto', cwd: process.cwd() });
+            // Strip any ambient provider API-key / setup-token env so the native login
+            // authenticates as the human's OAuth identity, not an injected credential
+            // that would impersonate a different account into this home.
+            for (const key of PROVIDER_AUTH_ENV_KEYS)
+                delete env[key];
+            const args = email && invocation.emailFlag ? [...invocation.args, invocation.emailFlag, email] : invocation.args;
+            return runNativeAccountCommand(agent, label, args, env, signal);
+        },
+        observeIdentity: async (agent, label) => {
+            const home = getVersionHomePath(agent, label);
+            const info = await getAccountInfo(agent, home);
+            const { isLaunchableSignedIn } = await import('../account-catalog.js');
+            return {
+                identityKey: nativeIdentityKey(info, nativeAccountCapability(agent)),
+                email: info.email,
+                releaseVersion: readInstallation(agent, label)?.releaseVersion ?? null,
+                // Strict: a live credential in THIS home, not a bare metadata identity.
+                signedIn: isLaunchableSignedIn(agent, home, info),
+            };
+        },
+        signedInHomes: async () => {
+            const { collectNativeHomeRows } = await import('../account-catalog.js');
+            const rows = await collectNativeHomeRows();
+            return rows
+                .filter(r => r.signedIn && (r.accountKey ?? r.email))
+                .map(r => ({ agent: r.agent, identityKey: (r.accountKey ?? r.email.toLowerCase()), label: r.label }));
+        },
+    };
+}

package/dist/lib/actor.d.ts

@@ -1,3 +1,4 @@
+import { type PhoenixSession } from './identity/client.js';
 import type { ActorConfig } from './types.js';
 export type ActorKind = 'human' | 'agent';
 export interface ResolvedActor {
@@ -20,6 +21,13 @@ export interface ResolvedActor {
      * happens to be signed into tailscale with.
      */
     phoenixId?: string;
+    /**
+     * The human's hosted profile picture (https URL) from the Phoenix ID session
+     * signed in on this device, attached only when that session belongs to the
+     * same email as the resolved actor. Rides the env as `AGENTS_ACTOR_AVATAR` so
+     * tools the agent runs (artifacts, shares) can show the person, not initials.
+     */
+    avatarUrl?: string;
 }
 /** Result of `tailscale whois --json <ip>` we care about. */
 export interface WhoisIdentity {
@@ -34,6 +42,13 @@ export interface WhoisIdentity {
  * from the tailnet DisplayName + login email.
  */
 export declare function actorFromIdentity(who: WhoisIdentity | undefined, host: string, actors: Record<string, ActorConfig>): ResolvedActor;
+/**
+ * The Phoenix ID profile picture for a resolved human, when the session signed
+ * in on this device is that same person (matched on email, case-insensitive).
+ * A shared box signed in as someone else must not lend its picture to whoever
+ * SSH-ed in, so a mismatch yields nothing. Pure: the session is injected.
+ */
+export declare function actorAvatar(actor: ResolvedActor, session: PhoenixSession | null): string | undefined;
 /**
  * Injectable tailscale resolvers, so tests can drive the SSH-whois and
  * local-self branches deterministically without a real tailscale on the box
@@ -43,6 +58,8 @@ export declare function actorFromIdentity(who: WhoisIdentity | undefined, host:
 export interface ActorResolvers {
     whois: (ip: string) => WhoisIdentity | undefined;
     self: () => WhoisIdentity | undefined;
+    /** The Phoenix ID session on this device (a local file read, no network). */
+    session: () => PhoenixSession | null;
 }
 /**
  * Compute the actor for a given environment. The only impurity is the tailscale

package/dist/lib/actor.js

@@ -25,6 +25,7 @@
 import { spawnSync } from 'child_process';
 import { machineId } from './machine-id.js';
 import { parseSshConnection } from './session/provenance.js';
+import { readSession } from './identity/client.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;
@@ -145,9 +146,28 @@ function inheritedActor(env) {
         email: env.AGENTS_ACTOR_EMAIL || undefined,
         github: env.AGENTS_ACTOR_GITHUB || undefined,
         phoenixId: env.AGENTS_ACTOR_PHOENIX_ID || undefined,
+        avatarUrl: httpsUrl(env.AGENTS_ACTOR_AVATAR),
     };
 }
-const defaultResolvers = { whois: tailscaleWhois, self: tailscaleSelf };
+/** An avatar is only ever an https URL; anything else is not an avatar. */
+function httpsUrl(value) {
+    const trimmed = value?.trim();
+    return trimmed && /^https:\/\/\S+$/i.test(trimmed) ? trimmed : undefined;
+}
+/**
+ * The Phoenix ID profile picture for a resolved human, when the session signed
+ * in on this device is that same person (matched on email, case-insensitive).
+ * A shared box signed in as someone else must not lend its picture to whoever
+ * SSH-ed in, so a mismatch yields nothing. Pure: the session is injected.
+ */
+export function actorAvatar(actor, session) {
+    if (actor.kind !== 'human' || !actor.email || !session?.email)
+        return undefined;
+    if (actor.email.trim().toLowerCase() !== session.email.trim().toLowerCase())
+        return undefined;
+    return httpsUrl(session.avatarUrl);
+}
+const defaultResolvers = { whois: tailscaleWhois, self: tailscaleSelf, session: readSession };
 /**
  * Compute the actor for a given environment. The only impurity is the tailscale
  * shell-out (injectable via `resolvers`), so tests drive every branch explicitly.
@@ -171,7 +191,9 @@ export function computeActor(env = process.env, resolvers = defaultResolvers) {
     // UNRESOLVED rather than being misattributed to the box's owner.
     if (!who && !sshRaw)
         who = resolvers.self();
-    return actorFromIdentity(who, machineId(), readActors());
+    const actor = actorFromIdentity(who, machineId(), readActors());
+    const avatarUrl = actorAvatar(actor, resolvers.session());
+    return avatarUrl ? { ...actor, avatarUrl } : actor;
 }
 let cached;
 let resolverOverride;
@@ -220,6 +242,8 @@ export function actorEnv(actor) {
         env.AGENTS_ACTOR_GITHUB = actor.github;
     if (actor.phoenixId)
         env.AGENTS_ACTOR_PHOENIX_ID = actor.phoenixId;
+    if (actor.avatarUrl)
+        env.AGENTS_ACTOR_AVATAR = actor.avatarUrl;
     if (actor.kind === 'human' && actor.name && actor.email) {
         env.GIT_AUTHOR_NAME = actor.name;
         env.GIT_AUTHOR_EMAIL = actor.email;

package/dist/lib/capabilities.js

@@ -11,6 +11,7 @@ import { AGENTS, MANAGED_AGENT_IDS } from './agents.js';
 // agent-spec/primitives is a leaf module — importing it creates no cycle, and it
 // is the only compareVersions that honors OpenClaw's `-N` rebuild suffix.
 import { compareVersions } from './agent-spec/primitives.js';
+import { installedReleaseFor } from './installations/store.js';
 function getCapability(agent, cap) {
     // Guard against unknown agent ids (e.g. a caller passing "claude@2.1.168"
     // instead of "claude"). Without this, AGENTS[agent] is undefined and the
@@ -48,6 +49,7 @@ export function supports(agent, cap, version) {
         return { ok: true };
     if (!version)
         return { ok: true };
+    version = installedReleaseFor(agent, version);
     if (c.since && compareVersions(version, c.since) < 0) {
         return { ok: false, reason: 'too_old', need: `>= ${c.since}` };
     }

package/dist/lib/commands.js

@@ -8,6 +8,7 @@
  */
 import * as fs from 'fs';
 import { compareVersions } from './agent-spec/primitives.js';
+import { installedReleaseFor } from './installations/store.js';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { AGENTS, ensureCommandsDir, agentConfigDirName, resolveAgentName } from './agents.js';
@@ -48,6 +49,7 @@ export function commandAppliesTo(agent, version, metadata) {
     if (metadata?.agents?.length && !metadata.agents.includes(agent)) {
         return { ok: false, reason: 'agent_excluded' };
     }
+    version = installedReleaseFor(agent, version);
     if (metadata?.since && compareVersions(version, metadata.since) < 0) {
         return { ok: false, reason: 'too_old', need: `>= ${metadata.since}` };
     }

package/dist/lib/config-keys.d.ts

@@ -9,7 +9,7 @@
 import type { AgentId } from './types.js';
 import { type ModelTier } from './model-tiers.js';
 /** The top-level scope of a unified config key. */
-export type ConfigScope = 'run' | 'interactive' | 'auto' | 'browser' | 'project' | 'device' | 'summarizer';
+export type ConfigScope = 'run' | 'interactive' | 'auto' | 'browser' | 'project' | 'device' | 'summarizer' | 'updates';
 /** A run-time default key: model, mode, effort, or tier override. */
 export interface ParsedRunConfigKey {
     scope: 'run';
@@ -51,7 +51,16 @@ export interface ParsedSummarizerConfigKey {
     scope: 'summarizer';
     property: 'enabled' | 'baseUrl' | 'model';
 }
-export type ParsedConfigKey = ParsedRunConfigKey | ParsedInteractiveConfigKey | ParsedAutoConfigKey | ParsedBrowserConfigKey | ParsedProjectConfigKey | ParsedDeviceConfigKey | ParsedSummarizerConfigKey;
+/**
+ * The managed-harness auto-update switch (PHNX-3940): `updates.auto` (global)
+ * or `updates.<agent>.auto` (one harness — `agent` is set).
+ */
+export interface ParsedUpdatesConfigKey {
+    scope: 'updates';
+    property: 'auto';
+    agent?: AgentId;
+}
+export type ParsedConfigKey = ParsedRunConfigKey | ParsedInteractiveConfigKey | ParsedAutoConfigKey | ParsedBrowserConfigKey | ParsedProjectConfigKey | ParsedDeviceConfigKey | ParsedSummarizerConfigKey | ParsedUpdatesConfigKey;
 export type DeviceConfigProperty = 'role' | 'max-agents' | 'scheduler' | 'daemon' | 'watchdog' | 'tmux' | 'browser.remote-control' | 'browser.task-idle-minutes' | 'notes' | 'browser.profile' | 'browser.viewer';
 /** Normalize agent@version to use `@` consistently. */
 export declare function formatAgentVersion(agent: AgentId, version: string): string;

package/dist/lib/config-keys.js

@@ -98,6 +98,17 @@ export function parseConfigKey(key) {
     if (summarizerMatch) {
         return { scope: 'summarizer', property: summarizerMatch[1] };
     }
+    if (raw === 'updates.auto') {
+        return { scope: 'updates', property: 'auto' };
+    }
+    const updatesAgentMatch = raw.match(/^updates\.(.+)\.auto$/);
+    if (updatesAgentMatch) {
+        const agentPart = updatesAgentMatch[1].toLowerCase();
+        if (!(agentPart in AGENTS)) {
+            throw new Error(`Unknown agent '${updatesAgentMatch[1]}' in '${key}'. Known agents: ${Object.keys(AGENTS).join(', ')}.`);
+        }
+        return { scope: 'updates', agent: agentPart, property: 'auto' };
+    }
     const deviceMatch = raw.match(/^devices\.(.+)\.(role|max-agents|scheduler|daemon|watchdog|tmux|notes|browser\.remote-control|browser\.task-idle-minutes|browser\.profile|browser\.viewer)$/);
     if (deviceMatch) {
         return {
@@ -125,6 +136,9 @@ export function parseConfigKey(key) {
     if (raw.startsWith('summarizer.')) {
         throw new Error(`Invalid summarizer config key '${key}'. Use summarizer.enabled, summarizer.baseUrl, or summarizer.model.`);
     }
+    if (raw.startsWith('updates.')) {
+        throw new Error(`Invalid updates config key '${key}'. Use updates.auto or updates.<agent>.auto.`);
+    }
     if (raw.startsWith('devices.')) {
         throw new Error(`Invalid device config key '${key}'. Expected devices.<name>.<${DEVICE_CONFIG_PROPERTIES.join('|')}>.`);
     }
@@ -152,6 +166,8 @@ export function formatConfigKey(parsed) {
             return `devices.${parsed.device}.${parsed.property}`;
         case 'summarizer':
             return `summarizer.${parsed.property}`;
+        case 'updates':
+            return parsed.agent ? `updates.${parsed.agent}.auto` : 'updates.auto';
     }
 }
 /** List every canonical key the command documents, with wildcards expanded to a concrete example. */
@@ -161,7 +177,7 @@ export function listKnownConfigKeys() {
     for (const tier of MODEL_TIERS) {
         keys.push(`run.<agent@version>.tier.${tier}`);
     }
-    keys.push('interactive.host', 'auto.pool', 'browser.profile', 'browser.viewer', 'browser.device', 'project.root', 'summarizer.enabled', 'summarizer.baseUrl', 'summarizer.model');
+    keys.push('interactive.host', 'auto.pool', 'browser.profile', 'browser.viewer', 'browser.device', 'project.root', 'summarizer.enabled', 'summarizer.baseUrl', 'summarizer.model', 'updates.auto', 'updates.<agent>.auto');
     for (const prop of DEVICE_CONFIG_PROPERTIES) {
         keys.push(`devices.<name>.${prop}`);
     }
@@ -233,5 +249,9 @@ export function configKeyStorageHint(parsed) {
                 : parsed.property === 'baseUrl' ? 'summarizerBaseUrl' : 'summarizerModel';
             return `config.${yamlKey} (central agents.yaml; syncs fleet-wide)`;
         }
+        case 'updates':
+            return parsed.agent
+                ? `config.updatesAgentAuto.${parsed.agent} (central agents.yaml; syncs fleet-wide)`
+                : 'config.updatesAuto (central agents.yaml; syncs fleet-wide)';
     }
 }

package/dist/lib/daemon/daemon.js

@@ -42,6 +42,7 @@ import { WatchdogService } from './watchdog-service.js';
 import { DeviceProbeService } from './device-probe-service.js';
 import { SelfHealService } from './self-heal-service.js';
 import { SelfUpdateService } from './self-update-service.js';
+import { HarnessUpdateService } from './harness-update-service.js';
 import { KeychainReapService } from './keychain-reap-service.js';
 import { AuthSyncService } from './auth-sync-service.js';
 import { UsageSyncService } from './usage-sync-service.js';
@@ -1090,6 +1091,10 @@ export async function runDaemon() {
         supervisor.register(new SelfUpdateService());
     else
         log('INFO', 'Self-update service disabled');
+    if (isEnabled('harness-update'))
+        supervisor.register(new HarnessUpdateService());
+    else
+        log('INFO', 'Harness-update service disabled');
     if (isEnabled('keychain-reap'))
         supervisor.register(new KeychainReapService());
     else