@phnx-labs/agents-cli 1.20.70 → 1.20.71

package/dist/lib/doctor-diff.js

@@ -22,21 +22,19 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, agentConfigDirName } from './agents.js';
-import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getEffectivePromptcutsPath, } from './state.js';
+import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getEffectivePromptcutsPath, getActiveRulesPreset, } from './state.js';
+import { composeRulesFromState } from './rules/compose.js';
 import { getAvailableResources, getActuallySyncedResources, getVersionHomePath, compareVersions, } from './versions.js';
 import { discoverPlugins, marketplaceSpecForName } from './plugins.js';
 import { pluginInstallDir, repairableManifestFields } from './plugin-marketplace.js';
 import { markdownToToml } from './convert.js';
-import { resolveImports, supportsRulesImports } from './rules/compile.js';
-import { listCommandsInVersionHome, getVersionCommandsDir } from './commands.js';
+import { listCommandsInVersionHome, getVersionCommandsDir, listPluginCommandNames } from './commands.js';
 import { shouldInstallCommandAsSkill, commandSkillMatches, commandSkillName } from './command-skills.js';
 import { gooseCommandMatches, gooseCommandsDir } from './goose-commands.js';
 import { supports } from './capabilities.js';
 import { listSkillsInVersionHome, getVersionSkillsDir } from './skills.js';
 import { listHooksInVersionHome, listHookEntriesFromDir } from './hooks.js';
 const RULES_DOC_FILENAME = 'README.md';
-const COMPILED_HEADER = '<!-- Auto-compiled by agents-cli from ~/.agents/rules/AGENTS.md + imports.\n' +
-    '     Edit the source files under ~/.agents/rules/ — edits to this file will be overwritten on next sync. -->\n\n';
 const ALL_KINDS = [
     'commands',
     'skills',
@@ -173,9 +171,16 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
             homePath,
         });
     }
