@phnx-labs/agents-cli 1.20.55 → 1.20.57

package/dist/lib/daemon.js

@@ -306,6 +306,28 @@ export async function runDaemon() {
     catch (err) {
         log('ERROR', `Stray daemon reaper failed: ${err.message}`);
     }
+    // #416: host the secrets broker socket-first — before the scheduler and the
+    // heavy browser/session-sync services — so `agents secrets` resolves within
+    // ms of daemon start. Only host when no broker is already reachable, so we
+    // never orphan a live standalone broker's clients (that broker stays the
+    // server until it idle-exits or the daemon restarts). Best-effort: a failure
+    // here must not stop the daemon. Retiring the standalone launchd service is
+    // the follow-on (#416 step 2 / #417).
+    let hostedBroker = null;
+    try {
+        const { agentPing, startHostedBroker } = await import('./secrets/agent.js');
+        if ((await agentPing()).reachable) {
+            log('INFO', 'Secrets broker already running (standalone); daemon not hosting it');
+        }
+        else {
+            hostedBroker = await startHostedBroker();
+            if (hostedBroker)
+                log('INFO', 'Secrets broker hosted in daemon (socket-first)');
+        }
+    }
+    catch (err) {
+        log('WARN', `Secrets broker host skipped: ${err.message}`);
+    }
     const scheduler = new JobScheduler(async (config) => {
         log('INFO', `Triggering job '${config.name}' (agent: ${config.agent})`);
         try {
@@ -594,6 +616,7 @@ export async function runDaemon() {
         clearTimeout(tmuxReconcileKickoff);
         clearInterval(launchHealthInterval);
         clearTimeout(launchHealthKickoff);
+        hostedBroker?.close();
         removeDaemonPid();
         removeHeartbeat();
         process.exit(0);
@@ -712,28 +735,39 @@ Environment=PATH=/usr/local/bin:/usr/bin:/bin:${os.homedir()}/.nvm/versions/node
 [Install]
 WantedBy=default.target`;
 }
-export function getAgentsBinPath() {
+const BUN_VIRTUAL_ROOT = /[/\\]\$bunfs[/\\]root[/\\]/;
+function resolveBunStandaloneEntry(entry, execPath) {
+    if (!BUN_VIRTUAL_ROOT.test(entry))
+        return entry;
+    if (!execPath || BUN_VIRTUAL_ROOT.test(execPath) || !fs.existsSync(execPath)) {
+        throw new Error(`Cannot resolve agents CLI: Bun standalone executable not found at ${execPath || '(empty path)'}`);
+    }
+    return execPath;
+}
+export function getAgentsBinPath(argv1 = process.argv[1], execPath = process.execPath) {
     // Prefer the binary actively executing this code. `which agents` returns
     // whatever happens to be first on PATH, which means a side-by-side dev
     // build at ~/.local/bin would silently spawn the registry-installed
-    // daemon and run stale code. process.argv[1] is the absolute path of
-    // the JS entrypoint the user actually invoked.
-    const argv1 = process.argv[1];
-    if (argv1 && fs.existsSync(argv1)) {
+    // daemon and run stale code. For a JS install, process.argv[1] is the
+    // absolute entrypoint the user actually invoked. A Bun standalone instead
+    // exposes its embedded /$bunfs/root entry at argv[1] and its physical signed
+    // executable at process.execPath; Bun reports both as existing paths.
+    const runningEntry = argv1 ? resolveBunStandaloneEntry(argv1, execPath) : undefined;
+    if (runningEntry && fs.existsSync(runningEntry)) {
         // The package's browser/computer entrypoints are sibling shims without a
         // `daemon` command. A daemon started as their IPC side effect must launch
         // through the main agents entrypoint instead of replaying the shim path.
-        const entryName = path.basename(argv1);
+        const entryName = path.basename(runningEntry);
         const compiledShim = /^(browser|computer)\.(c|m)?js$/.test(entryName);
         const installedShim = /^(browser|computer)$/.test(entryName);
         if (compiledShim || installedShim) {
-            const agentsEntry = path.join(path.dirname(argv1), compiledShim ? 'index.js' : 'agents');
+            const agentsEntry = path.join(path.dirname(runningEntry), compiledShim ? 'index.js' : 'agents');
             if (!fs.existsSync(agentsEntry)) {
                 throw new Error(`Cannot start agents daemon: main CLI entry not found at ${agentsEntry}`);
             }
             return agentsEntry;
         }
-        return argv1;
+        return runningEntry;
     }
     try {
         return execFileSync('which', ['agents'], { encoding: 'utf-8' }).trim();
@@ -903,9 +937,30 @@ export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
     }
     return { command: agentsBin, args: ['daemon', '_run'] };
 }
+/**
+ * Build the argv to relaunch the `agents` CLI with the given subcommand args.
+ *
+ * Resolves the real on-disk binary via getAgentsBinPath(), then dispatches: a
+ * `.js` entry runs under node (`node <entry> …`), a native/compiled binary runs
+ * directly (`<bin> …`).
+ *
+ * Callers MUST route self-spawns through this rather than hand-rolling
+ * `[process.execPath, process.argv[1], …]`: under the compiled standalone binary
+ * (#315) `process.argv[1]` is the bun virtual entry `/$bunfs/root/agents`, so the
+ * hand-rolled form becomes `agents /$bunfs/root/agents …` → the CLI receives the
+ * bunfs path as a subcommand and dies with "unknown command '/$bunfs/root/agents'".
+ * getAgentsBinPath() resolves that virtual entry to the physical process.execPath.
+ */
+export function getAgentsInvocation(subArgs, agentsBin = getAgentsBinPath()) {
+    const resolvedBin = resolveBunStandaloneEntry(agentsBin, process.execPath);
+    if (/\.(c|m)?js$/.test(resolvedBin)) {
+        return { command: process.execPath, args: [resolvedBin, ...subArgs] };
+    }
+    return { command: resolvedBin, args: subArgs };
+}
 export function validateDaemonBinary(binPath) {
     const warnings = [];
-    if (/\/\$bunfs\/root\//.test(binPath)) {
+    if (BUN_VIRTUAL_ROOT.test(binPath)) {
         throw new Error(`Refusing to supervise daemon: resolved binary is a bun virtual path (${binPath}). ` +
             `Install agents globally (npm i -g @phnx-labs/agents-cli) and restart.`);
     }

package/dist/lib/hosts/passthrough.js

@@ -34,6 +34,7 @@ const REMOTE_PASSTHROUGH = {
     sync: { nonInteractive: ['--yes'] },
     teams: {},
     message: {},
+    routines: {},
 };
 /** `--no-tty` is stripped like the routing flags but carries no value. */
 const STRIP_SPECS = [...HOST_ROUTING_SPECS, { long: 'no-tty', takesValue: false }];
@@ -115,10 +116,13 @@ export async function maybeRunOnHost(command, allArgs) {
         process.exitCode = 1;
         return true;
     }
-    // `--devices` / `--hosts` fan out to every registered device locally; don't
-    // let a per-host passthrough turn it into a cascading remote fan-out.
-    const fleetFlag = allArgs.includes('--devices') || allArgs.includes('--hosts');
-    if (fleetFlag)
+    // `--hosts` is always a generic fleet flag — bail for every command so the
+    // local aggregator handles it. `--devices` is fan-out on most commands but
+    // a placement flag on `routines` (which devices may run the routine), so
+    // only exempt routines from the bail.
+    if (allArgs.includes('--hosts'))
+        return false;
+    if (allArgs.includes('--devices') && command !== 'routines')
         return false;
     const hostName = hostFlag ?? deviceFlag;
     if (!hostName)

package/dist/lib/migrate.d.ts

@@ -96,5 +96,14 @@ export declare function repairSelfReferentialBinShims(versionsRoot?: string, shi
  * the new name.
  */
 export declare function migrateExtrasExtrasToAgentsExtras(historyDir?: string): void;
+/**
+ * Rewrite every routine YAML that carries the legacy singular `device: <value>`
+ * field to the new plural `devices: [<value>]` format. Preserves all other
+ * fields. Idempotent: a routine that already has `devices:` (or neither field)
+ * is left untouched.
+ *
+ * Params default to the real routines dir; injectable for tests.
+ */
+export declare function migrateRoutineDeviceToDevices(routinesDir?: string): void;
 /** Run all idempotent migrations. Safe to call multiple times. */
 export declare function runMigration(): Promise<void>;

package/dist/lib/migrate.js

@@ -1885,6 +1885,52 @@ export function migrateExtrasExtrasToAgentsExtras(historyDir = HISTORY_DIR) {
         console.error(`Renamed extras-extras → agents-extras (dirs: ${renamedDirs}, known_marketplaces: ${rewroteKnown}, settings: ${rewroteSettings})`);
     }
 }
+/**
+ * Rewrite every routine YAML that carries the legacy singular `device: <value>`
+ * field to the new plural `devices: [<value>]` format. Preserves all other
+ * fields. Idempotent: a routine that already has `devices:` (or neither field)
+ * is left untouched.
+ *
+ * Params default to the real routines dir; injectable for tests.
+ */
+export function migrateRoutineDeviceToDevices(routinesDir) {
+    const dir = routinesDir ?? path.join(USER_DIR, 'routines');
+    if (!fs.existsSync(dir))
+        return;
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+    let migrated = 0;
+    for (const file of files) {
+        const filePath = path.join(dir, file);
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        let doc;
+        try {
+            doc = yaml.parse(raw);
+            if (!doc || typeof doc !== 'object')
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (!('device' in doc))
+            continue;
+        if ('devices' in doc) {
+            delete doc.device;
+            atomicWriteFileSync(filePath, yaml.stringify(doc));
+            continue;
+        }
+        const val = doc.device;
+        if (typeof val !== 'string' || !val.trim()) {
+            throw new Error(`${file}: legacy 'device' field is not a valid device name — repair the file and retry`);
+        }
+        delete doc.device;
+        doc.devices = [val.trim()];
+        atomicWriteFileSync(filePath, yaml.stringify(doc));
+        migrated++;
+    }
+    if (migrated > 0) {
+        console.error(`Migrated ${migrated} routine${migrated === 1 ? '' : 's'}: device → devices`);
+    }
+}
 /** Run all idempotent migrations. Safe to call multiple times. */
 export async function runMigration() {
     // MUST run first: every other migrator reads SYSTEM_DIR (the new path).
@@ -1937,6 +1983,8 @@ export async function runMigration() {
     // installed version-home. Runs after migrateRuntimeToHistory so the version
     // homes are at their canonical HISTORY_DIR location.
     migrateExtrasExtrasToAgentsExtras();
+    // Rewrite routine YAML files: singular `device:` -> plural `devices: []`.
+    migrateRoutineDeviceToDevices();
     // Symlink repair runs LAST so it can find the post-move version homes.
     repairAgentConfigSymlinks();
     // Repair self-referential node_modules/.bin/<cli> symlinks (the droid

package/dist/lib/routines.d.ts

@@ -61,14 +61,13 @@ export interface JobConfig {
     timezone?: string;
     repo?: string;
     /**
-     * Pin this routine to one machine. `~/.agents/routines/` is synced to every
-     * device via the user repo, so without a pin an enabled routine fires on
-     * EVERY machine running the scheduler. When set, only the device whose
-     * `machineId()` matches (normalized hostname, e.g. `yosemite-s0`) schedules,
-     * fires, catches up, or counts this job as overdue; everywhere else it is
-     * inert and `run` refuses with an `agents ssh` pointer.
+     * Fleet allowlist — restrict this routine to specific devices. When omitted
+     * or empty, the routine is unrestricted and fires on every device running the
+     * scheduler. When set, only devices whose `machineId()` matches any entry
+     * (via `normalizeHost`) schedule, fire, catch up, or count this job as
+     * overdue; everywhere else it is inert and `run` refuses with a pointer.
      */
-    device?: string;
+    devices?: string[];
     variables?: Record<string, string>;
     sandbox?: boolean;
     allow?: JobAllowConfig;
@@ -94,12 +93,31 @@ export interface RunMeta {
     exitCode: number | null;
 }
 /**
- * True when the job may execute on this machine: no `device` pin, or the pin
- * names this device. Both sides go through `normalizeHost` so `Yosemite-S0`,
- * `yosemite-s0.tailnet.ts.net`, and `yosemite-s0` all agree. Every fire path
- * (cron scheduler, webhook, catchup/overdue, manual run) gates on this.
+ * True when the job may execute on this machine: no `devices` allowlist (or
+ * empty), or the allowlist includes this device. Both sides go through
+ * `normalizeHost` so `Yosemite-S0`, `yosemite-s0.tailnet.ts.net`, and
+ * `yosemite-s0` all agree. Every fire path (cron scheduler, webhook,
+ * catchup/overdue, manual run) gates on this.
  */
-export declare function jobRunsOnThisDevice(config: Pick<JobConfig, 'device'>): boolean;
+export declare function jobRunsOnThisDevice(config: Pick<JobConfig, 'devices'>): boolean;
+/** Human presentation of a device-affinity mismatch for commands and runner. */
+export interface JobEligibilityResult {
+    /** Full human message, e.g. "Job 'NAME' can only run on: a, b". */
+    message: string;
+    /** One-line copy-paste suggestion, e.g. "agents routines run NAME --host a". */
+    suggestion: string;
+    /** Comma-separated allowed devices label, e.g. "a, b". */
+    allowedLabel: string;
+    /** First allowed device (normalized), useful for the suggested host. */
+    firstHost: string;
+}
+/**
+ * Return null when the job may run here; otherwise return a structured,
+ * human-friendly eligibility failure. Centralizes the message/suggestion
+ * construction so manual run, executeJob, and executeJobDetached stay in
+ * sync. Scheduler/webhook/overdue paths continue to use jobRunsOnThisDevice.
+ */
+export declare function checkJobDeviceEligibility(config: Pick<JobConfig, 'name' | 'devices'>): JobEligibilityResult | null;
 /**
  * List all job configs, scanning project > user routine dirs.
  * Project routines (`<project>/.agents/routines/`) shadow user routines of the
@@ -113,7 +131,12 @@ export declare function listJobs(cwd?: string): JobConfig[];
  * only resolve user routines.
  */
 export declare function readJob(name: string, cwd?: string): JobConfig | null;
-/** Write a job config to disk, omitting fields that match defaults. */
+/** Write a job config to disk, omitting fields that match defaults.
+ *
+ * Updates the one existing supported extension (.yml or .yaml) atomically.
+ * New routines are written as .yml. If both extensions exist for the same
+ * name, the write fails explicitly so we never choose or drop a sibling.
+ */
 export declare function writeJob(config: JobConfig): void;
 /** Delete a job config file by name. Returns true if the file existed. */
 export declare function deleteJob(name: string): boolean;

package/dist/lib/routines.js

@@ -12,6 +12,7 @@ import * as yaml from 'yaml';
 import { Cron } from 'croner';
 import { getRoutinesDir, getRunsDir, ensureAgentsDir, getProjectRoutinesDir } from './state.js';
 import { safeJoin } from './paths.js';
+import { atomicWriteFileSync } from './fs-atomic.js';
 import { ALL_AGENT_IDS } from './agents.js';
 import { machineId, normalizeHost } from './machine-id.js';
 /** Canonical set of accepted GitHub trigger events — single source for validation. */
@@ -42,15 +43,33 @@ export function normalizeTriggerEvent(input) {
     return aliases[key] ?? null;
 }
 /**
- * True when the job may execute on this machine: no `device` pin, or the pin
- * names this device. Both sides go through `normalizeHost` so `Yosemite-S0`,
- * `yosemite-s0.tailnet.ts.net`, and `yosemite-s0` all agree. Every fire path
- * (cron scheduler, webhook, catchup/overdue, manual run) gates on this.
+ * True when the job may execute on this machine: no `devices` allowlist (or
+ * empty), or the allowlist includes this device. Both sides go through
+ * `normalizeHost` so `Yosemite-S0`, `yosemite-s0.tailnet.ts.net`, and
+ * `yosemite-s0` all agree. Every fire path (cron scheduler, webhook,
+ * catchup/overdue, manual run) gates on this.
  */
 export function jobRunsOnThisDevice(config) {
-    if (!config.device)
+    if (!config.devices || config.devices.length === 0)
         return true;
-    return normalizeHost(config.device) === machineId();
+    const self = machineId();
+    return config.devices.some((d) => normalizeHost(d) === self);
+}
+/**
+ * Return null when the job may run here; otherwise return a structured,
+ * human-friendly eligibility failure. Centralizes the message/suggestion
+ * construction so manual run, executeJob, and executeJobDetached stay in
+ * sync. Scheduler/webhook/overdue paths continue to use jobRunsOnThisDevice.
+ */
+export function checkJobDeviceEligibility(config) {
+    if (jobRunsOnThisDevice(config))
+        return null;
+    const allowed = (config.devices ?? []).map((d) => normalizeHost(d));
+    const allowedLabel = allowed.join(', ');
+    const firstHost = allowed[0] ?? 'HOST';
+    const message = `Job '${config.name}' can only run on: ${allowedLabel}`;
+    const suggestion = `agents routines run ${config.name} --host ${firstHost}`;
+    return { message, suggestion, allowedLabel, firstHost };
 }
 /** Default values applied to every job config when fields are omitted. */
 const JOB_DEFAULTS = {
@@ -122,6 +141,11 @@ function readJobFile(filePath) {
         const parsed = yaml.parse(content);
         if (!parsed || typeof parsed !== 'object')
             return null;
+        // Fail closed on the legacy singular `device` key. A routine that still
+        // carries it after v12 startup migration is unmigrated state and must be
+        // treated as unavailable/inert rather than unrestricted.
+        if (Object.prototype.hasOwnProperty.call(parsed, 'device'))
+            return null;
         return {
             ...JOB_DEFAULTS,
             ...parsed,
@@ -132,11 +156,23 @@ function readJobFile(filePath) {
         return null;
     }
 }
-/** Write a job config to disk, omitting fields that match defaults. */
+/** Write a job config to disk, omitting fields that match defaults.
+ *
+ * Updates the one existing supported extension (.yml or .yaml) atomically.
+ * New routines are written as .yml. If both extensions exist for the same
+ * name, the write fails explicitly so we never choose or drop a sibling.
+ */
 export function writeJob(config) {
     ensureAgentsDir();
     const jobsDir = getRoutinesDir();
-    const filePath = safeJoin(jobsDir, config.name + '.yml');
+    const ymlPath = safeJoin(jobsDir, config.name + '.yml');
+    const yamlPath = safeJoin(jobsDir, config.name + '.yaml');
+    const ymlExists = fs.existsSync(ymlPath);
+    const yamlExists = fs.existsSync(yamlPath);
+    if (ymlExists && yamlExists) {
+        throw new Error(`Routine '${config.name}' has both .yml and .yaml files; resolve the ambiguity before editing.`);
+    }
+    const filePath = ymlExists ? ymlPath : yamlExists ? yamlPath : ymlPath;
     const output = { ...config };
     if (output.mode === 'auto')
         delete output.mode;
@@ -148,7 +184,10 @@ export function writeJob(config) {
         delete output.enabled;
     if (output.runOnce === false || output.runOnce === undefined)
         delete output.runOnce;
-    fs.writeFileSync(filePath, yaml.stringify(output), 'utf-8');
+    const devArr = output.devices;
+    if (!devArr || devArr.length === 0)
+        delete output.devices;
+    atomicWriteFileSync(filePath, yaml.stringify(output));
 }
 /** Delete a job config file by name. Returns true if the file existed. */
 export function deleteJob(name) {
@@ -232,8 +271,19 @@ export function validateJob(config) {
         }
     }
     if (config.device !== undefined) {
-        if (typeof config.device !== 'string' || config.device.trim() === '') {
-            errors.push('device must be a non-empty device name (as shown by `agents devices`, e.g. yosemite-s0)');
+        errors.push('singular "device" key is no longer supported — replace with devices: [<name>] (an array)');
+    }
+    if (config.devices !== undefined) {
+        if (!Array.isArray(config.devices)) {
+            errors.push('devices must be an array of device names (as shown by `agents devices`)');
+        }
+        else {
+            for (const d of config.devices) {
+                if (typeof d !== 'string' || d.trim() === '') {
+                    errors.push('each entry in devices must be a non-empty device name');
+                    break;
+                }
+            }
         }
     }
     return errors;

package/dist/lib/runner.js

@@ -17,7 +17,7 @@ import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { resolveJobPrompt, parseTimeout, writeRunMeta, getRunDir, } from './routines.js';
+import { resolveJobPrompt, parseTimeout, writeRunMeta, getRunDir, checkJobDeviceEligibility, } from './routines.js';
 import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
@@ -378,6 +378,10 @@ function spawnJobAttempt(cmd, env, attemptLogPath, timeoutMs, combinedLogPath) {
  * failover across healthy same-agent accounts (RUSH-1016).
  */
 export async function executeJob(config, deps) {
+    const eligibility = checkJobDeviceEligibility(config);
+    if (eligibility) {
+        throw new Error(eligibility.message);
+    }
     maybeRotate();
     const launch = await resolveRoutineLaunch(config);
     const primaryVersion = launch.chain[0]?.version ?? config.version;
@@ -537,6 +541,11 @@ export async function executeJob(config, deps) {
 }
 /** Spawn a job as a detached process and return immediately with run metadata. */
 export async function executeJobDetached(config) {
+    const eligibility = checkJobDeviceEligibility(config);
+    if (eligibility) {
+        process.stderr.write(`[agents] daemon: skipping '${config.name}' — ${eligibility.message}\n`);
+        throw new Error(eligibility.message);
+    }
     // Pre-flight: pick a healthy version/account so the daemon does not launch
     // into a credit-exhausted install. Detached cannot mid-run failover (no exit
     // wait); the next schedule tick re-selects if this attempt still fails.

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

@@ -172,6 +172,27 @@ export declare function shouldWipeOnWatchEvent(chunk: string): boolean;
 export declare function runSecretsAgent(opts?: {
     service?: boolean;
 }): Promise<void>;
+/**
+ * Host the secrets broker inside the always-on daemon (#416).
+ *
+ * Serves the SAME socket and wire protocol as the standalone `runSecretsAgent`
+ * — so every existing client (`agentGetSync`, `agentPing`, `agentAutoLoadSync`)
+ * keeps working unchanged, no PROTOCOL_VERSION bump — but it is daemon-safe:
+ *
+ *   - no pid-file single-instance guard (the daemon owns the instance);
+ *   - no `process.exit`, no SIGTERM/SIGINT handlers, no self-heal/idle-exit
+ *     (those would kill the daemon — the daemon is the always-on backbone and
+ *     manages its own version/lifecycle). The sweep only TTL-evicts.
+ *
+ * The caller (`runDaemon`) must only invoke this when NO broker is already
+ * reachable (ping first) — this function clears a stale socket before binding,
+ * so calling it while a live standalone broker holds the socket would orphan
+ * that broker's clients. Returns a handle the daemon closes on shutdown, or
+ * null off-darwin (nothing to broker without biometry).
+ */
+export declare function startHostedBroker(): Promise<{
+    close(): void;
+} | null>;
 /** True if a broker socket exists at all. Cheap; gates the sync read so the
  * never-unlocked path stays a single stat. */
 export declare function agentSocketExists(): boolean;
@@ -246,6 +267,12 @@ export declare function agentLock(name?: string): Promise<number>;
  * predates the server-side exclusion, so this keeps the internal entry from
  * surfacing in `agents secrets status` in that skew window. */
 export declare function agentStatus(): Promise<AgentStatusEntry[]>;
+/** Ping result: whether a broker is reachable + speaking our protocol, and the
+ * version of the code it's running (for staleness detection). */
+export declare function agentPing(): Promise<{
+    reachable: boolean;
+    cliVersion?: string;
+}>;
 /**
  * Ensure a broker is running and reachable. Returns true once the socket answers
  * a ping. macOS only.

package/dist/lib/secrets/agent.js

@@ -500,6 +500,132 @@ export async function runSecretsAgent(opts = {}) {
         watcher = null;
     }
 }
+/**
+ * Host the secrets broker inside the always-on daemon (#416).
+ *
+ * Serves the SAME socket and wire protocol as the standalone `runSecretsAgent`
+ * — so every existing client (`agentGetSync`, `agentPing`, `agentAutoLoadSync`)
+ * keeps working unchanged, no PROTOCOL_VERSION bump — but it is daemon-safe:
+ *
+ *   - no pid-file single-instance guard (the daemon owns the instance);
+ *   - no `process.exit`, no SIGTERM/SIGINT handlers, no self-heal/idle-exit
+ *     (those would kill the daemon — the daemon is the always-on backbone and
+ *     manages its own version/lifecycle). The sweep only TTL-evicts.
+ *
+ * The caller (`runDaemon`) must only invoke this when NO broker is already
+ * reachable (ping first) — this function clears a stale socket before binding,
+ * so calling it while a live standalone broker holds the socket would orphan
+ * that broker's clients. Returns a handle the daemon closes on shutdown, or
+ * null off-darwin (nothing to broker without biometry).
+ */
+export async function startHostedBroker() {
+    if (!onDarwin())
+        return null;
+    const store = new Map();
+    const sock = socketPath(); // agentDir() creates the 0700 dir as a side effect
+    const handle = (req) => handleAgentRequest(store, req);
+    const onConn = (conn) => {
+        conn.setEncoding('utf-8');
+        let buf = '';
+        conn.on('data', (chunk) => {
+            buf += chunk;
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (!line.trim())
+                    continue;
+                let resp;
+                try {
+                    resp = handle(JSON.parse(line));
+                }
+                catch (err) {
+                    resp = { ok: false, error: err.message };
+                }
+                conn.write(JSON.stringify(resp) + '\n');
+            }
+        });
+        conn.on('error', () => { });
+    };
+    // Bind race-safely: never clobber a LIVE standalone broker. Try to listen; if
+    // the socket is already bound, a broker raced us after runDaemon's ping — if
+    // it answers, back off and let it serve (return null); if it's a stale socket
+    // file with no live listener, reclaim it and retry once. (Unconditionally
+    // unlinking before bind — as an earlier draft did — could remove a live
+    // broker's socket in the sub-ms window after runDaemon's reachability check.)
+    const listenOnce = () => new Promise((resolve, reject) => {
+        const s = net.createServer(onConn);
+        s.once('error', (err) => {
+            if (err.code === 'EADDRINUSE')
+                resolve('inuse');
+            else
+                reject(err);
+        });
+        s.listen(sock, () => {
+            try {
+                fs.chmodSync(sock, 0o600);
+            }
+            catch { /* dir 0700 already gates it */ }
+            resolve(s);
+        });
+    });
+    let bound = await listenOnce();
+    if (bound === 'inuse') {
+        if ((await agentPing()).reachable)
+            return null; // a live broker holds it — don't clobber
+        try {
+            fs.unlinkSync(sock);
+        }
+        catch { /* gone */ }
+        bound = await listenOnce();
+        if (bound === 'inuse')
+            return null; // still contended — the standalone fallback covers it
+    }
+    const server = bound;
+    // TTL eviction ONLY. Unlike the standalone broker's sweep, there is no
+    // self-heal-exit or idle-exit here — the daemon is always-on and owns the
+    // upgrade/lifecycle path; a broker that called process.exit() would take the
+    // whole daemon down with it.
+    const sweepTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [name, e] of store)
+            if (now >= e.expiresAt)
+                store.delete(name);
+    }, SWEEP_INTERVAL_MS);
+    // Auto-lock on sleep, same as the standalone broker: the signed helper emits
+    // LOCK/SLEEP lines; wipe the in-memory store on a wipe-worthy event.
+    let watcher = null;
+    try {
+        watcher = spawn(getKeychainHelperPath(), ['watch-lock'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        watcher.stdout?.setEncoding('utf-8');
+        watcher.stdout?.on('data', (chunk) => {
+            if (shouldWipeOnWatchEvent(chunk))
+                store.clear();
+        });
+        watcher.on('error', () => { watcher = null; });
+    }
+    catch {
+        watcher = null;
+    }
+    return {
+        close() {
+            store.clear();
+            clearInterval(sweepTimer);
+            try {
+                watcher?.kill();
+            }
+            catch { /* already gone */ }
+            try {
+                server.close();
+            }
+            catch { /* not listening */ }
+            try {
+                fs.unlinkSync(sock);
+            }
+            catch { /* gone */ }
+        },
+    };
+}
 // ─── Client ──────────────────────────────────────────────────────────────────
 /** Open the socket, send one request, resolve the one response. Async path —
  * used by the unlock/lock/status commands, which already run in async actions. */
@@ -766,7 +892,7 @@ export async function agentStatus() {
 }
 /** Ping result: whether a broker is reachable + speaking our protocol, and the
  * version of the code it's running (for staleness detection). */
-async function agentPing() {
+export async function agentPing() {
     if (!agentSocketExists())
         return { reachable: false };
     const r = await request({ cmd: 'ping' });
@@ -802,6 +928,23 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
             return true;
         await teardownStaleBroker();
     }
+    // Path 0 (#416): prefer the always-on daemon — it hosts the broker socket
+    // (one supervised backbone rather than a separate launchd service). If
+    // bringing the daemon up makes the broker answer, we're done. Fall through to
+    // the standalone-service paths below when the daemon path isn't available
+    // (kept as a fallback until the standalone service is retired, #416 step 2).
+    try {
+        const { ensureDaemonStarted } = await import('../daemon.js');
+        if (ensureDaemonStarted()) {
+            const d0 = Date.now() + timeoutMs;
+            while (Date.now() < d0) {
+                if ((await agentPing()).reachable)
+                    return true;
+                await new Promise((r) => setTimeout(r, 120));
+            }
+        }
+    }
+    catch { /* daemon path unavailable — fall through to the standalone service */ }
     // Path 1: the persistent service. installSecretsAgentService is idempotent and
     // waits for the socket; for an already-installed service we kickstart and wait.
     try {