@phnx-labs/agents-cli 1.22.0 → 1.22.3

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

@@ -22,6 +22,7 @@ import * as path from 'path';
 import { sleepSync } from '../fs-atomic.js';
 import { getRuntimeStateDir, getHelpersDir } from '../state.js';
 import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../version.js';
+import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 const SERVICE_LABEL = 'com.phnx-labs.agents-menubar';
@@ -154,17 +155,6 @@ function resolveCliEntry() {
     }
     return null;
 }
-function copyAppBundle(src, dest) {
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    if (fs.existsSync(dest))
-        fs.rmSync(dest, { recursive: true, force: true });
-    // `cp -R` preserves the bundle's signature and resource forks (see install-helper.ts).
-    const r = spawnSync('cp', ['-R', src, dest], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
-    if (r.status !== 0) {
-        const msg = (r.stderr || r.stdout || '').toString().trim();
-        throw new Error(`Failed to copy ${src} -> ${dest}: ${msg || 'unknown error'}`);
-    }
-}
 /**
  * Register the freshly-installed bundle with LaunchServices.
  *
@@ -232,18 +222,32 @@ export function ensureMenubarAppInstalled(opts = {}) {
     if (!src)
         return null;
     const dest = installedAppPath();
-    if (!opts.forceReinstall && fs.existsSync(dest)) {
-        const sourceIsDevId = hasDeveloperIdSignature(src);
-        const destIsDevId = hasDeveloperIdSignature(dest);
-        if (!(sourceIsDevId && !destIsDevId)) {
-            return installedExecutablePath();
-        }
-    }
-    copyAppBundle(src, dest);
-    // A fresh copy is exactly when the bundle's icon can be new (first install) or
-    // superseded (upgrade) — register it so LaunchServices knows the bundle and can
-    // resolve its AppIcon for the left-hand slot of daemon notifications.
-    refreshBundleIconRegistration(dest);
+    // Heal an older install that was ad-hoc re-signed over a Developer ID source:
+    // that unstable identity made Accessibility re-prompt on every upgrade.
+    const needsInstall = () => {
+        if (opts.forceReinstall)
+            return true;
+        if (!fs.existsSync(dest))
+            return true;
+        return hasDeveloperIdSignature(src) && !hasDeveloperIdSignature(dest);
+    };
+    // Fast path: nothing to do.
+    if (!needsInstall())
+        return installedExecutablePath();
+    // Serialize the atomic install so concurrent `agents` invocations (this runs
+    // on the darwin startup path) don't race the swap or each re-copy — the
+    // stampede that transiently corrupted MenubarHelper.app and tripped the
+    // "damaged" dialog.
+    withInstallLock(dest, (heartbeat) => {
+        if (!needsInstall())
+            return;
+        copyAppBundle(src, dest);
+        heartbeat(); // cp -R done; keep the lock fresh across lsregister
+        // A fresh copy is exactly when the bundle's icon can be new (first install) or
+        // superseded (upgrade) — register it so LaunchServices knows the bundle and can
+        // resolve its AppIcon for the left-hand slot of daemon notifications.
+        refreshBundleIconRegistration(dest);
+    });
     return installedExecutablePath();
 }
 function xmlEscape(s) {

package/dist/lib/project-status.d.ts

@@ -54,6 +54,13 @@ export interface ProjectSessionRollup {
  * with the full definition list to show zero-agent projects.
  */
 export declare function rollupSessionsByProject(defs: ProjectDef[], sessions: ActiveSession[]): Map<string, ProjectSessionRollup>;
+/**
+ * True when a session's status means it is over. Exported so the card can keep
+ * the `agents` roster to live sessions: the headline and the `dead` row already
+ * separate the two, and a roster that reads `crashed ×25` beside `23 live`
+ * makes the reader distrust both numbers.
+ */
+export declare function isDeadStatus(status: string): boolean;
 /** Live vs finished sessions on a project. */
 export interface LiveDeadSplit {
     live: number;

package/dist/lib/project-status.js

@@ -93,6 +93,15 @@ export function rollupSessionsByProject(defs, sessions) {
  * that are running unattended.
  */
 const DEAD_STATUSES = new Set(['closed', 'crashed']);
+/**
+ * True when a session's status means it is over. Exported so the card can keep
+ * the `agents` roster to live sessions: the headline and the `dead` row already
+ * separate the two, and a roster that reads `crashed ×25` beside `23 live`
+ * makes the reader distrust both numbers.
+ */
+export function isDeadStatus(status) {
+    return DEAD_STATUSES.has(status);
+}
 /**
  * Split a rollup's sessions into what is working and what is wreckage.
  *

package/dist/lib/projects.d.ts

@@ -5,8 +5,17 @@
  * directory by pure convention (`<projectRoot>/<slug>`, see `project-root.ts`).
  * This module adds editable definitions on top: one YAML file per project under
  * `~/.agents/projects/<name>.yaml`, sitting beside the existing `routines/`,
- * `monitors/`, and `teams/` dirs in the user repo (so definitions sync across
- * machines for free via `agents push/pull`). A defined project can name itself
+ * `monitors/`, and `teams/` dirs in the user repo.
+ *
+ * That location makes definitions SYNCABLE, not automatically synced: they ride
+ * the user repo only once they are committed to it, via `agents repo push user`
+ * (`agents push` was removed). Until then the directory is untracked, and a
+ * reconcile that cleans the working tree deletes it — observed twice on one
+ * machine, taking four definitions with it each time. The recovery is an
+ * orphaned `chore(local): save …-sync drift` commit, which is not a guarantee:
+ * unreachable objects are collected. Say "commit them" rather than "for free".
+ *
+ * A defined project can name itself
  * independently of its folder, bind more than one repo, pin a monorepo subpath,
  * describe context subdirectories an agent should start from, carry a Linear
  * link and external integrations, and set an explicit default path.
@@ -42,6 +51,19 @@ export interface ProjectContext {
     /** One line on how this subtree relates to the project. */
     purpose: string;
 }
+/**
+ * A project goal — the OKR-shaped "why". A project serves one or more goals: a
+ * qualitative `objective` ("Ship agents-cli 2.0") and an optional `measure`, the
+ * key result that says whether it's landing ("fleet on 2.x", "p95 < 200ms"). The
+ * goal is the outcome the work is chasing; milestones (dated checkpoints, pulled
+ * from Linear) and live work (agents / PRs / artifacts) are how far along it is.
+ */
+export interface ProjectGoal {
+    /** The outcome, in a line. */
+    objective: string;
+    /** Optional key result — how success is measured. */
+    measure?: string;
+}
 /** An external context source hung off the project (surfaced in `projects show`). */
 export interface ProjectIntegration {
     /** e.g. `gdrive`, `notion`, `figma`, `url`. */
@@ -64,6 +86,8 @@ export interface ProjectDef {
     repos?: ProjectRepo[];
     /** Described starting points inside the project. */
     contexts?: ProjectContext[];
+    /** The outcomes this project serves (OKR-shaped); a project may have several. */
+    goals?: ProjectGoal[];
     /** External context sources (Drive, docs, …). */
     integrations?: ProjectIntegration[];
     /** Linear project link — reuses the existing GraphQL path. */

package/dist/lib/projects.js

@@ -5,8 +5,17 @@
  * directory by pure convention (`<projectRoot>/<slug>`, see `project-root.ts`).
  * This module adds editable definitions on top: one YAML file per project under
  * `~/.agents/projects/<name>.yaml`, sitting beside the existing `routines/`,
- * `monitors/`, and `teams/` dirs in the user repo (so definitions sync across
- * machines for free via `agents push/pull`). A defined project can name itself
+ * `monitors/`, and `teams/` dirs in the user repo.
+ *
+ * That location makes definitions SYNCABLE, not automatically synced: they ride
+ * the user repo only once they are committed to it, via `agents repo push user`
+ * (`agents push` was removed). Until then the directory is untracked, and a
+ * reconcile that cleans the working tree deletes it — observed twice on one
+ * machine, taking four definitions with it each time. The recovery is an
+ * orphaned `chore(local): save …-sync drift` commit, which is not a guarantee:
+ * unreachable objects are collected. Say "commit them" rather than "for free".
+ *
+ * A defined project can name itself
  * independently of its folder, bind more than one repo, pin a monorepo subpath,
  * describe context subdirectories an agent should start from, carry a Linear
  * link and external integrations, and set an explicit default path.
@@ -112,6 +121,18 @@ export function validateProjectDef(raw, sourceName) {
             return [];
         });
     }
+    if (Array.isArray(o.goals)) {
+        def.goals = o.goals.flatMap((g) => {
+            if (g && typeof g === 'object' && typeof g.objective === 'string') {
+                const gg = g;
+                const goal = { objective: gg.objective };
+                if (typeof gg.measure === 'string')
+                    goal.measure = gg.measure;
+                return [goal];
+            }
+            return [];
+        });
+    }
     if (Array.isArray(o.integrations)) {
         def.integrations = o.integrations.flatMap((i) => {
             if (i &&
@@ -235,11 +256,40 @@ export function projectBasePath(def, forRemote) {
 }
 function projectRootsAbs(defs) {
     const out = [];
-    for (const def of defs) {
-        const raw = def.root ?? def.defaultPath;
+    const push = (name, raw) => {
         if (!raw)
-            continue;
-        out.push({ name: def.name, abs: path.resolve(expandLocalHome(raw)) });
+            return;
+        out.push({ name, abs: path.resolve(expandLocalHome(raw)) });
+    };
+    for (const def of defs) {
+        // `root` says where the CHECKOUT is; `defaultPath` says which work is this
+        // project's. For a monorepo subproject those differ, and only the narrower
+        // one is a membership claim — a project scoped to `rush/apps/cli` does not
+        // own `rush/apps/web`.
+        //
+        // The old `root ?? defaultPath` collapsed such a subproject onto the
+        // monorepo root, the same path its umbrella anchors at, so the longest-match
+        // tiebreak below had nothing to separate them and a session in
+        // `rush/apps/cli` counted toward whichever definition was listed first.
+        const rootAbs = def.root ? path.resolve(expandLocalHome(def.root)) : undefined;
+        const defaultAbs = def.defaultPath ? path.resolve(expandLocalHome(def.defaultPath)) : undefined;
+        const narrowed = !!(rootAbs && defaultAbs && defaultAbs !== rootAbs && isUnder(defaultAbs, rootAbs));
+        // A narrowed project's root is a WEAK claim: it still covers the rest of the
+        // checkout when nobody else wants it, but yields to any project that claims
+        // a path outright. Dropping it entirely regressed the single-project case —
+        // `add foo --root ~/src/foo --path apps/web` stopped attributing work
+        // anywhere else in its own repo, and `--path` means where agents START, not
+        // which work counts.
+        if (rootAbs)
+            out.push({ name: def.name, abs: rootAbs, weak: narrowed });
+        if (defaultAbs && defaultAbs !== rootAbs)
+            out.push({ name: def.name, abs: defaultAbs });
+        for (const r of def.repos ?? []) {
+            push(def.name, r.path);
+            // A repo pinned to a monorepo subpath anchors at that subpath too.
+            if (r.path && r.subpath)
+                push(def.name, path.join(expandLocalHome(r.path), r.subpath));
+        }
     }
     return out;
 }
@@ -269,13 +319,23 @@ export function projectNameForCwd(cwd, defs) {
     const abs = path.resolve(expandLocalHome(cwd));
     let best;
     let bestLen = -1;
-    for (const { name, abs: root } of projectRootsAbs(defs)) {
-        if (isUnder(abs, root) && root.length > bestLen) {
+    let weakBest;
+    let weakLen = -1;
+    for (const { name, abs: root, weak } of projectRootsAbs(defs)) {
+        if (!isUnder(abs, root))
+            continue;
+        if (weak) {
+            if (root.length > weakLen) {
+                weakBest = name;
+                weakLen = root.length;
+            }
+        }
+        else if (root.length > bestLen) {
             best = name;
             bestLen = root.length;
         }
     }
-    return best;
+    return best ?? weakBest;
 }
 /**
  * The canonical project label for a cwd, for every surface that buckets work by

package/dist/lib/rotate.d.ts

@@ -6,7 +6,7 @@
  */
 import type { AgentId, RunStrategy } from './types.js';
 import type { FallbackEntry } from './exec.js';
-import { type AccountInfo } from './agents.js';
+import { type AccountInfo, type CredentialPresence } from './agents.js';
 import { type UsageSnapshot } from './usage.js';
 export interface RotateCandidate {
     agent: AgentId;
@@ -75,6 +75,21 @@ export declare function getProjectRunStrategy(agent: AgentId, startPath: string)
 export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: string): RunStrategy;
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;
+/**
+ * Whether a version home can actually authenticate a launch.
+ *
+ * `getAccountInfo` falls back to the active/global HOME when a version home has
+ * no credential of its own, so `agents view` still shows who is logged in. Launch
+ * paths isolate config (GROK_HOME, CODEX_HOME, KIMI_CODE_HOME, CLAUDE_CONFIG_DIR,
+ * …) to the per-version home, so a home that only "inherits" the active login
+ * cannot spawn a signed-in agent — balanced kept picking those empty homes and
+ * the run died on "Not signed in".
+ *
+ * When we know where the credential lives (`knownLocation`), require it under
+ * THIS version home. When we don't (keychain-only / unmapped agents), trust the
+ * existing `signedIn` signal.
+ */
+export declare function isLaunchableSignedIn(signedIn: boolean, presence: Pick<CredentialPresence, 'knownLocation' | 'perVersion'>): boolean;
 /**
  * How old a usage snapshot may be and still settle a routing DECISION.
  *

package/dist/lib/rotate.js

@@ -6,7 +6,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { accountDisplayLabel, getAccountInfo, ALL_AGENT_IDS } from './agents.js';
+import { accountDisplayLabel, getAccountInfo, credentialPresence, ALL_AGENT_IDS, } from './agents.js';
 import { readMeta, writeMeta, getHelpersDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
 import { getProjectRunConfigs } from './run-config.js';
@@ -68,6 +68,27 @@ export function setGlobalRunStrategy(agent, strategy) {
 function isRotationEligible(candidate) {
     return candidate.signedIn && hasUsageAvailable(candidate);
 }
+/**
+ * Whether a version home can actually authenticate a launch.
+ *
+ * `getAccountInfo` falls back to the active/global HOME when a version home has
+ * no credential of its own, so `agents view` still shows who is logged in. Launch
+ * paths isolate config (GROK_HOME, CODEX_HOME, KIMI_CODE_HOME, CLAUDE_CONFIG_DIR,
+ * …) to the per-version home, so a home that only "inherits" the active login
+ * cannot spawn a signed-in agent — balanced kept picking those empty homes and
+ * the run died on "Not signed in".
+ *
+ * When we know where the credential lives (`knownLocation`), require it under
+ * THIS version home. When we don't (keychain-only / unmapped agents), trust the
+ * existing `signedIn` signal.
+ */
+export function isLaunchableSignedIn(signedIn, presence) {
+    if (!signedIn)
+        return false;
+    if (!presence.knownLocation)
+        return true;
+    return presence.perVersion;
+}
 function isAvailableEligible(candidate) {
     return isRotationEligible(candidate);
 }
@@ -484,17 +505,22 @@ export async function collectRunCandidates(agent) {
         // one per installed version, every time `agents run` cold-starts. If
         // claude's stored token has actually expired, the spawned agent detects
         // it at its own startup and re-auths; that's the correct UX.
+        //
+        // Gate signedIn on a real per-version credential when we know where it
+        // lives — see isLaunchableSignedIn. Do not reuse the active-home fallback
+        // identity for routing, or empty version homes look healthy and die at spawn.
+        const launchable = isLaunchableSignedIn(info.signedIn, credentialPresence(agent, home));
         return {
             agent,
             version,
             home,
             info,
-            accountKey: info.accountKey,
-            accountLabel: accountDisplayLabel(info),
-            email: info.email,
-            usageStatus: info.usageStatus,
-            plan: info.plan,
-            signedIn: info.signedIn,
+            accountKey: launchable ? info.accountKey : null,
+            accountLabel: launchable ? accountDisplayLabel(info) : '',
+            email: launchable ? info.email : null,
+            usageStatus: launchable ? info.usageStatus : null,
+            plan: launchable ? info.plan : null,
+            signedIn: launchable,
             lastActive: info.lastActive,
         };
     }));

package/dist/lib/secrets/bundles.d.ts

@@ -344,6 +344,26 @@ export interface RotateOptions {
  * unless `clearMeta` or a `meta` patch is supplied.
  */
 export declare function rotateBundleSecret(bundle: SecretsBundle, key: string, opts: RotateOptions): void;
+/**
+ * Reconcile a bundle's keychain-backed VALUE items to its CURRENT policy, then
+ * write the (always no-ACL) metadata.
+ *
+ * `writeBundle` only rewrites the metadata item, so a policy change alone leaves
+ * every value item carrying the ACL it was created with — and macOS gates each
+ * read on the ITEM's ACL, not the bundle's declared tier (spec SEC-19). Without
+ * this reconcile, `agents secrets policy <b> never` reports "silent" while the
+ * still-ACL'd value keeps popping Touch ID on every read, forever.
+ *
+ *   hold/always -> never  strips the biometry ACL (helper `set-no-acl`: delete+add)
+ *   never -> hold/always  re-attaches it (helper `set`)
+ *
+ * The current values are read in ONE batch, so the reconcile costs at most a
+ * single Touch ID — the last prompt a hold->never bundle will ever raise (a
+ * never->* flip reads silently, since the items are already no-ACL). No-op on the
+ * ACL to write for non-keychain backends (file/vault have no biometry concept),
+ * and a metadata-only write when the bundle has no keychain-backed values.
+ */
+export declare function reAclBundleItems(bundle: SecretsBundle): void;
 /** Options for renameBundle. */
 export interface RenameOptions {
     /** When true, overwrite an existing destination bundle (purges its keychain items first). */

package/dist/lib/secrets/bundles.js

@@ -1376,6 +1376,56 @@ export function rotateBundleSecret(bundle, key, opts) {
     }
     writeBundle(bundle);
 }
+/**
+ * Reconcile a bundle's keychain-backed VALUE items to its CURRENT policy, then
+ * write the (always no-ACL) metadata.
+ *
+ * `writeBundle` only rewrites the metadata item, so a policy change alone leaves
+ * every value item carrying the ACL it was created with — and macOS gates each
+ * read on the ITEM's ACL, not the bundle's declared tier (spec SEC-19). Without
+ * this reconcile, `agents secrets policy <b> never` reports "silent" while the
+ * still-ACL'd value keeps popping Touch ID on every read, forever.
+ *
+ *   hold/always -> never  strips the biometry ACL (helper `set-no-acl`: delete+add)
+ *   never -> hold/always  re-attaches it (helper `set`)
+ *
+ * The current values are read in ONE batch, so the reconcile costs at most a
+ * single Touch ID — the last prompt a hold->never bundle will ever raise (a
+ * never->* flip reads silently, since the items are already no-ACL). No-op on the
+ * ACL to write for non-keychain backends (file/vault have no biometry concept),
+ * and a metadata-only write when the bundle has no keychain-backed values.
+ */
+export function reAclBundleItems(bundle) {
+    if ((bundle.backend ?? 'keychain') !== 'keychain') {
+        // No biometry ACL off the keychain backend — only metadata needs persisting.
+        writeBundle(bundle);
+        return;
+    }
+    const store = itemStore('keychain');
+    // keychainItemsForBundle already returns ONLY keychain-backed value items
+    // (via parseBundleValue), so no extra ref-shape filtering here.
+    const entries = keychainItemsForBundle(bundle);
+    if (entries.length === 0) {
+        // Literal/ref-only bundle: nothing to re-ACL, just refresh metadata.
+        writeBundle(bundle);
+        return;
+    }
+    // One batched read = at most one Touch ID for the whole reconcile.
+    const values = store.getBatch(entries.map((e) => e.item));
+    const rewrite = new Map();
+    for (const { item } of entries) {
+        const value = values.get(item);
+        // A key present in metadata but with no readable value item is real
+        // corruption, not something to silently skip (no fallbacks — fail loud).
+        if (value === undefined) {
+            throw new Error(`Cannot change policy for '${bundle.name}': a keychain value is missing or unreadable. Rotate that key, then retry.`);
+        }
+        rewrite.set(item, value);
+    }
+    // writeBundleWithItems re-stores each value with { noAcl: policy === 'never' }
+    // and the metadata no-ACL (metadata-last), and evicts any broker-held copy.
+    writeBundleWithItems(bundle, rewrite);
+}
 /**
  * Rename a bundle: move metadata + every keychain-backed value to a new name.
  *

package/dist/lib/secrets/install-helper.js

@@ -18,6 +18,7 @@ import { createHash } from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
 const APP_BUNDLE_NAME = 'Agents CLI.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 let installRootOverride = null;
@@ -107,19 +108,6 @@ function spctlAssess(appPath) {
     });
     return { ok: r.status === 0, output: (r.stderr || r.stdout || '').toString().trim() };
 }
-function copyAppBundle(src, dest) {
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    if (fs.existsSync(dest))
-        fs.rmSync(dest, { recursive: true, force: true });
-    // `cp -R` preserves the bundle's signature, symlinks, and resource forks.
-    // `fs.cpSync({recursive: true})` works on simple trees but has historically
-    // mishandled extended attributes on `.app` bundles, breaking codesign.
-    const r = spawnSync('cp', ['-R', src, dest], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
-    if (r.status !== 0) {
-        const msg = (r.stderr || r.stdout || '').toString().trim();
-        throw new Error(`Failed to copy ${src} -> ${dest}: ${msg || 'unknown error'}`);
-    }
-}
 /**
  * Idempotent install. Copies the bundled `.app` to the stable user path. Skips
  * if the destination already exists, `codesign --verify` passes, AND the
@@ -135,25 +123,34 @@ function copyAppBundle(src, dest) {
 export function ensureKeychainHelperInstalled(opts = {}) {
     assertDarwin();
     const dest = installedAppPath();
-    if (!opts.forceReinstall && fs.existsSync(dest)) {
-        const { ok } = codesignVerify(dest);
-        if (ok && !installedHelperIsStale())
+    const upToDate = () => fs.existsSync(dest) && codesignVerify(dest).ok && !installedHelperIsStale();
+    // Fast path: already installed, valid, and current — no lock, no copy.
+    if (!opts.forceReinstall && upToDate())
+        return;
+    // Serialize the install so concurrent `agents` invocations don't race the
+    // atomic swap (and don't each run a redundant `cp`). The re-check inside the
+    // lock means a burst of callers copies once, not N times — the stampede that
+    // transiently corrupted the bundle and tripped the "damaged" dialog.
+    withInstallLock(dest, (heartbeat) => {
+        if (!opts.forceReinstall && upToDate())
             return;
-    }
-    const src = sourceAppPath();
-    copyAppBundle(src, dest);
-    const verify = codesignVerify(dest);
-    if (!verify.ok) {
-        throw new Error(`Installed helper failed codesign verification at ${dest}.\n${verify.output}\n` +
-            'The bundle may be corrupted. Try `agents helper install` to reinstall, or reinstall agents-cli.');
-    }
-    const assess = spctlAssess(dest);
-    if (!assess.ok) {
-        // Warn, do not fail. Gatekeeper ticket lookup needs network; offline
-        // installs and CI runners commonly fail this check. The ACL semantics
-        // we care about depend on codesign, not spctl.
-        process.stderr.write(`agents-cli: notarization check (spctl) did not pass for ${dest}: ${assess.output}\n`);
-    }
+        const src = sourceAppPath();
+        copyAppBundle(src, dest);
+        heartbeat(); // cp -R done; keep the lock fresh across the codesign/spctl spawns
+        const verify = codesignVerify(dest);
+        if (!verify.ok) {
+            throw new Error(`Installed helper failed codesign verification at ${dest}.\n${verify.output}\n` +
+                'The bundle may be corrupted. Try `agents helper install` to reinstall, or reinstall agents-cli.');
+        }
+        heartbeat(); // codesign done; spctl does a network Gatekeeper lookup — refresh again
+        const assess = spctlAssess(dest);
+        if (!assess.ok) {
+            // Warn, do not fail. Gatekeeper ticket lookup needs network; offline
+            // installs and CI runners commonly fail this check. The ACL semantics
+            // we care about depend on codesign, not spctl.
+            process.stderr.write(`agents-cli: notarization check (spctl) did not pass for ${dest}: ${assess.output}\n`);
+        }
+    });
 }
 /**
  * Return the absolute path to the helper executable. If the installed bundle

package/dist/lib/share/config.d.ts

@@ -32,12 +32,20 @@ export declare function readWriteTokenFromBundle(): string;
 /** Read the raw write token from injected env first, then the local bundle.
  * Throws with an actionable message if absent (run setup/join first). */
 export declare function readWriteToken(): string;
-/** Best-effort runtime env for spawned agents. Never throws: a missing/locked
- * bundle should not block unrelated agent runs, but an already-unlocked bundle
- * or injected token lets ephemeral agents publish with no local setup. */
-export declare function shareRuntimeEnv(opts?: {
-    agentOnly?: boolean;
-}): Record<string, string> | undefined;
+/** Best-effort runtime env for spawned agents. Never throws AND never prompts.
+ *
+ * Auto-injecting the share write token on every `agents run` is a background
+ * convenience, NOT a user-initiated secret access — so it MUST NOT raise a Touch
+ * ID sheet (SEC-13: an agent launch never pops biometry on its own). This was the
+ * per-run prompt storm: `share` is a keychain bundle that is rarely broker-held,
+ * so an interactive read here spawned the helper and popped Touch ID on EVERY
+ * launch. The read is now always `agentOnly` — it resolves the token only from the
+ * injected env or an already-held / no-ACL bundle, and silently returns undefined
+ * otherwise (the caller runs without auto-share; the agent can still publish via
+ * its own `agents share`). To get zero-friction auto-share with no prompt: unlock
+ * once (`agents secrets unlock share`) or make it no-ACL (`agents secrets policy
+ * share never`). */
+export declare function shareRuntimeEnv(): Record<string, string> | undefined;
 /** Cloudflare API credentials for provisioning, read from `cloudflare` (or a
  * user-named bundle). Fuzzy-matches key names so it works across bundle layouts. */
 export declare function readCloudflareCreds(bundle?: string, override?: {

package/dist/lib/share/config.js

@@ -56,6 +56,14 @@ export function storeWriteToken(token) {
         bundle = {
             name: SHARE_BUNDLE,
             description: 'agents share — write token for the R2 share endpoint',
+            // A NEW share bundle defaults to the `never` tier (no biometry ACL). The R2
+            // write token is low-sensitivity automation infra that is auto-read on EVERY
+            // `agents run` (shareRuntimeEnv) — a biometry ACL there is what produced the
+            // per-run Touch ID storm. `never` stores it no-ACL so auto-share is silent
+            // and needs no unlock. An EXISTING bundle keeps its tier (we never silently
+            // downgrade one the user already made); change it explicitly with
+            // `agents secrets policy share <tier>`.
+            policy: 'never',
             vars: {},
         };
     }
@@ -82,10 +90,20 @@ export function readWriteTokenFromBundle() {
 export function readWriteToken() {
     return readWriteTokenEnv() ?? readWriteTokenFromBundle();
 }
-/** Best-effort runtime env for spawned agents. Never throws: a missing/locked
- * bundle should not block unrelated agent runs, but an already-unlocked bundle
- * or injected token lets ephemeral agents publish with no local setup. */
-export function shareRuntimeEnv(opts = {}) {
+/** Best-effort runtime env for spawned agents. Never throws AND never prompts.
+ *
+ * Auto-injecting the share write token on every `agents run` is a background
+ * convenience, NOT a user-initiated secret access — so it MUST NOT raise a Touch
+ * ID sheet (SEC-13: an agent launch never pops biometry on its own). This was the
+ * per-run prompt storm: `share` is a keychain bundle that is rarely broker-held,
+ * so an interactive read here spawned the helper and popped Touch ID on EVERY
+ * launch. The read is now always `agentOnly` — it resolves the token only from the
+ * injected env or an already-held / no-ACL bundle, and silently returns undefined
+ * otherwise (the caller runs without auto-share; the agent can still publish via
+ * its own `agents share`). To get zero-friction auto-share with no prompt: unlock
+ * once (`agents secrets unlock share`) or make it no-ACL (`agents secrets policy
+ * share never`). */
+export function shareRuntimeEnv() {
     if (!readShareConfig())
         return undefined;
     const fromEnv = readWriteTokenEnv();
@@ -97,7 +115,7 @@ export function shareRuntimeEnv(opts = {}) {
         const { env } = readAndResolveBundleEnv(SHARE_BUNDLE, {
             caller: 'share',
             keys: [SHARE_TOKEN_KEY],
-            agentOnly: opts.agentOnly,
+            agentOnly: true, // never raise a Touch ID sheet on an agent launch (SEC-13)
         });
         const token = env[SHARE_TOKEN_KEY];
         return token ? { [SHARE_TOKEN_ENV_KEY]: token } : undefined;

package/dist/lib/types.d.ts

@@ -764,6 +764,16 @@ export interface Meta {
      */
     isolatedAgents?: Partial<Record<AgentId, string>>;
     run?: RunConfig;
+    /**
+     * Daemon watchdog config. `rotate` (default `on`) lets the watchdog rotate a
+     * rate-limited session IN PLACE onto a healthy account/harness via
+     * `agents run auto` — see lib/watchdog/rotate.ts. Set `off` to keep the
+     * nudge-only behavior (the Factory `agents.watchdog.autoRotate: false`
+     * migration writes `off` here).
+     */
+    watchdog?: {
+        rotate?: 'on' | 'off';
+    };
     /**
      * `agents run --lease` config. `secretsBundle` names the keychain secrets bundle
      * whose provider token (e.g. `HCLOUD_TOKEN`) crabbox uses to reach the cloud API.