@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/lib/usage.d.ts

@@ -151,6 +151,22 @@ export declare function deriveUsageStatusFromSnapshot(snapshot: UsageSnapshot |
 export declare function formatUsageStatusBadge(usageStatus: 'available' | 'rate_limited' | 'out_of_credits' | null | undefined): string;
 /** Format a multi-line usage section for detailed agent views. */
 export declare function formatUsageSection(usage: UsageInfo): string[];
+/**
+ * The access token to use for a READ-ONLY Claude usage fetch, or null when the
+ * stored token is within the refresh leeway.
+ *
+ * Returns null instead of refreshing on purpose. Claude's refresh token is
+ * single-use and rotates server-side on every refresh; with one account signed
+ * into several machines, refreshing here would stampede that one token and
+ * silently invalidate every other holder — the RUSH-1822 failure, except in the
+ * usage path (fired in the background by the SWR cache and by `agents run`'s
+ * default "balanced" rotation on every unpinned run) rather than the health
+ * probe. So a usage read must never rotate: a near-expiry token yields "no usage
+ * right now" instead of a fleet-wide logout. Mirrors {@link probeClaudeStatus};
+ * the single legitimate refresh belongs to the actual claude run, never a read.
+ * Pure — unit-tested.
+ */
+export declare function claudeUsageAccessTokenNoRefresh(oauth: Pick<ClaudeOauthCredentials, 'accessToken' | 'expiresAt'>): string | null;
 /** Raw quota bucket from the Kimi /usages response (numbers arrive as strings). */
 interface KimiUsageQuota {
     limit?: string | number | null;
@@ -242,8 +258,24 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
  * Without step 2 the live usage fetch got no token on Linux, so `agents view`
  * (run remotely over SSH by `--host`) rendered no usage bars even though the
  * account + plan — read from the plaintext `.claude.json` — showed fine.
+ *
+ * `opts.accessTokenCache` opts INTO the no-ACL access-token cache (the Touch ID
+ * storm fix, see the cache helpers above). It is OFF by default so every caller
+ * keeps the full ACL-read credential — the cached copy deliberately omits the
+ * refresh token, so callers that refresh (`isClaudeAuthValid` ->
+ * `getClaudeAccessToken`) or export the full blob (`readClaudeCredentialsBlob`
+ * for Rush Cloud dispatch) must NOT pass it. Only the read-only, high-frequency
+ * access-token-only consumers (the usage fetch and the auth-health probe) opt in.
+ */
+export declare function loadClaudeOauth(home?: string, opts?: {
+    accessTokenCache?: boolean;
+}): Promise<ClaudeOauthCredentials | null>;
+/**
+ * Save Claude OAuth credentials to the system keychain/keyring.
+ * Reads the existing payload, merges the new OAuth fields, and writes back.
+ * Exported for regression tests; not part of the public command surface.
  */
-export declare function loadClaudeOauth(home?: string): Promise<ClaudeOauthCredentials | null>;
+export declare function saveClaudeOauth(home: string | undefined, credentials: ClaudeOauthCredentials): Promise<boolean>;
 /**
  * Derive the Keychain service name for a Claude home directory.
  * Managed (non-default) homes get a hash suffix for isolation.

package/dist/lib/usage.js

@@ -17,7 +17,7 @@ import { promisify } from 'util';
 import chalk from 'chalk';
 import { decodeJwtPayload, decryptDroidAuthPayload } from './agents.js';
 import { walkForFiles } from './fs-walk.js';
-import { getKeychainToken, setKeychainToken, deleteKeychainToken, } from './secrets/index.js';
+import { getKeychainToken, setKeychainToken, deleteKeychainToken, isKeychainBackendOverridden, } from './secrets/index.js';
 import { getCacheDir } from './state.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
@@ -375,10 +375,33 @@ async function getCodexUsageInfo(options) {
         return { snapshot: null, error: null };
     }
 }
+/**
+ * The access token to use for a READ-ONLY Claude usage fetch, or null when the
+ * stored token is within the refresh leeway.
+ *
+ * Returns null instead of refreshing on purpose. Claude's refresh token is
+ * single-use and rotates server-side on every refresh; with one account signed
+ * into several machines, refreshing here would stampede that one token and
+ * silently invalidate every other holder — the RUSH-1822 failure, except in the
+ * usage path (fired in the background by the SWR cache and by `agents run`'s
+ * default "balanced" rotation on every unpinned run) rather than the health
+ * probe. So a usage read must never rotate: a near-expiry token yields "no usage
+ * right now" instead of a fleet-wide logout. Mirrors {@link probeClaudeStatus};
+ * the single legitimate refresh belongs to the actual claude run, never a read.
+ * Pure — unit-tested.
+ */
+export function claudeUsageAccessTokenNoRefresh(oauth) {
+    if (claudeAccessTokenNeedsRefresh(oauth.expiresAt ?? null))
+        return null;
+    const token = oauth.accessToken?.trim();
+    return token ? token : null;
+}
 /** Fetch Claude usage via the Anthropic OAuth usage API. */
 async function getClaudeUsageInfo(options) {
     try {
-        const oauth = await loadClaudeOauth(options?.home);
+        // Opt into the no-ACL access-token cache: this is the every-60s watchdog hot
+        // path and usage needs only the access token, so it kills the Touch ID storm.
+        const oauth = await loadClaudeOauth(options?.home, { accessTokenCache: true });
         if (!oauth?.accessToken) {
             return { snapshot: null, error: null };
         }
@@ -387,7 +410,8 @@ async function getClaudeUsageInfo(options) {
         if (!isClaudeUsageOrgMatch(requestedOrgId, liveOrgId)) {
             return { snapshot: null, error: null };
         }
-        const accessToken = await getClaudeAccessToken(oauth, options?.home);
+        // Read-only: never refresh a single-use token just to read usage (RUSH-1822).
+        const accessToken = claudeUsageAccessTokenNoRefresh(oauth);
         if (!accessToken) {
             return { snapshot: null, error: null };
         }
@@ -627,7 +651,10 @@ async function getDroidUsageInfo(options) {
 }
 /** Probe Claude's OAuth token against the usage endpoint. Never refreshes — reports `expired` for a near-expiry token; see the comment below (RUSH-1822). */
 export async function probeClaudeStatus(home, cliVersion) {
-    const oauth = await loadClaudeOauth(home);
+    // Opt into the no-ACL access-token cache: the daemon warms this probe every ~3
+    // min per account and it never refreshes (access token only), so caching is safe
+    // and stops it from adding to the Touch ID storm.
+    const oauth = await loadClaudeOauth(home, { accessTokenCache: true });
     const accessToken = oauth?.accessToken?.trim();
     if (!accessToken)
         return { status: null, token: 'missing' };
@@ -862,6 +889,103 @@ function parseClaudeOauthPayload(raw) {
         return null;
     }
 }
+// ── No-ACL cache for Claude's OAuth token (kills the macOS Touch ID storm) ──
+//
+// The source item `Claude Code-credentials-<hash>` is ACL-bound to Claude Code's
+// own process, so every read agents-cli makes (via `/usr/bin/security`) pops
+// Touch ID. The Factory watchdog polls `agents view --json` every 60s per agent,
+// and each poll that crosses the 2-minute usage cache fires a background refresh
+// -> loadClaudeOauth -> keychain read -> a biometric prompt. With many agents and
+// accounts that is a prompt every couple of minutes, per account.
+//
+// Fix: after one real (prompting) read, cache the ACCESS token in a device-local
+// NO-ACL keychain item — the same `set-no-acl` mechanism secrets/session-store.ts
+// uses for unlocked bundles, whose reads never prompt — and serve every later read
+// from it until the token's own `expiresAt`. The ACL read then happens at most once
+// per token lifetime (~a few times a day), shared across every agent process.
+//
+// Security posture: only the short-lived access token is cached, never the refresh
+// token, and the entry dies at the token's expiry (capped below). This mirrors the
+// no-ACL posture session-store.ts already accepts for held bundles.
+const CLAUDE_OAUTH_CACHE_PREFIX = 'agents-cli.claude-oauth-cache.';
+/** Hard cap so a token with a distant or absent `expiresAt` can't pin a stale entry. */
+const CLAUDE_OAUTH_CACHE_MAX_TTL_MS = 8 * 60 * 60 * 1000;
+/** The no-ACL cache item name for a Claude keychain service (hashed to stay tidy). */
+function claudeOauthCacheItem(service) {
+    const hash = createHash('sha256').update(service).digest('hex').slice(0, 16);
+    return `${CLAUDE_OAUTH_CACHE_PREFIX}${hash}`;
+}
+/** Whether the no-ACL cache is meaningful: macOS (where the source read prompts) or
+ * whenever a test keychain backend is installed, so the path is exercisable on CI.
+ * Off macOS in production the source read is prompt-free, so there is nothing to cache. */
+function claudeOauthCacheActive() {
+    return process.platform === 'darwin' || isKeychainBackendOverridden();
+}
+/** Read the cached access token (prompt-free). Null on miss, or when the cache entry
+ * or the token itself has expired — in which case the stale entry is dropped. */
+function readCachedClaudeOauth(service) {
+    try {
+        const entry = JSON.parse(getKeychainToken(claudeOauthCacheItem(service)));
+        if (!entry || typeof entry.accessToken !== 'string' || !entry.accessToken)
+            return null;
+        const now = Date.now();
+        const tokenExpired = typeof entry.expiresAt === 'number' && entry.expiresAt > 0 && now >= entry.expiresAt;
+        if (now >= entry.cacheExpiresAt || tokenExpired) {
+            try {
+                deleteKeychainToken(claudeOauthCacheItem(service));
+            }
+            catch {
+                /* best-effort eviction */
+            }
+            return null;
+        }
+        return {
+            accessToken: entry.accessToken,
+            refreshToken: null,
+            expiresAt: entry.expiresAt ?? null,
+            scopes: entry.scopes ?? null,
+            subscriptionType: entry.subscriptionType ?? null,
+            rateLimitTier: entry.rateLimitTier ?? null,
+            organizationUuid: entry.organizationUuid ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Populate the no-ACL cache after a real (prompting) source read. Best-effort — the
+ * cache is an optimization, so any failure just means the next read prompts again. */
+function writeCachedClaudeOauth(service, creds) {
+    if (!creds.accessToken)
+        return;
+    try {
+        const now = Date.now();
+        const cap = now + CLAUDE_OAUTH_CACHE_MAX_TTL_MS;
+        const tokenExp = typeof creds.expiresAt === 'number' && creds.expiresAt > now ? creds.expiresAt : cap;
+        const entry = {
+            accessToken: creds.accessToken,
+            expiresAt: creds.expiresAt ?? null,
+            scopes: creds.scopes ?? null,
+            subscriptionType: creds.subscriptionType ?? null,
+            rateLimitTier: creds.rateLimitTier ?? null,
+            organizationUuid: creds.organizationUuid ?? null,
+            cacheExpiresAt: Math.min(tokenExp, cap),
+        };
+        setKeychainToken(claudeOauthCacheItem(service), JSON.stringify(entry), { noAcl: true });
+    }
+    catch {
+        /* best-effort — cache is an optimization */
+    }
+}
+/** Evict the no-ACL cache so a source rotation or sign-out is reflected immediately. */
+function deleteCachedClaudeOauth(service) {
+    try {
+        deleteKeychainToken(claudeOauthCacheItem(service));
+    }
+    catch {
+        /* best-effort — cache is an optimization */
+    }
+}
 /**
  * Load a version home's Claude OAuth credential from the two stores Claude Code
  * uses, tried in order:
@@ -878,19 +1002,48 @@ function parseClaudeOauthPayload(raw) {
  * Without step 2 the live usage fetch got no token on Linux, so `agents view`
  * (run remotely over SSH by `--host`) rendered no usage bars even though the
  * account + plan — read from the plaintext `.claude.json` — showed fine.
+ *
+ * `opts.accessTokenCache` opts INTO the no-ACL access-token cache (the Touch ID
+ * storm fix, see the cache helpers above). It is OFF by default so every caller
+ * keeps the full ACL-read credential — the cached copy deliberately omits the
+ * refresh token, so callers that refresh (`isClaudeAuthValid` ->
+ * `getClaudeAccessToken`) or export the full blob (`readClaudeCredentialsBlob`
+ * for Rush Cloud dispatch) must NOT pass it. Only the read-only, high-frequency
+ * access-token-only consumers (the usage fetch and the auth-health probe) opt in.
  */
-export async function loadClaudeOauth(home) {
+export async function loadClaudeOauth(home, opts) {
     // The OS keychain/keyring step is macOS/Linux-only. Windows skips straight
     // to the .credentials.json fallback — the Claude CLI has no keychain
-    // integration there and stores its OAuth token in that file too.
-    if (process.platform === 'darwin' || process.platform === 'linux') {
+    // integration there and stores its OAuth token in that file too. An injected
+    // test backend is the exception: it makes the keychain path exercisable
+    // anywhere, so the platform check must yield to it exactly as the inner
+    // claudeOauthCacheActive() gate does — otherwise this whole block is dead on
+    // a Windows runner and the tests below it read an empty home.
+    if (process.platform === 'darwin' || process.platform === 'linux' || isKeychainBackendOverridden()) {
+        const service = getClaudeKeychainService(home);
+        // Serve the no-ACL cache first (opt-in, macOS/test only) so the ACL-gated read
+        // below — the one that pops Touch ID — happens at most once per token lifetime
+        // instead of on every usage refresh. Off unless the caller opts in, because the
+        // cached copy drops the refresh token (see the doc comment above).
+        const cacheActive = opts?.accessTokenCache === true && claudeOauthCacheActive();
+        if (cacheActive) {
+            const cached = readCachedClaudeOauth(service);
+            if (cached)
+                return cached;
+        }
         try {
-            const fromKeychain = parseClaudeOauthPayload(getKeychainToken(getClaudeKeychainService(home)));
-            if (fromKeychain)
+            const fromKeychain = parseClaudeOauthPayload(getKeychainToken(service));
+            if (fromKeychain) {
+                if (cacheActive)
+                    writeCachedClaudeOauth(service, fromKeychain);
                 return fromKeychain;
+            }
         }
         catch {
             // No keychain item, or no reachable keyring (headless Linux) — fall through.
+            // Evict any stale no-ACL cache so a sign-out/deletion isn't masked.
+            if (cacheActive)
+                deleteCachedClaudeOauth(service);
         }
     }
     const credsPath = path.join(home ?? os.homedir(), '.claude', '.credentials.json');
@@ -907,10 +1060,15 @@ export async function loadClaudeOauth(home) {
 /**
  * Save Claude OAuth credentials to the system keychain/keyring.
  * Reads the existing payload, merges the new OAuth fields, and writes back.
+ * Exported for regression tests; not part of the public command surface.
  */
-async function saveClaudeOauth(home, credentials) {
-    // Windows not yet supported
-    if (process.platform !== 'darwin' && process.platform !== 'linux') {
+export async function saveClaudeOauth(home, credentials) {
+    // Windows not yet supported. An injected test backend is the exception, for
+    // the same reason as the loadClaudeOauth guard above: it makes the keychain
+    // path exercisable anywhere, and without it this returns before the rotated
+    // credential is written OR the no-ACL cache is evicted — so a cached reader
+    // keeps serving the pre-rotation access token.
+    if (process.platform !== 'darwin' && process.platform !== 'linux' && !isKeychainBackendOverridden()) {
         return false;
     }
     try {
@@ -944,6 +1102,8 @@ async function saveClaudeOauth(home, credentials) {
             // Entry might not exist, ignore
         }
         setKeychainToken(service, payloadJson);
+        // A new credential rotation means any cached access token is stale.
+        deleteCachedClaudeOauth(service);
         return true;
     }
     catch {

package/dist/lib/versions.d.ts

@@ -216,6 +216,19 @@ export declare function getGlobalDefault(agent: AgentId): string | null;
  * Set the global default version for an agent.
  */
 export declare function setGlobalDefault(agent: AgentId, version: string | undefined): void;
+/**
+ * Get the preferred ISOLATED version for an agent — the copy a bare
+ * `agents run <agent>` falls back to when there is no global default.
+ */
+export declare function getIsolatedDefault(agent: AgentId): string | null;
+/**
+ * Set (or clear, with `undefined`) the preferred isolated version.
+ *
+ * Deliberately does NOT touch the launcher, the bare shim, the `~/.<agent>` config
+ * symlink or the global default — the five things `setDefaultVersion` does. This is
+ * a pointer inside the sandbox, so it stays inside the sandbox.
+ */
+export declare function setIsolatedDefault(agent: AgentId, version: string | undefined): void;
 /**
  * Mark an installed version as an isolated install (`agents add --isolated`).
  *
@@ -431,8 +444,15 @@ export declare function verifyInstalledBinaryLaunches(agent: AgentId, version: s
  * the exact failure this repairs. Agents with a global/native binary (grok,
  * droid) have no such tarball and are returned unchanged.
  */
-export declare function ensureAgentRunnable(agent: AgentId, version: string, log?: (message: string) => void): Promise<string | null>;
-export declare function healBrokenDefaultLaunches(log?: (m: string) => void): Promise<string[]>;
+export declare function ensureAgentRunnable(agent: AgentId, version: string, log?: (message: string) => void, opts?: {
+    allowDefaultSwitch?: boolean;
+}): Promise<string | null>;
+export declare function healBrokenDefaultLaunches(log?: (m: string) => void, opts?: {
+    allowDefaultSwitch?: boolean;
+}): Promise<{
+    repaired: string[];
+    unhealed: string[];
+}>;
 /** Outcome of syncing resources to a version home, keyed by resource type. */
 export interface SyncResult {
     commands: boolean;

package/dist/lib/versions.js

@@ -32,12 +32,12 @@ import { VERSION_RE, compareVersions } from './agent-spec/primitives.js';
 import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError, findInPath, isSelfUpdatingAgent } from './agents.js';
 import { discoverPermissionGroups, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from './permissions.js';
 import { parseMcpServerConfig, isProjectMcpTrusted } from './mcp.js';
-import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
+import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink, assertIsolationBoundary, } from './shims.js';
 import { importInstallScriptBinary } from './import.js';
 import { IS_WINDOWS, composeWin32CommandLine } from './platform/index.js';
 import { listInstalledSubagents } from './subagents.js';
 import { listInstalledWorkflows } from './workflows.js';
-import { pruneVersionHomeHookEntriesFromSettings } from './hooks.js';
+import { parseHookManifest, registerHooksToSettings, selectHookManifest, pruneVersionHomeHookEntriesFromSettings } from './hooks.js';
 import { supports, explainSkip } from './capabilities.js';
 import { discoverPlugins, marketplaceSpecForName } from './plugins.js';
 import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from './staleness/index.js';
@@ -1186,6 +1186,14 @@ export function getGlobalDefault(agent) {
  * Set the global default version for an agent.
  */
 export function setGlobalDefault(agent, version) {
+    // A global default is what owns the launcher and arms the self-heal `shadowing`
+    // check, so recording one for an isolated-only agent is the root of the original
+    // breach. Clearing is always allowed — `removeVersion` legitimately clears a
+    // default as the last non-isolated version goes away, which is the very moment
+    // an agent BECOMES isolated-only.
+    if (version !== undefined) {
+        assertIsolationBoundary(agent, 'set a global default');
+    }
     const meta = readMeta();
     if (!meta.agents) {
         meta.agents = {};
@@ -1199,6 +1207,34 @@ export function setGlobalDefault(agent, version) {
     }
     writeMeta(meta);
 }
+/**
+ * Get the preferred ISOLATED version for an agent — the copy a bare
+ * `agents run <agent>` falls back to when there is no global default.
+ */
+export function getIsolatedDefault(agent) {
+    const meta = readMeta();
+    return meta.isolatedAgents?.[agent] || null;
+}
+/**
+ * Set (or clear, with `undefined`) the preferred isolated version.
+ *
+ * Deliberately does NOT touch the launcher, the bare shim, the `~/.<agent>` config
+ * symlink or the global default — the five things `setDefaultVersion` does. This is
+ * a pointer inside the sandbox, so it stays inside the sandbox.
+ */
+export function setIsolatedDefault(agent, version) {
+    const meta = readMeta();
+    if (!meta.isolatedAgents) {
+        meta.isolatedAgents = {};
+    }
+    if (version === undefined) {
+        delete meta.isolatedAgents[agent];
+    }
+    else {
+        meta.isolatedAgents[agent] = version;
+    }
+    writeMeta(meta);
+}
 /**
  * Path to the sentinel file that marks a version as an isolated install.
  *
@@ -1784,6 +1820,13 @@ export function removeVersion(agent, version) {
             console.log(chalk.yellow(`Removed the last non-isolated ${agent} version and cleared its default. Reinstall with: agents add ${agent}, then set one with: agents use ${agent}@<version>`));
         }
     }
+    // Same for the isolated pointer: a removed version must not stay the answer to a
+    // bare `agents run <agent>`. Prefer the newest remaining isolated copy so removing
+    // one of several does not silently drop the user back to their PATH binary.
+    if (getIsolatedDefault(agent) === version) {
+        const survivors = listInstalledVersions(agent).filter((v) => isVersionIsolated(agent, v));
+        setIsolatedDefault(agent, survivors.length > 0 ? survivors[survivors.length - 1] : undefined);
+    }
     // Clean up dangling config symlink if it pointed to the removed version
     const symlinkVersion = getConfigSymlinkVersion(agent);
     if (symlinkVersion === version) {
@@ -1855,7 +1898,23 @@ export function resolveVersion(agent, projectPath) {
         }
     }
     // Fall back to global default
-    return getGlobalDefault(agent);
+    const globalDefault = getGlobalDefault(agent);
+    if (globalDefault)
+        return globalDefault;
+    // Last resort: the preferred isolated copy. Strictly a fallback — a global
+    // default always wins, so nothing changes for anyone who has one. Without this,
+    // an isolated-only user cannot reach their installs by bare name at all: the
+    // resolution chain ended here, so `agents run codex` fell through to whatever
+    // `codex` meant on PATH, and only `agents run codex@<version>` worked.
+    //
+    // The pointer is verified on read. It survives in agents.yaml across a trash +
+    // restore cycle, but a version removed for good would otherwise leave a dangling
+    // pin that resolves to a directory that is not there.
+    const isolated = getIsolatedDefault(agent);
+    if (isolated && isVersionInstalled(agent, isolated) && isVersionIsolated(agent, isolated)) {
+        return isolated;
+    }
+    return null;
 }
 /**
  * Normalize a user-supplied @version token across CLI subcommands.
@@ -2091,7 +2150,17 @@ export async function verifyInstalledBinaryLaunches(agent, version) {
  * the exact failure this repairs. Agents with a global/native binary (grok,
  * droid) have no such tarball and are returned unchanged.
  */
-export async function ensureAgentRunnable(agent, version, log) {
+export async function ensureAgentRunnable(agent, version, log, opts) {
+    // Whether this heal may REPOINT the global default (adopt another version, or
+    // install `latest` and pin it). Interactive callers (`agents run`, `agents
+    // add`) allow it. The daemon's unattended 6-hourly launch-health pass sets
+    // this false: a background pass that silently switches the default installs a
+    // fresh version home → a fresh, empty Claude credential scope (macOS keychain
+    // keyed off CLAUDE_CONFIG_DIR; Linux per-version token file), i.e. an
+    // "unprovoked logout" at a time uncorrelated with anything the user did. In
+    // refuse-mode we still repair the CURRENT default in place (no scope change),
+    // but never repoint — we return null so the caller can alert instead.
+    const allowDefaultSwitch = opts?.allowDefaultSwitch ?? true;
     const cfg = AGENTS[agent];
     if (!cfg?.npmPackage)
         return version;
@@ -2113,6 +2182,14 @@ export async function ensureAgentRunnable(agent, version, log) {
         log?.(`${cfg.name}@${version} is an isolated install and could not be repaired — leaving your default ${cfg.name} untouched.`);
         return null;
     }
+    // In-place repair failed → normally adopt another installed version and repoint
+    // the default. When default-switching is disallowed (unattended daemon pass),
+    // refuse: repointing would swap the live credential scope out from under the
+    // user with no signal. Surface it so the caller can notify.
+    if (!allowDefaultSwitch) {
+        log?.(`${cfg.name}@${version} won't launch and could not be repaired in place — NOT repointing your default ${cfg.name} unattended. Run \`agents use ${agent} <version>\` or \`agents add ${agent}@latest\` to choose one.`);
+        return null;
+    }
     // In-place repair failed → adopt another installed version that launches.
     // Isolated copies are excluded: they are deliberately not promotable.
     const others = listInstalledVersions(agent)
@@ -2162,14 +2239,18 @@ export async function ensureAgentRunnable(agent, version, log) {
  * `agents run` hits a raw ENOENT — the run-time heal (ensureAgentRunnable) only
  * fires once a run is already starting; this catches it in the background.
  *
- * Returns a label (`agent@broken→healed`) for each version actually repaired, so
- * the daemon can log/notify. A version that already launches costs one cheap
- * `--version` probe and is left untouched.
+ * Returns `{ repaired, unhealed }`: `repaired` is a label (`agent@broken→healed`)
+ * for each version actually fixed; `unhealed` is `agent@version` for each broken
+ * default that could not be fixed (including, under `allowDefaultSwitch:false`,
+ * one that was deliberately not repointed), so the daemon can log/notify. A
+ * version that already launches costs one cheap `--version` probe and is left
+ * untouched.
  */
 const failedRepairAt = new Map();
 const REPAIR_COOLDOWN_MS = 24 * 60 * 60_000;
-export async function healBrokenDefaultLaunches(log) {
+export async function healBrokenDefaultLaunches(log, opts) {
     const repaired = [];
+    const unhealed = [];
     for (const agent of Object.keys(AGENTS)) {
         if (!AGENTS[agent].npmPackage)
             continue; // native/global agents have no gutted-tarball failure mode
@@ -2189,16 +2270,17 @@ export async function healBrokenDefaultLaunches(log) {
             continue;
         }
         log?.(`${AGENTS[agent].name}@${version} won't launch — repairing…`);
-        const healed = await ensureAgentRunnable(agent, version, log);
+        const healed = await ensureAgentRunnable(agent, version, log, opts);
         if (healed) {
             failedRepairAt.delete(key);
             repaired.push(`${agent}@${version}${healed === version ? '' : `→${healed}`}`);
         }
         else {
             failedRepairAt.set(key, Date.now());
+            unhealed.push(key);
         }
     }
-    return repaired;
+    return { repaired, unhealed };
 }
 async function getCliVersionFromPath(agent) {
     const agentConfig = AGENTS[agent];
@@ -2581,6 +2663,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             const hooksToSync = selection
                 ? resolveSelection(selection.hooks, available.hooks)
                 : available.hooks;
+            let hookManifest = {};
             if (hooksToSync.length > 0) {
                 const r = hooksWriter.write({ version, versionHome, selection: hooksToSync, cwd });
                 // Remove orphan files from version home. The trusted set is the
@@ -2598,6 +2681,11 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                     }
                 }
                 result.hooks = r.synced.length > 0;
+                hookManifest = selectHookManifest(parseHookManifest(), hooksToSync);
+            }
+            const hooksInScope = !userPassedSelection || selection?.hooks !== undefined;
+            if (agent === 'opencode' && hooksInScope) {
+                registerHooksToSettings(agent, versionHome, hookManifest);
             }
         }
     }

package/dist/lib/watchdog/log.d.ts

@@ -0,0 +1,43 @@
+/** Same path the Factory reader pulls (apps/factory/src/core/watchdogLog.ts). */
+export declare const WATCHDOG_LOG_PATH: string;
+/** Kinds the Factory reader accepts. Keep in lockstep with watchdogLog.ts. */
+export type WatchdogEventKind = 'tick' | 'decision' | 'nudge' | 'rotate' | 'error';
+/** JSONL row shape — a verbatim replica of the Factory reader's WatchdogEvent. */
+export interface WatchdogEvent {
+    ts: number;
+    kind: WatchdogEventKind;
+    terminalId?: string;
+    agentType?: string;
+    message: string;
+    reason?: string;
+    /** For 'tick' events: the session lines the watchdog actually read. */
+    tailLines?: string[];
+    /** For 'tick' / 'decision' events: how long the terminal had been stalled. */
+    stalledForMs?: number;
+    /** Carried so the UI can show what the agent was stuck on. */
+    lastUserMessage?: string;
+    lastAssistantMessage?: string;
+    /** For a 'decision'/'nudge' that injects: the exact text delivered. */
+    nudgeText?: string;
+}
+/** Serialize one event to a JSONL line (no trailing newline). */
+export declare function formatEvent(ev: WatchdogEvent): string;
+/**
+ * Cap on retained log lines. Mirrors the Factory reader's expectation that the
+ * writer trims (watchdogLog.ts trimToLast). Large enough to keep a useful
+ * history, small enough to bound the file the UI polls.
+ */
+export declare const WATCHDOG_LOG_MAX_LINES = 2000;
+/** Trim a JSONL body to the last `maxLines` events (same logic as the reader). */
+export declare function trimToLast(text: string, maxLines: number): string;
+/**
+ * Append events to the log under a file lock, trimming to WATCHDOG_LOG_MAX_LINES
+ * so the file never grows unbounded. Concurrent watchdog ticks share the lock so
+ * their appends never interleave into a corrupt line. Best-effort: a filesystem
+ * error is swallowed (the Factory card tolerates a stale/missing log), never
+ * throwing into the tick.
+ */
+export declare function appendWatchdogEvents(events: WatchdogEvent[], opts?: {
+    logPath?: string;
+    maxLines?: number;
+}): void;

package/dist/lib/watchdog/log.js

@@ -0,0 +1,69 @@
+/**
+ * Canonical watchdog event log (watchdog-brain-v2).
+ *
+ * The Factory Floor renders a read-only "Watchdog activity" card from the JSONL
+ * feed at ~/.agents/.cache/logs/watchdog.log. That feed was historically written
+ * by the retired extension-side watchdog; now the always-on CLI watchdog owns it.
+ *
+ * The event SHAPE here is a deliberate, verbatim replica of the reader in
+ * apps/factory/src/core/watchdogLog.ts (WatchdogEvent / WatchdogEventKind /
+ * WATCHDOG_LOG_PATH / the trim cap). The repo forbids cross-app imports
+ * (CLAUDE.md repo map), so the two files are kept in sync by hand — a change to
+ * the Factory reader's shape must be mirrored here. There is no import between
+ * them.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { withFileLock, atomicWriteFileSync, ensureLockTarget } from '../fs-atomic.js';
+/** Same path the Factory reader pulls (apps/factory/src/core/watchdogLog.ts). */
+export const WATCHDOG_LOG_PATH = path.join(os.homedir(), '.agents', '.cache', 'logs', 'watchdog.log');
+/** Serialize one event to a JSONL line (no trailing newline). */
+export function formatEvent(ev) {
+    return JSON.stringify(ev);
+}
+/**
+ * Cap on retained log lines. Mirrors the Factory reader's expectation that the
+ * writer trims (watchdogLog.ts trimToLast). Large enough to keep a useful
+ * history, small enough to bound the file the UI polls.
+ */
+export const WATCHDOG_LOG_MAX_LINES = 2000;
+/** Trim a JSONL body to the last `maxLines` events (same logic as the reader). */
+export function trimToLast(text, maxLines) {
+    const lines = text.split('\n').filter((l) => l.trim().length > 0);
+    if (lines.length <= maxLines)
+        return lines.join('\n') + (lines.length ? '\n' : '');
+    return lines.slice(lines.length - maxLines).join('\n') + '\n';
+}
+/**
+ * Append events to the log under a file lock, trimming to WATCHDOG_LOG_MAX_LINES
+ * so the file never grows unbounded. Concurrent watchdog ticks share the lock so
+ * their appends never interleave into a corrupt line. Best-effort: a filesystem
+ * error is swallowed (the Factory card tolerates a stale/missing log), never
+ * throwing into the tick.
+ */
+export function appendWatchdogEvents(events, opts = {}) {
+    if (events.length === 0)
+        return;
+    const logPath = opts.logPath ?? WATCHDOG_LOG_PATH;
+    const maxLines = opts.maxLines ?? WATCHDOG_LOG_MAX_LINES;
+    const lockPath = path.join(path.dirname(logPath), '.watchdog.log.lock');
+    try {
+        ensureLockTarget(lockPath);
+        withFileLock(lockPath, () => {
+            let existing = '';
+            try {
+                existing = fs.readFileSync(logPath, 'utf8');
+            }
+            catch {
+                /* first write — no file yet */
+            }
+            const appended = events.map(formatEvent).join('\n') + '\n';
+            const body = trimToLast(existing + appended, maxLines);
+            atomicWriteFileSync(logPath, body);
+        });
+    }
+    catch {
+        /* best-effort: never let logging break a tick */
+    }
+}