@phnx-labs/agents-cli 1.22.84 → 1.22.86

package/dist/lib/installations/shims.js

@@ -10,6 +10,7 @@ import { IS_WINDOWS, prependToWindowsUserPath } from '../platform/index.js';
 import { getShimsDir, getVersionsDir, getBackupsDir, getHistoryDir, ensureAgentsDir } from '../state.js';
 export { getShimsDir };
 import { AGENTS, agentConfigDirName, readAuthAccountIdentity } from '../agents.js';
+import { acquireAuthOperationLock } from '../accounts/auth-operation-lock.js';
 import { codexHomeShimBash } from '../codex-home.js';
 import { resolveHarnessAdapter } from '../harness/index.js';
 import { randomUUID } from 'node:crypto';
@@ -1130,6 +1131,74 @@ export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'cursor
 export function supportsIsolatedInstall(agent) {
     return CONFIG_ENV_ISOLATED_AGENTS.includes(agent);
 }
+/**
+ * Harnesses that isolate by symlink-adopting `~/.<config>` rather than a
+ * config-dir env (PHNX-3940 T5). One active slot per device; `accounts default`
+ * repoints the adopted symlink under the auth-op lock.
+ */
+export function isSymlinkAdoptedHarness(agent) {
+    return !CONFIG_ENV_ISOLATED_AGENTS.includes(agent);
+}
+/**
+ * Repoint this harness's adopted `~/.<config>` symlink at `home`'s config dir.
+ * No-op for env-isolated harnesses. Fails loud when the adopted path is a real
+ * directory rather than a symlink — adopting that is `agents use`, not default.
+ */
+export function repointAdoptedConfigToHome(agent, home) {
+    if (!isSymlinkAdoptedHarness(agent))
+        return { success: true };
+    const lock = acquireAuthOperationLock(agent);
+    try {
+        lock.assertHeld();
+        const configPath = getAgentConfigPath(agent);
+        const configDirName = path.relative(os.homedir(), AGENTS[agent].configDir);
+        const target = path.join(home, configDirName);
+        fs.mkdirSync(target, { recursive: true });
+        try {
+            const stat = fs.lstatSync(configPath);
+            if (stat.isSymbolicLink()) {
+                const current = path.resolve(path.dirname(configPath), fs.readlinkSync(configPath));
+                if (current === path.resolve(target))
+                    return { success: true };
+            }
+            else {
+                return {
+                    success: false,
+                    error: `${configPath} is not a symlink; refusing to replace a real config directory. `
+                        + `Run \`agents use ${agent}\` once to adopt it, then \`agents accounts default ${agent}\`.`,
+                };
+            }
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        // Atomic retarget: create temp symlink, rename over existing (same pattern
+        // as switchHomeFileSymlinks). A window of "path missing" would let a
+        // harness process observe neither the old nor the new target.
+        const tmpPath = `${configPath}.agents-tmp-${process.pid}`;
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch { /* leftover from a killed prior swap */ }
+        try {
+            fs.symlinkSync(target, tmpPath, process.platform === 'win32' ? 'junction' : undefined);
+            fs.renameSync(tmpPath, configPath);
+        }
+        catch (err) {
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch { /* rename may have already consumed it */ }
+            throw err;
+        }
+        return { success: true };
+    }
+    finally {
+        lock.release();
+    }
+}
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary
@@ -2096,13 +2165,25 @@ export function listShimFileNames() {
         return [];
     }
 }
+/**
+ * Legacy command shims that are wrong even when their baked install is alive.
+ * `secrets`: the shim `exec`s `agents secrets`, which since PHNX-3989 is a
+ * passthrough to the STANDALONE `secrets` binary — so a `secrets` shim that
+ * re-enters `agents secrets` is a recursion, never a working command. It sits
+ * first on PATH and shadows the real `@phnx-labs/secrets-cli` bin, so it is
+ * pruned unconditionally (the liveness check below is what kept it alive across
+ * every in-place upgrade from 1.22.84).
+ */
+const LEGACY_SHIMS_ALWAYS_PRUNED = new Set(['secrets']);
 /**
  * Prune a stale, orphaned shim: one that is NOT a managed agent shim and NOT a user
  * alias, whose baked `AGENTS_BIN` points at an install that no longer exists. These
- * are legacy `exec "$AGENTS_BIN" <cmd>` command shims (browser/secrets/sessions/…)
- * left behind by a removed install — the current source never generates them, and
- * they either die with `exit 127` or shadow the real package bin on PATH. Only
- * removed when the baked target is gone, so a working shim is never touched.
+ * are `exec "$AGENTS_BIN" <cmd>` command shims (browser/sessions/pty/teams) that
+ * `scripts/postinstall.js` writes for the LIVE install; one baked at a removed
+ * install either dies with `exit 127` or shadows the real package bin on PATH.
+ * Only removed when the baked target is gone, so a working shim is never touched —
+ * except the `LEGACY_SHIMS_ALWAYS_PRUNED` set, which cannot work at all (and which
+ * postinstall no longer writes).
  * Returns true if removed.
  */
 export function pruneOrphanedCommandShim(fileName) {
@@ -2123,7 +2204,7 @@ export function pruneOrphanedCommandShim(fileName) {
     const bin = readAgentsBinFromShim(shimPath);
     if (!bin)
         return false; // not an AGENTS_BIN-baked shim
-    if (fs.existsSync(bin))
+    if (fs.existsSync(bin) && !LEGACY_SHIMS_ALWAYS_PRUNED.has(fileName))
         return false; // its install is still alive — leave it
     try {
         fs.rmSync(shimPath);

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;
+};