@phnx-labs/agents-cli 1.22.84 → 1.22.85

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

@@ -60,6 +60,42 @@ export declare function listInstallationLabels(agent: AgentId): string[];
  * that disappears mid-scan is skipped rather than failing the whole listing.
  */
 export declare function listInstallations(agent: AgentId): Installation[];
+/**
+ * The label of the single managed installation every harness gets under the
+ * account model v2 (PHNX-3940). One managed install per harness per device;
+ * accounts live in credential slots beside it, and a second home is an expert
+ * `--isolated` copy, never another managed install.
+ */
+export declare const MANAGED_INSTALLATION_LABEL = "main";
+/**
+ * Resolve the ONE managed installation of a harness, or null when the harness
+ * has no managed install yet. The winner is deterministic: the `main` label
+ * first, then the recorded global default (the install the user actually
+ * launches), then the first remaining non-isolated installation by label.
+ * Isolated copies (`agents add --isolated`) never count — they are expert
+ * second homes, not the managed install.
+ */
+export declare function resolveManagedInstallation(agent: AgentId): Installation | null;
+export interface EnsureHarnessInstallationResult {
+    installation: Installation;
+    /** True when this call installed the harness just now; false when the managed installation already existed and was reused unchanged. */
+    installed: boolean;
+}
+/**
+ * The taught entry point for "make this harness runnable" (PHNX-3940): return
+ * the harness's single managed installation, installing the current release
+ * into the `main` label when the harness is not installed yet. `release` pins
+ * the fresh install to a concrete release (recorded as a pinned update policy
+ * by `installVersion`); it has no effect when an installation already exists —
+ * moving an existing install is `agents update <agent> --to <release>`'s job.
+ *
+ * Throws (fail loud) when the install fails; never returns a half-installed
+ * record.
+ */
+export declare function ensureHarnessInstallation(agent: AgentId, opts?: {
+    release?: string;
+    onProgress?: (message: string) => void;
+}): Promise<EnsureHarnessInstallationResult>;
 /**
  * Get the directory where a specific version is installed.
  */