+    // Plugin-bundled commands (installed as `<plugin>-<cmd>`) are source-managed by
+    // their plugin, tracked under the `plugins` kind — not extras. Without this,
+    // `agents doctor` shows every plugin command (swarm-plan, code-review, …) as an
+    // unmanaged extra, mirroring the orphan false-positive the prune path had.
+    const pluginCommands = listPluginCommandNames();
     for (const name of installed) {
         if (seen.has(name))
             continue;
+        if (pluginCommands.has(name))
+            continue;
         const extraHome = asSkill
             ? path.join(agentDir, 'skills', commandSkillName(name), 'SKILL.md')
             : agent === 'goose'
@@ -236,6 +241,14 @@ function dirsContentMatch(src, dst) {
     return true;
 }
 function diffSkills(agent, version, cwd, excludeProject = false) {
+    // Native ~/.agents/skills consumers (Gemini, …) read central skills directly.
+    // The orchestrator DELETES their version-home skills dir (syncResourcesToVersion)
+    // and registers no skills writer, so there is nothing in the version home to
+    // reconcile. Mirror diffVersionSkills' native gate (skills.ts) — without it
+    // every central skill is false-reported `missing` and held as unreconcilable
+    // forever (drift never clears for these agents).
+    if (AGENTS[agent].nativeAgentsSkillsDir)
+        return [];
     const homeDir = getVersionSkillsDir(agent, version);
     const installed = new Set(listSkillsInVersionHome(agent, version));
     const layerBases = buildLayerBases(cwd, 'skills', { excludeProject });
@@ -380,18 +393,27 @@ function listRulesNames(cwd, excludeProject = false) {
     }
     return out;
 }
-function expectedRuleContent(agent, name, sourcePath) {
-    // AGENTS.md on agents without native @-import support is compiled with imports inlined.
-    if (name === 'AGENTS' && !supportsRulesImports(agent)) {
-        const root = readSafe(sourcePath);
-        if (root == null)
+function expectedRuleContent(agent, name, version, sourcePath) {
+    // The instruction file (AGENTS → the agent's CLAUDE.md/GEMINI.md/AGENTS.md)
+    // is COMPOSED from `subrules/` fragments for the version's active preset —
+    // that is exactly what the rules writer emits (see
+    // staleness/writers/rules.ts → composeRulesFromState). Compare against the
+    // same rendering so a correctly-synced home file reconciles instead of being
+    // held forever against the raw `rules/AGENTS.md` (the whole-repo doc, which a
+    // preset composition deliberately never equals — system subrules don't
+    // auto-append). The `agent` is not part of the rendering (every capable agent
+    // gets identical composed bytes); it is kept for symmetry with the writer's
+    // per-agent dispatch and future per-agent presets.
+    if (name === 'AGENTS') {
+        try {
+            return composeRulesFromState({ preset: getActiveRulesPreset(agent, version) }).content;
+        }
+        catch {
+            // No rules.yaml / unknown preset — the writer skips too; treat as unknown.
             return null;
-        // Compile relative to the source's own dir so project-layer AGENTS.md resolves
-        // its imports relative to the project rules dir, not the user one.
-        const baseDir = path.dirname(sourcePath);
-        const { content } = resolveImports(root, baseDir);
-        return COMPILED_HEADER + content;
+        }
     }
+    // Any sibling top-level rules file syncs as a raw copy.
     return readSafe(sourcePath);
 }
 function diffRules(agent, version, cwd, excludeProject = false) {
@@ -418,7 +440,7 @@ function diffRules(agent, version, cwd, excludeProject = false) {
             rows.push({ kind: 'rules', name, status: 'missing', source: src.layer, sourcePath: src.path });
             continue;
         }
-        const expected = expectedRuleContent(agent, name, src.path);
+        const expected = expectedRuleContent(agent, name, version, src.path);
         const actual = readSafe(homePath);
         if (expected == null || actual == null) {
             rows.push({ kind: 'rules', name, status: 'diff', source: src.layer, sourcePath: src.path, homePath });

package/dist/lib/fleet/apply.d.ts

@@ -30,6 +30,10 @@ export interface DiffContext {
     /** agents-cli version the source is on — the fleet target version. */
     targetCliVersion: string;
     sourceAuth: SourceAuth;
+    /** Secrets-bundle names the profile declares. Values are keychain-local and
+     * can't be pushed, so each reachable device surfaces them as a manual recreate
+     * (`needs-secret`) — informational, never an executed mutation. */
+    secretsBundles?: string[];
 }
 /** Pure: desired vs probed -> per-device diff + flat action list. */
 export declare function diffFleet(desired: DeviceDesired[], probes: Map<string, DeviceProbe>, ctx: DiffContext): FleetPlan;

package/dist/lib/fleet/apply.js

@@ -44,6 +44,7 @@ export function diffFleet(desired, probes, ctx) {
         };
         const rowActions = [];
         const loginBlocked = [];
+        const secretsNeeded = [];
         if (probe.reachable) {
             // agents-cli presence.
             if (!probe.cliVersion) {
@@ -82,8 +83,18 @@ export function diffFleet(desired, probes, ctx) {
                     }
                 }
             }
+            // secrets — surfaced, never pushed (values are keychain-local). Declared
+            // once at the manifest level, so every reachable device gets the same
+            // manual-recreate reminder. Not an executable action (see idempotence
+            // check in commands/apply.ts, which excludes needs-* kinds).
+            if (ctx.secretsBundles && ctx.secretsBundles.length > 0) {
+                for (const bundle of ctx.secretsBundles) {
+                    secretsNeeded.push(bundle);
+                    rowActions.push({ device: d.device, kind: 'needs-secret', detail: `recreate secrets bundle '${bundle}' (\`agents secrets create ${bundle}\`)` });
+                }
+            }
         }
-        devices.push({ device: d.device, desired: d, probe, actions: rowActions, loginBlocked });
+        devices.push({ device: d.device, desired: d, probe, actions: rowActions, loginBlocked, secretsNeeded });
         actions.push(...rowActions);
     }
     return { devices, actions };
@@ -161,11 +172,18 @@ export function reconcileDevice(row, device, ctx) {
         steps.push({ kind: 'add-agent', ok: r.code === 0, detail: a.detail });
         ok = ok && r.code === 0;
     }
-    // 3. config sync.
+    // 3. config sync — one `agents sync <scope>` per declared scope. Each scope is
+    // a positional repo target (system/user/project/alias); a bare `agents sync`
+    // would ignore the profile's declared scopes entirely.
     if (row.actions.some((a) => a.kind === 'sync-config')) {
-        const r = sshAgents(['sync']);
-        steps.push({ kind: 'sync-config', ok: r.code === 0, detail: `sync config` });
-        ok = ok && r.code === 0;
+        const scopes = row.desired.sync.length > 0 ? row.desired.sync : [''];
+        let syncOk = true;
+        for (const scope of scopes) {
+            const r = sshAgents(scope ? ['sync', scope] : ['sync']);
+            syncOk = syncOk && r.code === 0;
+        }
+        steps.push({ kind: 'sync-config', ok: syncOk, detail: `sync config (${row.desired.sync.join(', ') || 'default'})` });
+        ok = ok && syncOk;
     }
     // 4. login propagation — one bundle for all pushable agents on this device.
     const pushAgents = [...new Set(row.actions.filter((a) => a.kind === 'push-login').map((a) => a.agent))];
@@ -182,6 +200,11 @@ export function reconcileDevice(row, device, ctx) {
     for (const blocked of row.loginBlocked) {
         steps.push({ kind: 'needs-login', ok: false, detail: `${blocked} needs a manual login (\`agents ssh ${row.device} -- ${blocked}\`)` });
     }
+    // Surface declared secrets bundles as (non-fatal) manual-recreate reminders —
+    // values are keychain-local, never captured or pushed.
+    for (const bundle of row.secretsNeeded) {
+        steps.push({ kind: 'needs-secret', ok: false, detail: `secrets bundle '${bundle}' must exist on ${row.device} (\`agents ssh ${row.device} -- secrets create ${bundle}\`)` });
+    }
     return { device: row.device, ok, steps };
 }
 /** Run a pool of async tasks with a concurrency cap, preserving input order. */

package/dist/lib/fleet/capture.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Serialize the live environment into a `fleet:` manifest.
+ *
+ * `captureFleet` is PURE — it takes the previous manifest plus already-gathered
+ * inputs (device names, per-device agent specs, browser profiles, secret-bundle
+ * names, routine names) and returns the new manifest. All I/O (registry read,
+ * `agents secrets`/`routines` enumeration, YAML write) happens in the command
+ * (`commands/fleet-capture.ts`); keeping this pure makes the privacy contract —
+ * NAMES ONLY, never IPs/usernames — trivially unit-testable.
+ *
+ * Additive by design: it merges OVER an existing manifest and never clobbers a
+ * hand-authored per-device override (`agents:` you set by hand wins over a
+ * captured one). The captured roster reflects live state, so it becomes the
+ * source of truth for WHICH devices exist.
+ */
+import type { FleetManifest, FleetDefaults } from './types.js';
+export interface CaptureInputs {
+    /** Registered, non-control device names to record (the roster — names only). */
+    devices: string[];
+    /** Optional per-device agent specs (e.g. from `--from-pins`), keyed by name. */
+    agentsByDevice?: Record<string, string[]>;
+    /** Fleet defaults to seed when the manifest has none (source's own agents). */
+    defaults?: FleetDefaults;
+    /** Secrets-bundle NAMES to ensure exist (values stay in the keychain). */
+    secretsBundles?: string[];
+    /** Routine NAMES that should be active on the fleet. */
+    routines?: string[];
+}
+/**
+ * Build the new `fleet:` manifest from the previous one and captured inputs.
+ * Pure — no SSH, no filesystem, no registry. The returned object carries device
+ * names + desired state only; a caller that serializes it to YAML can assert no
+ * address/username ever appears.
+ */
+export declare function captureFleet(prev: FleetManifest | undefined, inputs: CaptureInputs): FleetManifest;

package/dist/lib/fleet/capture.js

@@ -0,0 +1,51 @@
+/**
+ * Serialize the live environment into a `fleet:` manifest.
+ *
+ * `captureFleet` is PURE — it takes the previous manifest plus already-gathered
+ * inputs (device names, per-device agent specs, browser profiles, secret-bundle
+ * names, routine names) and returns the new manifest. All I/O (registry read,
+ * `agents secrets`/`routines` enumeration, YAML write) happens in the command
+ * (`commands/fleet-capture.ts`); keeping this pure makes the privacy contract —
+ * NAMES ONLY, never IPs/usernames — trivially unit-testable.
+ *
+ * Additive by design: it merges OVER an existing manifest and never clobbers a
+ * hand-authored per-device override (`agents:` you set by hand wins over a
+ * captured one). The captured roster reflects live state, so it becomes the
+ * source of truth for WHICH devices exist.
+ */
+/**
+ * Build the new `fleet:` manifest from the previous one and captured inputs.
+ * Pure — no SSH, no filesystem, no registry. The returned object carries device
+ * names + desired state only; a caller that serializes it to YAML can assert no
+ * address/username ever appears.
+ */
+export function captureFleet(prev, inputs) {
+    const prevDevices = prev && prev.devices !== 'all' && typeof prev.devices === 'object'
+        ? prev.devices
+        : {};
+    // Roster: explicit map of the captured names. A hand-authored override for a
+    // device that still exists is preserved; a captured agent list only fills in
+    // when the manifest didn't already pin one for that device.
+    const devices = {};
+    for (const name of inputs.devices) {
+        const prevOverride = prevDevices[name] ?? {};
+        const override = { ...prevOverride };
+        const captured = inputs.agentsByDevice?.[name];
+        if (override.agents === undefined && captured && captured.length > 0) {
+            override.agents = captured;
+        }
+        devices[name] = override;
+    }
+    const manifest = {
+        // Keep hand-authored defaults; otherwise seed from the source snapshot.
+        defaults: prev?.defaults ?? inputs.defaults ?? {},
+        devices,
+    };
+    const bundles = inputs.secretsBundles ?? prev?.secrets?.bundles;
+    if (bundles && bundles.length > 0)
+        manifest.secrets = { bundles: [...bundles].sort() };
+    const routines = inputs.routines ?? prev?.routines;
+    if (routines && routines.length > 0)
+        manifest.routines = [...routines].sort();
+    return manifest;
+}

package/dist/lib/fleet/manifest.d.ts

@@ -19,6 +19,12 @@ export interface ResolveContext {
     registeredDevices: string[];
     /** The source machine, always excluded from the target set. */
     source: string;
+    /** Names the bootstrap could not resolve from Tailscale (off-tailnet, ignored,
+     * or a typo). These are SKIPPED with the caller's warning rather than aborting
+     * the whole reconcile — a manifest naming an asleep laptop must not hard-fail
+     * every other device. Without a bootstrap, this is empty and an unregistered
+     * name still throws (genuine misconfig, caught early). */
+    unresolved?: string[];
 }
 /**
  * Expand a manifest into concrete per-device desired states. `devices: all`

package/dist/lib/fleet/manifest.js

@@ -66,7 +66,25 @@ export function parseFleetManifest(raw) {
     else {
         throw new Error(`fleet: devices must be the string 'all' or a mapping of device -> overrides (got ${JSON.stringify(o.devices)}).`);
     }
-    return { defaults, devices };
+    const manifest = { defaults, devices };
+    // Additive, backward-compatible extras (captured by `agents fleet capture`).
+    if (o.secrets !== undefined) {
+        if (typeof o.secrets !== 'object' || o.secrets === null || Array.isArray(o.secrets)) {
+            throw new Error('fleet: secrets must be a mapping with a `bundles:` list.');
+        }
+        const bundles = o.secrets.bundles;
+        if (bundles !== undefined && !isStringArray(bundles)) {
+            throw new Error('fleet: secrets.bundles must be a list of bundle names (e.g. [attio]).');
+        }
+        manifest.secrets = { bundles: bundles };
+    }
+    if (o.routines !== undefined) {
+        if (!isStringArray(o.routines)) {
+            throw new Error('fleet: routines must be a list of routine names.');
+        }
+        manifest.routines = o.routines;
+    }
+    return manifest;
 }
 /** Read a YAML file and extract + validate its `fleet:` block. */
 export function readFleetFile(filePath) {
@@ -115,9 +133,14 @@ export function resolveDesired(manifest, ctx) {
         }
         return out;
     }
+    const unresolved = new Set(ctx.unresolved ?? []);
     for (const [name, override] of Object.entries(manifest.devices)) {
         if (name === ctx.source)
             continue;
+        // Bootstrap couldn't register this name (off-tailnet / ignored / typo) —
+        // skip it (the caller already surfaced it) instead of aborting the run.
+        if (unresolved.has(name))
+            continue;
         if (!ctx.registeredDevices.includes(name)) {
             throw new Error(`fleet: device '${name}' is not a registered device. Run \`agents devices add ${name}\` or fix the manifest.`);
         }

package/dist/lib/fleet/types.d.ts

@@ -42,6 +42,23 @@ export interface FleetDeviceOverride {
 export interface FleetManifest {
     defaults?: FleetDefaults;
     devices: 'all' | Record<string, FleetDeviceOverride>;
+    /**
+     * Fleet-wide extras captured by `agents fleet capture` so a fresh machine can
+     * reconstruct the whole environment, not just installed agents. All additive,
+     * portable, and LEAK-FREE — names only, never connection details.
+     *
+     * (Browser profiles are deliberately NOT captured here: the central `browser:`
+     * block already syncs verbatim via `agents repo push/pull`, so duplicating it
+     * would be redundant — and its ssh:// endpoints can carry `user@host`, which
+     * must never be copied into a second location.)
+     */
+    /** Secrets-bundle NAMES to ensure exist — values live in the keychain and are
+     * never captured or pushed; `apply` surfaces missing bundles to recreate. */
+    secrets?: {
+        bundles?: string[];
+    };
+    /** Routine NAMES that should be active on the fleet (files sync via the repo). */
+    routines?: string[];
 }
 /**
  * A device's desired state after merging defaults with its override and
@@ -74,7 +91,10 @@ export interface DeviceProbe {
     note?: string;
 }
 /** One planned action against a device, in a single reconcile dimension. */
-export type FleetActionKind = 'install-cli' | 'upgrade-cli' | 'add-agent' | 'sync-config' | 'push-login' | 'needs-login';
+export type FleetActionKind = 'install-cli' | 'upgrade-cli' | 'add-agent' | 'sync-config' | 'push-login' | 'needs-login'
+/** Secrets bundles the profile declares but that can't be pushed (values are
+ * keychain-local) — surfaced as a manual recreate, like `needs-login`. */
+ | 'needs-secret';
 export interface FleetAction {
     device: string;
     kind: FleetActionKind;
@@ -101,6 +121,9 @@ export interface DeviceDiff {
     /** Agents that must be logged in on the device but can't be propagated
      * (source token is device-bound, e.g. macOS keychain). Surfaced, not faked. */
     loginBlocked: string[];
+    /** Secrets-bundle names the profile declares that must be recreated on the
+     * device (values are keychain-local — never captured or pushed). Surfaced. */
+    secretsNeeded: string[];
 }
 /** A portable auth file captured from a source agent home, ready to propagate. */
 export interface AuthFilePayload {

package/dist/lib/git.d.ts

@@ -219,6 +219,20 @@ export declare function displayHomePath(dir: string): string;
  * branch reconciles instead of failing with "Need to specify how to reconcile
  * divergent branches".
  */
+/**
+ * Auto-commit the machine's OWN generated per-device meta file
+ * (`devices/<machineId>/agents.yaml`) if it's the dirty state blocking a pull.
+ *
+ * That file is committed + synced (so every machine can introspect every other
+ * machine's pins), but each box rewrites its own copy whenever a pin changes —
+ * leaving the tree perpetually dirty and wedging `agents repo pull` (which
+ * refuses a dirty tree). This durably commits just that one path (explicit
+ * pathspec) so the pull can proceed; genuine user edits to OTHER files are left
+ * untouched and still (correctly) block the pull. No-op when the meta path isn't
+ * inside `dir` (system/extra repos) or isn't dirty. Returns the committed rel
+ * path, or null. `metaAbs` is injectable for tests; defaults to the live path.
+ */
+export declare function commitOwnDeviceMeta(dir: string, metaAbs?: string): Promise<string | null>;
 export declare function pullRepo(dir: string): Promise<{
     success: boolean;
     commit: string;

package/dist/lib/git.js

@@ -10,7 +10,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { IS_WINDOWS, isWindowsAbsolutePath } from './platform/index.js';
-import { getPackageLocalPath } from './state.js';
+import { getPackageLocalPath, getDeviceMetaPath } from './state.js';
 import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from './types.js';
 /**
  * Validate that a clone/pull source uses a safe git transport before it is
@@ -733,9 +733,47 @@ export function displayHomePath(dir) {
  * branch reconciles instead of failing with "Need to specify how to reconcile
  * divergent branches".
  */
+/**
+ * Auto-commit the machine's OWN generated per-device meta file
+ * (`devices/<machineId>/agents.yaml`) if it's the dirty state blocking a pull.
+ *
+ * That file is committed + synced (so every machine can introspect every other
+ * machine's pins), but each box rewrites its own copy whenever a pin changes —
+ * leaving the tree perpetually dirty and wedging `agents repo pull` (which
+ * refuses a dirty tree). This durably commits just that one path (explicit
+ * pathspec) so the pull can proceed; genuine user edits to OTHER files are left
+ * untouched and still (correctly) block the pull. No-op when the meta path isn't
+ * inside `dir` (system/extra repos) or isn't dirty. Returns the committed rel
+ * path, or null. `metaAbs` is injectable for tests; defaults to the live path.
+ */
+export async function commitOwnDeviceMeta(dir, metaAbs = getDeviceMetaPath()) {
+    const resolvedDir = path.resolve(dir);
+    const resolvedMeta = path.resolve(metaAbs);
+    if (resolvedMeta !== resolvedDir && !resolvedMeta.startsWith(resolvedDir + path.sep)) {
+        return null; // meta lives outside this repo — not ours to commit here
+    }
+    const rel = path.relative(resolvedDir, resolvedMeta).split(path.sep).join('/');
+    try {
+        const git = simpleGit(dir);
+        const status = await git.status();
+        const dirty = status.files.some((f) => f.path === rel);
+        if (!dirty)
+            return null;
+        await git.add([rel]);
+        const machine = path.basename(path.dirname(resolvedMeta));
+        await git.commit(`chore(devices): snapshot ${machine} agent pins`, [rel]);
+        return rel;
+    }
+    catch {
+        return null; // best-effort — never let this block the pull path
+    }
+}
 export async function pullRepo(dir) {
     try {
         const git = simpleGit(dir);
+        // Commit this machine's own device-meta first so a per-machine pin change
+        // never wedges the pull. Genuine edits elsewhere still block below.
+        await commitOwnDeviceMeta(dir);
         const status = await git.status();
         if (!status.isClean()) {
             return {

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

@@ -26,6 +26,18 @@ export declare function menubarServiceInstalled(): boolean;
 export declare function ensureMenubarAppInstalled(opts?: {
     forceReinstall?: boolean;
 }): string | null;
+/**
+ * Restart the menu-bar launchd agent from a clean state.
+ *
+ * Always `bootout` first: on modern macOS `bootstrap` fails when the job is
+ * already bootstrapped, and the deprecated `load -w` fallback is unreliable.
+ * A prior WindowServer disconnect can leave the job throttled so that a plain
+ * `kickstart -k` does not bring it back; booting it out and bootstrapping fresh
+ * is the only sequence that reliably re-attaches the status item.
+ */
+export declare function restartMenubarLaunchAgent(uid: number, plist: string, exec?: (cmd: string, args: readonly string[], opts: {
+    stdio: ['ignore', 'ignore', 'ignore'];
+}) => Buffer): void;
 /**
  * Install + start the menu-bar helper as a launchd user service (idempotent).
  * Clears the sticky opt-out, installs the .app, writes the plist, and

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

@@ -210,6 +210,31 @@ ${envXml}
 </dict>
 </plist>`;
 }
+/**
+ * Restart the menu-bar launchd agent from a clean state.
+ *
+ * Always `bootout` first: on modern macOS `bootstrap` fails when the job is
+ * already bootstrapped, and the deprecated `load -w` fallback is unreliable.
+ * A prior WindowServer disconnect can leave the job throttled so that a plain
+ * `kickstart -k` does not bring it back; booting it out and bootstrapping fresh
+ * is the only sequence that reliably re-attaches the status item.
+ */
+export function restartMenubarLaunchAgent(uid, plist, exec = execFileSync) {
+    const serviceTarget = `gui/${uid}/${SERVICE_LABEL}`;
+    const opts = { stdio: ['ignore', 'ignore', 'ignore'] };
+    try {
+        exec('launchctl', ['bootout', serviceTarget], opts);
+    }
+    catch { /* may not be loaded */ }
+    try {
+        exec('launchctl', ['bootstrap', `gui/${uid}`, plist], opts);
+    }
+    catch { /* best effort */ }
+    try {
+        exec('launchctl', ['kickstart', serviceTarget], opts);
+    }
+    catch { /* best effort */ }
+}
 /**
  * Install + start the menu-bar helper as a launchd user service (idempotent).
  * Clears the sticky opt-out, installs the .app, writes the plist, and
@@ -232,19 +257,7 @@ export function enableMenubarService(opts = { clearOptOut: true }) {
     fs.mkdirSync(path.dirname(plist), { recursive: true });
     fs.writeFileSync(plist, generateServicePlist(exec));
     const uid = process.getuid?.() ?? 0;
-    try {
-        execFileSync('launchctl', ['bootstrap', `gui/${uid}`, plist], { stdio: ['ignore', 'ignore', 'ignore'] });
-    }
-    catch {
-        try {
-            execFileSync('launchctl', ['load', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
-        }
-        catch { /* may already be loaded */ }
-    }
-    try {
-        execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
-    }
-    catch { /* best effort */ }
+    restartMenubarLaunchAgent(uid, plist);
     // Stamp the version we just installed so the upgrade self-heal can tell when
     // a later release ships a newer helper that needs reinstalling.
     try {

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

@@ -280,6 +280,11 @@ export declare function agentAutoLoadMetaSync(nameSetHash: string, bundles: Secr
  * per ~7d), so auto-caching is ON by default; opt out with
  * `secrets.agent.auto: false`. Best-effort; an unreadable meta reads as on. */
 export declare function secretsAgentAutoEnabled(): boolean;
+/** Default `sleepPersist` for a new unlock when `--durable` is not passed. OFF by
+ * default (the secure split default: survive restart, re-lock on sleep); set
+ * `secrets.agent.durable: true` in agents.yaml to make every unlock sleep-durable.
+ * Best-effort; an unreadable meta reads as off. */
+export declare function secretsAgentDurable(): boolean;
 /** Minimum / maximum bounds for the configurable hold window. A too-small value
  * would defeat the broker (constant re-prompts); a too-large one pins secrets in
  * memory far longer than intended. */

package/dist/lib/secrets/agent.js

@@ -34,6 +34,7 @@ import { isAlive } from '../platform/process.js';
 import { getKeychainHelperPath } from './install-helper.js';
 import { getCliVersion, getCliVersionFresh } from '../version.js';
 import { getCliLaunch } from '../cli-entry.js';
+import { rehydrateSessions, pruneSessionsOnSleep } from './session-store.js';
 /** Bumped when the wire protocol changes; a client that pings a mismatched
  * server kills and respawns it rather than talking a stale dialect. */
 const PROTOCOL_VERSION = 1;
@@ -93,6 +94,20 @@ export function shouldTeardownVersionSkewedBroker(realHeldBundles) {
 function onDarwin() {
     return process.platform === 'darwin';
 }
+/**
+ * Build the broker's in-memory store, REHYDRATED from the durable session store
+ * (session-store.ts) so an unlock survives a daemon restart / agents-cli upgrade.
+ * Expired sessions are dropped; `--durable` and default entries alike come back
+ * (SLEEP already pruned the non-durable ones from the keychain while the broker
+ * was alive). Empty off darwin or when nothing was held.
+ */
+function rehydrateStore(now = Date.now()) {
+    const store = new Map();
+    for (const { name, entry } of rehydrateSessions(now)) {
+        store.set(name, { bundle: entry.bundle, env: entry.env, expiresAt: entry.expiresAt });
+    }
+    return store;
+}
 /** Broker runtime dir under the regenerable cache, locked to the user (0700).
  * AGENTS_SECRETS_AGENT_DIR overrides the location — a test seam so the suite can
  * run a real broker on a temp socket without touching the user's real dir. */
@@ -442,7 +457,7 @@ export async function runSecretsAgent(opts = {}) {
             throw err;
         }
     }
-    const store = new Map();
+    const store = rehydrateStore();
     // emptySince tracks the last moment the store held something; the sweep exits
     // the process once it's been empty for IDLE_EXIT_MS so no idle broker lingers.
     let emptySince = Date.now();
@@ -589,6 +604,9 @@ export async function runSecretsAgent(opts = {}) {
             if (shouldWipeOnWatchEvent(chunk)) {
                 store.clear();
                 emptySince = Date.now();
+                // Split default: delete non-`--durable` durable sessions too, so a default
+                // unlock re-locks on sleep; `--durable` ones survive (session-store.ts).
+                pruneSessionsOnSleep();
             }
         });
         watcher.on('error', () => { watcher = null; });
@@ -627,7 +645,7 @@ export async function runSecretsAgent(opts = {}) {
 export async function startHostedBroker() {
     if (!onDarwin())
         return null;
-    const store = new Map();
+    const store = rehydrateStore();
     const sock = socketPath(); // agentDir() creates the 0700 dir as a side effect
     const handle = (req) => handleAgentRequest(store, req);
     const onConn = makeConnectionHandler(handle, readAgentToken);
@@ -651,8 +669,10 @@ export async function startHostedBroker() {
         watcher = spawn(getKeychainHelperPath(), ['watch-lock'], { stdio: ['ignore', 'pipe', 'ignore'] });
         watcher.stdout?.setEncoding('utf-8');
         watcher.stdout?.on('data', (chunk) => {
-            if (shouldWipeOnWatchEvent(chunk))
+            if (shouldWipeOnWatchEvent(chunk)) {
                 store.clear();
+                pruneSessionsOnSleep(); // split default — see runSecretsAgent's handler
+            }
         });
         watcher.on('error', () => { watcher = null; });
     }
@@ -912,6 +932,18 @@ export function secretsAgentAutoEnabled() {
         return true;
     }
 }
+/** Default `sleepPersist` for a new unlock when `--durable` is not passed. OFF by
+ * default (the secure split default: survive restart, re-lock on sleep); set
+ * `secrets.agent.durable: true` in agents.yaml to make every unlock sleep-durable.
+ * Best-effort; an unreadable meta reads as off. */
+export function secretsAgentDurable() {
+    try {
+        return readMeta().secrets?.agent?.durable === true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Minimum / maximum bounds for the configurable hold window. A too-small value
  * would defeat the broker (constant re-prompts); a too-large one pins secrets in
  * memory far longer than intended. */