@@ -154,6 +190,13 @@ export declare function pickCanonicalGlobalBinaryVersion(agent: AgentId, version
  * For a self-updating global-binary agent (droid) every version dir resolves to
  * the SAME binary, so this collapses them to a single canonical entry — one
  * install, one row in `agents view`, never the phantom set of semver dir names.
+ *
+ * A directory is an installation only when it has a working launch binary.
+ * Account credential slots (PHNX-3940, `~/.agents/.history/accounts/**`) are
+ * HOME-shaped dirs with no binary and no `installation.json`, so they can
+ * never appear here. Record-less pre-frozen installs are reported as-is; their
+ * migration belongs to the record-based paths (`listInstallations`), never to
+ * this read surface.
  */
 export declare function listInstalledVersions(agent: AgentId): string[];
 /**

package/dist/lib/installations/store.js

@@ -224,6 +224,62 @@ export function listInstallations(agent) {
     }
     return out;
 }
+/**
+ * The label of the single managed installation every harness gets under the
+ * account model v2 (PHNX-3940). One managed install per harness per device;
+ * accounts live in credential slots beside it, and a second home is an expert
+ * `--isolated` copy, never another managed install.
+ */
+export const MANAGED_INSTALLATION_LABEL = 'main';
+/**
+ * Resolve the ONE managed installation of a harness, or null when the harness
+ * has no managed install yet. The winner is deterministic: the `main` label
+ * first, then the recorded global default (the install the user actually
+ * launches), then the first remaining non-isolated installation by label.
+ * Isolated copies (`agents add --isolated`) never count — they are expert
+ * second homes, not the managed install.
+ */
+export function resolveManagedInstallation(agent) {
+    const managed = listInstallations(agent).filter((i) => !isVersionIsolated(agent, i.label));
+    if (managed.length === 0)
+        return null;
+    const main = managed.find((i) => i.label === MANAGED_INSTALLATION_LABEL);
+    if (main)
+        return main;
+    const globalDefault = getGlobalDefault(agent);
+    const def = globalDefault ? managed.find((i) => i.label === globalDefault) : undefined;
+    return def ?? managed[0];
+}
+/**
+ * The taught entry point for "make this harness runnable" (PHNX-3940): return
+ * the harness's single managed installation, installing the current release
+ * into the `main` label when the harness is not installed yet. `release` pins
+ * the fresh install to a concrete release (recorded as a pinned update policy
+ * by `installVersion`); it has no effect when an installation already exists —
+ * moving an existing install is `agents update <agent> --to <release>`'s job.
+ *
+ * Throws (fail loud) when the install fails; never returns a half-installed
+ * record.
+ */
+export async function ensureHarnessInstallation(agent, opts = {}) {
+    const existing = resolveManagedInstallation(agent);
+    if (existing)
+        return { installation: existing, installed: false };
+    const release = opts.release ?? 'latest';
+    // installVersion lives in ./versions.js, which imports this file. A dynamic
+    // import keeps the static module graph acyclic (see the docblock at the top
+    // of this file) while the call itself runs after both modules are loaded.
+    const { installVersion } = await import('./versions.js');
+    const result = await installVersion(agent, release, opts.onProgress, { installationLabel: MANAGED_INSTALLATION_LABEL });
+    if (!result.success) {
+        throw new Error(result.error || `Failed to install ${agent}@${release}.`);
+    }
+    const record = readInstallation(agent, MANAGED_INSTALLATION_LABEL);
+    if (!record) {
+        throw new Error(`Install of ${agent}@${release} reported success but left no installation record at ${MANAGED_INSTALLATION_LABEL}.`);
+    }
+    return { installation: record, installed: true };
+}
 /**
  * Get the directory where a specific version is installed.
  */
@@ -534,6 +590,13 @@ function collapseGlobalBinaryVersions(agent, versions) {
  * For a self-updating global-binary agent (droid) every version dir resolves to
  * the SAME binary, so this collapses them to a single canonical entry — one
  * install, one row in `agents view`, never the phantom set of semver dir names.
+ *
+ * A directory is an installation only when it has a working launch binary.
+ * Account credential slots (PHNX-3940, `~/.agents/.history/accounts/**`) are
+ * HOME-shaped dirs with no binary and no `installation.json`, so they can
+ * never appear here. Record-less pre-frozen installs are reported as-is; their
+ * migration belongs to the record-based paths (`listInstallations`), never to
+ * this read surface.
  */
 export function listInstalledVersions(agent) {
     const agentVersionsDir = path.join(getVersionsDir(), agent);
@@ -554,13 +617,18 @@ export function listInstalledVersions(agent) {
     const entries = fs.readdirSync(agentVersionsDir, { withFileTypes: true });
     const versions = [];
     for (const entry of entries) {
-        if (entry.isDirectory()) {
-            // Probe the real launch binary (isVersionInstalled), not just the
-            // node_modules/.bin wrapper — a gutted install must not count as healthy
-            // in the balanced account/version picker.
-            if (isVersionInstalled(agent, entry.name)) {
-                versions.push(entry.name);
-            }
+        if (!entry.isDirectory())
+            continue;
+        // Probe the real launch binary (isVersionInstalled), not just the
+        // node_modules/.bin wrapper — a gutted install must not count as healthy
+        // in the balanced account/version picker. A dir with no working binary
+        // (a slot, a partial download) is not an installation at all. Read-only:
+        // `agents view` enumerates through here and must leave every version home
+        // byte-identical (issue #2058), so a record-less pre-frozen install is
+        // reported as-is — its migration belongs to the record-based paths
+        // (listInstallations), never to a read surface.
+        if (isVersionInstalled(agent, entry.name)) {
+            versions.push(entry.name);
         }
     }
     versions.sort(compareVersions);

package/dist/lib/installations/versions.js

@@ -1044,7 +1044,7 @@ export async function installVersion(agent, version, onProgress, opts) {
         throw new Error(`Invalid version: ${JSON.stringify(version)}`);
     }
     // A caller-supplied installation label decouples the addressable version-dir
-    // name from the vendor release (PHNX-3940): `agents accounts connect` mints an
+    // name from the vendor release (PHNX-3940): `agents accounts add` mints an
     // opaque stable label so ten accounts can share the same upstream `latest`
     // under distinct isolated homes, each with its own native login. It follows
     // the same identity/release split the installScript branch already uses via

package/dist/lib/menubar/install-menubar.d.ts

@@ -1,9 +1,9 @@
 /**
  * Install + lifecycle for the macOS menu-bar helper (`MenubarHelper.app`).
  *
- * Mirrors `src/lib/secrets/install-helper.ts` (stable Application Support path,
- * survives npm re-sign) and the secrets-agent launchd pattern in
- * `src/lib/secrets/agent.ts` (RunAtLoad + KeepAlive user service).
+ * Mirrors the stable-Application-Support-path-survives-npm-re-sign pattern and
+ * a RunAtLoad + KeepAlive user service, the same shape the deleted embedded
+ * secrets-agent used before it moved to the standalone secrets-cli (PHNX-3989).
  *
  * The helper is a no-Dock `.accessory` status-bar app. It reads live agent
  * state directly from disk and shells `agents` only for actions, so the plist

package/dist/lib/menubar/install-menubar.js

@@ -1,9 +1,9 @@
 /**
  * Install + lifecycle for the macOS menu-bar helper (`MenubarHelper.app`).
  *
- * Mirrors `src/lib/secrets/install-helper.ts` (stable Application Support path,
- * survives npm re-sign) and the secrets-agent launchd pattern in
- * `src/lib/secrets/agent.ts` (RunAtLoad + KeepAlive user service).
+ * Mirrors the stable-Application-Support-path-survives-npm-re-sign pattern and
+ * a RunAtLoad + KeepAlive user service, the same shape the deleted embedded
+ * secrets-agent used before it moved to the standalone secrets-cli (PHNX-3989).
  *
  * The helper is a no-Dock `.accessory` status-bar app. It reads live agent
  * state directly from disk and shells `agents` only for actions, so the plist

package/dist/lib/native-accounts.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Native-account lookup leaf (PHNX-3940).
+ *
+ * A PURE, types-only module: it answers "which registered account is this
+ * email / what does its identity key decode to" from a `Meta` snapshot passed
+ * in by the caller — it never reads state, the keychain, or the network, and it
+ * imports nothing from `account-registry` (which imports the agent-spec engine).
+ * That import-graph constraint is load-bearing: `agent-spec/agents.ts`
+ * completes an email-only worker home from the registry row here, and importing
+ * `account-registry` there would be a cycle. `account-registry` re-exports both
+ * functions so existing callers keep one import site.
+ *
+ * The merge of central (`accounts.native`, `scope:'version'`) and device-scoped
+ * (`deviceAccounts.native`) rows mirrors `listNativeAccounts`, inlined so this
+ * module stays a leaf.
+ */
+import type { AgentId, Meta, NativeAccountRecord } from './types.js';
+/**
+ * The one native row for `agent` whose `identityLabel` (email) matches, or null.
+ *
+ * Returns null when zero OR several rows match — never guesses. Several rows can
+ * share one email (a Team seat AND a personal Max under the same address are two
+ * accounts, two orgs), and picking one would attribute a worker home to the
+ * wrong org. The read-side caller falls closed to email-only identity in that
+ * case, which is correct: an ambiguous identity is better left unresolved than
+ * resolved wrong.
+ */
+export declare function registeredNativeAccountForEmail(meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, agent: AgentId, email: string): NativeAccountRecord | null;
+/**
+ * Decode an `<agent>:<label>=<value>[:<label>=<value>…]` identity key into its
+ * parts, or null when it does not belong to `agent` or is malformed. The key
+ * shape is what `buildIdentityKey` in `agent-spec/agents.ts` writes — e.g.
+ * `claude:account=<uuid>:org=<uuid>` → `{ account, org }`.
+ */
+export declare function parseNativeIdentityKey(agent: AgentId, identityKey: string): Record<string, string> | null;

package/dist/lib/native-accounts.js

@@ -0,0 +1,41 @@
+/** Central + device-scoped native rows, device winning on a shared id. */
+function mergedNativeAccounts(meta) {
+    const merged = { ...meta.accounts?.native, ...meta.deviceAccounts?.native };
+    return Object.values(merged);
+}
+/**
+ * The one native row for `agent` whose `identityLabel` (email) matches, or null.
+ *
+ * Returns null when zero OR several rows match — never guesses. Several rows can
+ * share one email (a Team seat AND a personal Max under the same address are two
+ * accounts, two orgs), and picking one would attribute a worker home to the
+ * wrong org. The read-side caller falls closed to email-only identity in that
+ * case, which is correct: an ambiguous identity is better left unresolved than
+ * resolved wrong.
+ */
+export function registeredNativeAccountForEmail(meta, agent, email) {
+    const needle = email.trim().toLowerCase();
+    if (!needle)
+        return null;
+    const matches = mergedNativeAccounts(meta).filter((account) => account.agent === agent && account.identityLabel?.trim().toLowerCase() === needle);
+    return matches.length === 1 ? matches[0] : null;
+}
+/**
+ * Decode an `<agent>:<label>=<value>[:<label>=<value>…]` identity key into its
+ * parts, or null when it does not belong to `agent` or is malformed. The key
+ * shape is what `buildIdentityKey` in `agent-spec/agents.ts` writes — e.g.
+ * `claude:account=<uuid>:org=<uuid>` → `{ account, org }`.
+ */
+export function parseNativeIdentityKey(agent, identityKey) {
+    const prefix = `${agent}:`;
+    if (!identityKey.startsWith(prefix))
+        return null;
+    const parts = {};
+    for (const segment of identityKey.slice(prefix.length).split(':')) {
+        const eq = segment.indexOf('=');
+        if (eq < 1 || eq === segment.length - 1)
+            return null;
+        parts[segment.slice(0, eq)] = segment.slice(eq + 1);
+    }
+    return Object.keys(parts).length > 0 ? parts : null;
+}

package/dist/lib/net-close.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Bounded-close helper for a local `net.Server`. Generic — no secrets/engine
+ * dependency — so consumers that only needed it for that reason (the webhook
+ * receiver, the daemon's webhook service) no longer import `lib/secrets/*`.
+ */
+import type * as net from 'node:net';
+/**
+ * Close `server`, resolving once closed or after `timeoutMs`, whichever comes
+ * first — a shutdown must never hang on a client that never disconnects.
+ */
+export declare function closeServerBounded(server: net.Server, timeoutMs?: number): Promise<void>;

package/dist/lib/net-close.js

@@ -0,0 +1,25 @@
+const SERVER_CLOSE_TIMEOUT_MS = 5000;
+/**
+ * Close `server`, resolving once closed or after `timeoutMs`, whichever comes
+ * first — a shutdown must never hang on a client that never disconnects.
+ */
+export function closeServerBounded(server, timeoutMs = SERVER_CLOSE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(finish, timeoutMs);
+        try {
+            server.close(() => finish());
+        }
+        catch {
+            // Already closed / not listening — treat as released.
+            finish();
+        }
+    });
+}

package/dist/lib/openclaw-keychain.js

@@ -1,6 +1,32 @@
 import { execFileSync, spawnSync } from 'child_process';
 import { getCliLaunch } from './cli-entry.js';
-import { buildAddGenericPasswordArgs, buildAddGenericPasswordSpawnOptions, } from './secrets/index.js';
+/**
+ * argv for writing a bare (non-`agents-cli.`) keychain item via
+ * `/usr/bin/security add-generic-password`, deliberately WITHOUT the value: the
+ * secret travels over stdin (see below) so it never lands in argv or a `ps`
+ * snapshot. Pure — no agents-cli secrets engine involved (this migration writes
+ * directly to the OpenClaw account's OWN macOS keychain entries, bypassing the
+ * `agents secrets` bundle store entirely), so it's a local helper rather than a
+ * process-client call.
+ */
+function buildAddGenericPasswordArgs(account, item) {
+    return ['add-generic-password', '-U', '-a', account, '-s', item, '-w'];
+}
+/**
+ * spawnSync options for the bare `-w` keychain write. `input` pipes the value
+ * TWICE (bare `-w` prompts enter+confirm; one line fails the confirm and stores
+ * an empty secret). `detached: true` runs `security` in a new session with no
+ * controlling terminal, so readpassphrase(3) falls back to our piped stdin
+ * instead of prompting the user's `/dev/tty` in an interactive shell.
+ */
+function buildAddGenericPasswordSpawnOptions(value) {
+    return {
+        input: `${value}\n${value}\n`,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 10_000,
+        detached: true,
+    };
+}
 export const OPENCLAW_KEYCHAIN_ACCOUNT = 'openclaw';
 export const OPENCLAW_KEYCHAIN_PROVIDER = 'agents_keychain';
 export const OPENCLAW_KEYCHAIN_ENV_SERVICES = {

package/dist/lib/profiles.js

@@ -11,7 +11,7 @@ import * as crypto from 'node:crypto';
 import * as yaml from 'yaml';
 import { ALL_AGENT_IDS } from './agents.js';
 import { getUserAgentsDir } from './state.js';
-import { deleteKeychainToken, getKeychainToken, hasKeychainToken, keychainItemName } from './secrets/profiles.js';
+import { deleteKeychainTokenSync, getKeychainTokenSync, hasKeychainTokenSync, isSecretsClientError, profileKeychainItem } from './secrets-client.js';
 import { getPreset } from './profiles-presets.js';
 import { MODEL_TIERS, isTierToken } from './model-tiers.js';
 import { addAccount, findAccount, resolveCredentialAccount } from './account-registry.js';
@@ -85,7 +85,7 @@ function migrateLegacyProfileAuth(profile, file) {
     const accountName = `legacy-${profile.provider}-${suffix}`;
     if (!findAccount(accountName)) {
         const kind = profile.auth.envVar.includes('BEARER_TOKEN') ? 'bearer-token' : 'api-key';
-        addAccount(accountName, provider, kind, getKeychainToken(profile.auth.keychainItem));
+        addAccount(accountName, provider, kind, getKeychainTokenSync(profile.auth.keychainItem));
     }
     const migratedAccount = findAccount(accountName);
     const oldItem = profile.auth.keychainItem;
@@ -110,7 +110,7 @@ function migrateLegacyProfileAuth(profile, file) {
         }
     });
     if (!stillReferenced)
-        deleteKeychainToken(oldItem);
+        deleteKeychainTokenSync(oldItem);
 }
 /** Write a profile to disk atomically (write-to-tmp then rename). */
 export function writeProfile(profile) {
@@ -250,7 +250,7 @@ export function profileAuthLabel(profile) {
         return `${provider} ${maskToken(token)}`;
     }
     if (profile.auth) {
-        return `${provider} ${hasKeychainToken(profile.auth.keychainItem) ? 'stored' : 'missing'}`;
+        return `${provider} ${hasKeychainTokenSync(profile.auth.keychainItem) ? 'stored' : 'missing'}`;
     }
     return provider;
 }
@@ -324,7 +324,7 @@ export function profileFromPreset(profileName, preset, version) {
         env: { ...preset.env },
         auth: {
             envVar: preset.authEnvVar,
-            keychainItem: keychainItemName(preset.provider),
+            keychainItem: profileKeychainItem(preset.provider),
         },
         authOptional: preset.authOptional,
         description: preset.description,
@@ -392,7 +392,7 @@ export function profileFromHostModel(name, host, model, opts = {}) {
         forkedFrom: host,
     };
     if (opts.provider && opts.authEnvVar) {
-        profile.auth = { envVar: opts.authEnvVar, keychainItem: keychainItemName(opts.provider) };
+        profile.auth = { envVar: opts.authEnvVar, keychainItem: profileKeychainItem(opts.provider) };
         profile.authOptional = false;
     }
     return profile;
@@ -455,7 +455,7 @@ export function forkProfile(source, name, opts = {}) {
             throw new Error(`Host '${host}' has no known auth env var; --provider cannot be attached to this fork.`);
         }
         forked.provider = opts.provider;
-        forked.auth = { envVar, keychainItem: keychainItemName(opts.provider) };
+        forked.auth = { envVar, keychainItem: profileKeychainItem(opts.provider) };
         forked.authOptional = source.authOptional ?? false;
     }
     return forked;
@@ -529,10 +529,23 @@ export function resolveProfileEnv(profile) {
         // Optional auth (host manages its own login) with no stored token: inject
         // nothing and let the host use its own credentials. Only required auth
         // hard-fails on a missing keychain item.
-        if (profile.authOptional && !hasKeychainToken(profile.auth.keychainItem)) {
+        if (profile.authOptional && !hasKeychainTokenSync(profile.auth.keychainItem)) {
             return env;
         }
-        const token = getKeychainToken(profile.auth.keychainItem);
+        let token;
+        try {
+            token = getKeychainTokenSync(profile.auth.keychainItem);
+        }
+        catch (err) {
+            // The standalone deliberately reports only a code, so name the item and
+            // the repair here — a bare `NOT_FOUND` gives the user nothing to act on.
+            if (!isSecretsClientError(err, 'NOT_FOUND'))
+                throw err;
+            throw new Error(`Harness '${profile.name}' needs a ${profile.provider ?? 'provider'} key, but its keychain item ` +
+                `'${profile.auth.keychainItem}' is missing on this device. Store one with ` +
+                `'agents harness edit ${profile.name} --auth-provider ${profile.provider ?? '<provider>'}' ` +
+                `(or --from-secrets <bundle>:<key>), or bind an account with 'agents harness edit ${profile.name} --account <name>'.`);
+        }
         env[profile.auth.envVar] = token;
     }
     return env;

package/dist/lib/project-resources.js

@@ -9,7 +9,7 @@ import { markdownToToml } from './convert.js';
 import { safeJoin } from './paths.js';
 import { subagentTarget } from './subagents-registry.js';
 import { parseSubagentFrontmatter } from './subagents.js';
-import { syncWorkflowToVersion } from './workflows.js';
+import { syncWorkflowToVersion } from './workflows-registry.js';
 const MANIFEST_FILE = '.agents-managed.json';
 const MANIFEST_VERSION = 1;
 const COPY_IGNORE = new Set(['.DS_Store', '.git', '.gitignore', '.venv', '__pycache__', 'node_modules']);

package/dist/lib/reserved-stores.d.ts

@@ -0,0 +1,53 @@
+import type { SecretsBackend } from './secrets-types.js';
+import { type AgentId } from './types.js';
+/** Legacy readable alias for `__claude__`. Not migrated in this track. */
+export declare const AUTH_STORE_ALIAS = "auth";
+/** The one reserved bundle name most callers actually need. */
+export declare const AUTH_BUNDLE_NAME = "auth";
+/**
+ * The reserved `auth` bundle holds per-account Claude setup-tokens for
+ * unattended usage/probe and MUST be file-backed (headless, fleet-shareable —
+ * credential-management.md invariant 7). The standalone enforces the same
+ * rule on its write path (`WRONG_BACKEND`); agents-cli asserts it on every
+ * read so a keychain/vault-backed `auth` left over from an older layout fails
+ * loud instead of silently being ignored by usage/probe (SEC-GAP-3).
+ */
+export declare const AUTH_BUNDLE_BACKEND: SecretsBackend;
+export declare const RESERVED_BUNDLE_NAMES: Set<string>;
+export declare function isReservedBundleName(name: string): boolean;
+/** Thrown when the reserved `auth` bundle is found on the wrong backend. */
+export declare class ReservedBundleWrongBackendError extends Error {
+    readonly bundle: string;
+    readonly backend: SecretsBackend;
+    constructor(bundle: string, backend: SecretsBackend);
+}
+/** Fail loud when the reserved `auth` bundle is on any backend but `file`. */
+export declare function assertReservedAuthBackend(backend: SecretsBackend): void;
+/**
+ * True for the wrong-backend refusal in either shape: raised here from a
+ * read-side check, or returned by the standalone (`WRONG_BACKEND`) when its
+ * own write/resolve guard fired.
+ */
+export declare function isReservedBundleBackendError(error: unknown): boolean;
+export declare const RESERVED_STORES: Record<AgentId, string>;
+export declare function reservedStoreName(harness: AgentId): string;
+export declare function isReservedStoreName(name: string): boolean;
+export type StorableCredentialKind = 'setup-token' | 'api-key';
+/**
+ * Fail loud at the write boundary: only a setup-token or an API key may enter
+ * a reserved store. Rotating OAuth/session credentials stay in their slot on
+ * the device that minted them.
+ */
+export declare function assertStorableCredentialKind(kind: string, harness?: AgentId): asserts kind is StorableCredentialKind;
+/**
+ * Whether the local reserved `auth` bundle exists and is on the expected
+ * (file) backend. `ok: true` on a missing bundle — nothing to be wrong about.
+ * Read-only status probe (`agents doctor`, `agents fleet apply`); an
+ * unreachable standalone is treated the same as "bundle absent" so a
+ * diagnostic never crashes over one optional finding.
+ */
+export declare function inspectReservedAuthBundle(): {
+    exists: boolean;
+    backend: SecretsBackend | null;
+    ok: boolean;
+};

package/dist/lib/reserved-stores.js

@@ -0,0 +1,120 @@
+/**
+ * Reserved per-harness credential stores (PHNX-3940 / PHNX-3989).
+ *
+ * One store name per `ALL_AGENT_IDS` entry: `__<harness>__`. A user-created
+ * bundle can never collide (the standalone rejects `__`-prefixed names unless
+ * explicitly allowed). The legacy `auth` bundle remains a readable alias for
+ * `__claude__` — this module does not migrate data.
+ *
+ * Deliberately a LEAF module (no import of `claude-account-token.ts` or
+ * `secrets-policy.ts`): both of those need these constants, and
+ * `claude-account-token.ts` is itself a dependency of `secrets-policy.ts`'s
+ * fleet-sync helpers — importing this module's exports from `secrets-policy.js`
+ * instead would form a real circular import that throws
+ * `ReferenceError: Cannot access '...' before initialization` under real ESM
+ * evaluation order (reproduced running this suite outside vitest's
+ * mock-tolerant transform). Keep it a leaf; `secrets-policy.ts` re-exports it
+ * for the existing public surface.
+ */
+import { bundleExistsSync, bundleBackendSync, isSecretsClientError } from './secrets-client.js';
+import { AGENT_IDS } from './types.js';
+/** Legacy readable alias for `__claude__`. Not migrated in this track. */
+export const AUTH_STORE_ALIAS = 'auth';
+/** The one reserved bundle name most callers actually need. */
+export const AUTH_BUNDLE_NAME = AUTH_STORE_ALIAS;
+/**
+ * The reserved `auth` bundle holds per-account Claude setup-tokens for
+ * unattended usage/probe and MUST be file-backed (headless, fleet-shareable —
+ * credential-management.md invariant 7). The standalone enforces the same
+ * rule on its write path (`WRONG_BACKEND`); agents-cli asserts it on every
+ * read so a keychain/vault-backed `auth` left over from an older layout fails
+ * loud instead of silently being ignored by usage/probe (SEC-GAP-3).
+ */
+export const AUTH_BUNDLE_BACKEND = 'file';
+export const RESERVED_BUNDLE_NAMES = new Set([AUTH_BUNDLE_NAME]);
+export function isReservedBundleName(name) {
+    return RESERVED_BUNDLE_NAMES.has(name.trim().toLowerCase());
+}
+/** Thrown when the reserved `auth` bundle is found on the wrong backend. */
+export class ReservedBundleWrongBackendError extends Error {
+    bundle;
+    backend;
+    constructor(bundle, backend) {
+        super(`Bundle '${bundle}' is reserved for file-backed setup-tokens (headless, fleet-shareable). ` +
+            `A ${backend}-backed '${bundle}' bundle is ignored by usage/probe instead of authenticating. ` +
+            `Recreate it as file-backed: agents secrets delete ${bundle} --yes && agents secrets create ${bundle} --backend file`);
+        this.name = 'ReservedBundleWrongBackendError';
+        this.bundle = bundle;
+        this.backend = backend;
+    }
+}
+/** Fail loud when the reserved `auth` bundle is on any backend but `file`. */
+export function assertReservedAuthBackend(backend) {
+    if (backend !== AUTH_BUNDLE_BACKEND)
+        throw new ReservedBundleWrongBackendError(AUTH_STORE_ALIAS, backend);
+}
+/**
+ * True for the wrong-backend refusal in either shape: raised here from a
+ * read-side check, or returned by the standalone (`WRONG_BACKEND`) when its
+ * own write/resolve guard fired.
+ */
+export function isReservedBundleBackendError(error) {
+    return error instanceof ReservedBundleWrongBackendError || isSecretsClientError(error, 'WRONG_BACKEND');
+}
+export const RESERVED_STORES = Object.fromEntries(AGENT_IDS.map((id) => [id, `__${id}__`]));
+export function reservedStoreName(harness) {
+    const name = RESERVED_STORES[harness];
+    if (!name)
+        throw new Error(`No reserved store for '${harness}'.`);
+    return name;
+}
+export function isReservedStoreName(name) {
+    const n = name.trim().toLowerCase();
+    if (n === AUTH_STORE_ALIAS)
+        return true;
+    return AGENT_IDS.some((id) => RESERVED_STORES[id].toLowerCase() === n);
+}
+/**
+ * Fail loud at the write boundary: only a setup-token or an API key may enter
+ * a reserved store. Rotating OAuth/session credentials stay in their slot on
+ * the device that minted them.
+ */
+export function assertStorableCredentialKind(kind, harness) {
+    if (kind === 'setup-token' || kind === 'api-key')
+        return;
+    throw new Error(storableCredentialRefusal(kind, harness));
+}
+function storableCredentialRefusal(kind, harness) {
+    if (harness === 'codex')
+        return 'codex: auth.json is a rotating session; add an API key instead';
+    if (harness === 'droid')
+        return 'droid: refresh tokens are single-use and collapse the fleet when copied; add a FACTORY_API_KEY instead';
+    if (harness === 'claude')
+        return 'claude: native OAuth (.credentials.json) is a rotating session; mint a setup-token instead';
+    if (harness === 'grok')
+        return 'grok: auth.json is a rotating session; add an XAI_API_KEY instead';
+    if (harness === 'kimi' || harness === 'antigravity')
+        return `${harness}: no portable worker credential; log in per device`;
+    const who = harness ?? 'this harness';
+    return `${who}: reserved stores accept only a setup-token or an API key, not '${kind}'`;
+}
+/**
+ * Whether the local reserved `auth` bundle exists and is on the expected
+ * (file) backend. `ok: true` on a missing bundle — nothing to be wrong about.
+ * Read-only status probe (`agents doctor`, `agents fleet apply`); an
+ * unreachable standalone is treated the same as "bundle absent" so a
+ * diagnostic never crashes over one optional finding.
+ */
+export function inspectReservedAuthBundle() {
+    let exists;
+    try {
+        exists = bundleExistsSync(AUTH_BUNDLE_NAME);
+    }
+    catch {
+        return { exists: false, backend: null, ok: true };
+    }
+    if (!exists)
+        return { exists: false, backend: null, ok: true };
+    const backend = bundleBackendSync(AUTH_BUNDLE_NAME);
+    return { exists: true, backend, ok: backend === AUTH_BUNDLE_BACKEND };
+}