@phnx-labs/agents-cli 1.20.63 → 1.20.65

package/dist/lib/runner.js

@@ -23,6 +23,8 @@ import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { createTimer, maybeRotate, redactPrompt } from './events.js';
 import { normalizeMode, buildExecEnv, detectRateLimit, } from './exec.js';
+import { loadTask as loadHostTask } from './hosts/tasks.js';
+import { reconcileTask as reconcileHostTask } from './hosts/reconcile.js';
 import { backgroundSpawnOptions } from './platform/process.js';
 import { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js';
 import { getConfiguredRunStrategy, resolveRunVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
@@ -44,17 +46,20 @@ export function buildJobCommand(config, resolvedPrompt) {
         const cmd = ['agents', 'run', config.workflow, resolvedPrompt, '--mode', config.mode];
         return cmd;
     }
+    // Past the workflow branch this is an agent (or resume) job — command jobs never
+    // reach buildJobCommand (execute*Job branches out first), and validateJob guarantees agent.
+    const agent = config.agent;
     // Resume branch: reopen an EXISTING session via `agents run <agent> --resume <id>`
     // instead of starting fresh. The real session resumes with its full prior context
     // (index-based lookup, cwd-independent) and `resolvedPrompt` becomes its next turn —
     // so a self-scheduled wake (e.g. /hibernate) is handled by the session that scheduled
     // it, not a fresh, context-less agent that would refuse an "opaque" instruction.
     if (config.resume) {
-        return ['agents', 'run', config.agent, '--resume', config.resume, resolvedPrompt, '--mode', config.mode];
+        return ['agents', 'run', agent, '--resume', config.resume, resolvedPrompt, '--mode', config.mode];
     }
-    const template = AGENT_COMMANDS[config.agent];
+    const template = AGENT_COMMANDS[agent];
     if (!template) {
-        throw new Error(`Unsupported agent for daemon jobs: ${config.agent}`);
+        throw new Error(`Unsupported agent for daemon jobs: ${agent}`);
     }
     let cmd = template.map((part) => part.replace('{prompt}', resolvedPrompt));
     // Canonicalize mode (accepts legacy `full` as alias for `skip`).
@@ -155,10 +160,12 @@ export function buildJobCommand(config, resolvedPrompt) {
  * Reasoning level (config.config.reasoning) maps to per-agent flags via models.ts.
  */
 function appendModelAndReasoning(cmd, config) {
+    // Only called from buildJobCommand's agent path — config.agent is set.
+    const agent = config.agent;
     const model = config.config?.model;
     if (model) {
         if (config.version) {
-            const resolved = resolveModel(config.agent, config.version, model);
+            const resolved = resolveModel(agent, config.version, model);
             if (resolved.warning) {
                 process.stderr.write(`[agents] ${resolved.warning}\n`);
             }
@@ -170,7 +177,7 @@ function appendModelAndReasoning(cmd, config) {
     }
     const reasoning = config.config?.reasoning;
     if (reasoning) {
-        const flags = buildReasoningFlags(config.agent, reasoning);
+        const flags = buildReasoningFlags(agent, reasoning);
         if (flags.length > 0)
             cmd.push(...flags);
     }
@@ -178,6 +185,48 @@ function appendModelAndReasoning(cmd, config) {
 function generateRunId() {
     return new Date().toISOString().replace(/[:.]/g, '-');
 }
+/**
+ * Build the argv for a command-mode routine: run the shell string directly
+ * through the platform shell. No agent binary, no rotation, no sandbox.
+ */
+function buildShellCommand(command) {
+    return process.platform === 'win32'
+        ? ['cmd', '/c', command]
+        : ['/bin/sh', '-c', command];
+}
+/**
+ * Real (un-sandboxed) environment for a command routine. Command routines do
+ * `npm i -g` / `git pull` and need the actual $HOME / $PATH, not the sandbox
+ * overlay. Only TZ is injected when the routine pins a timezone.
+ */
+function commandSpawnEnv(config) {
+    const env = { ...process.env };
+    if (config.timezone)
+        env.TZ = config.timezone;
+    return env;
+}
+/** POSIX single-quote a string so it is safe to embed in a `/bin/sh -c` script. */
+function shSingleQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Detached command routines write their own exit code to `<runDir>/exit-code`
+ * (see the wrapper in executeCommandJobDetached). `monitorRunningJobs` reads it
+ * to recover the true terminal status when the daemon restarted between spawn and
+ * exit and so missed the in-process `child.on('exit')`. Returns null when the
+ * file is absent/unparseable (child killed or crashed before writing it).
+ */
+function readCommandExitCode(runDir) {
+    try {
+        const raw = fs.readFileSync(path.join(runDir, 'exit-code'), 'utf-8').trim();
+        if (!/^-?\d+$/.test(raw))
+            return null;
+        return parseInt(raw, 10);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Resolve the version/account chain for a routine the same way `agents run`
  * does: honor an explicit `version:` pin; otherwise use the configured run
@@ -191,6 +240,8 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
     if (config.workflow) {
         return { chain: [], rotation: null, pinned: false };
     }
+    // resolveRoutineLaunch is only called for agent jobs (workflow returns above;
+    // command jobs branch out of execute*Job before reaching this).
     const agent = config.agent;
     if (config.version) {
         const version = config.version;
@@ -399,6 +450,18 @@ export async function executeJob(config, deps) {
     if (eligibility) {
         throw new Error(eligibility.message);
     }
+    // `host:` placement — the job body runs on another machine over SSH; local
+    // version selection / sandbox / spawn do not apply. Sync callers (manual
+    // `routines run`, catchup) follow the remote run to completion.
+    if (config.host) {
+        return executeJobOnHost(config, { detached: false });
+    }
+    // Command-mode: run a plain shell command directly (no agent, no rotation,
+    // no pinning, no sandbox overlay). Reuses the run-record machinery so
+    // list/runs/overdue keep working.
+    if (config.command) {
+        return executeCommandJobForeground(config);
+    }
     maybeRotate();
     const launch = await resolveRoutineLaunch(config);
     const primaryVersion = launch.chain[0]?.version ?? config.version;
@@ -425,6 +488,7 @@ export async function executeJob(config, deps) {
         : { ...process.env };
     // Workflows run via `agents run <workflow>` which delegates to claude under the hood.
     // Use 'claude' as the effective agent for report extraction and metadata when workflow is set.
+    // (command jobs branched out earlier, so config.agent is set on the non-workflow path.)
     const effectiveAgent = config.workflow ? 'claude' : config.agent;
     const meta = {
         jobName: config.name,
@@ -561,6 +625,153 @@ export async function executeJob(config, deps) {
     timer.end({ status: 'failed', exitCode: 1, runId });
     return { meta, reportPath: null };
 }
+async function executeJobOnHost(config, opts) {
+    if (config.workflow) {
+        throw new Error(`Routine '${config.name}' runs a workflow bundle, which can't execute on a host yet — remove 'host:' or 'workflow:'.`);
+    }
+    if (config.loop) {
+        throw new Error(`Routine '${config.name}' uses 'loop:', which can't execute on a host yet — remove 'host:' or 'loop:'.`);
+    }
+    if (config.command) {
+        throw new Error(`Routine '${config.name}' uses 'command:', which can't execute on a host yet — remove 'host:' or 'command:'.`);
+    }
+    const { resolveHostRunTarget, dispatchPromptToHost } = await import('./hosts/run-target.js');
+    const host = await resolveHostRunTarget(config.host);
+    const timer = createTimer('agent.run', {
+        agent: config.agent,
+        jobName: config.name,
+        mode: config.mode,
+        host: host.name,
+        ...redactPrompt(config.prompt),
+        schedule: config.schedule,
+    });
+    const runId = generateRunId();
+    const runDir = getRunDir(config.name, runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    const meta = {
+        jobName: config.name,
+        runId,
+        agent: config.agent,
+        pid: null, // no local process — the run lives on the host
+        spawnedAt: Date.now(),
+        status: 'running',
+        startedAt: new Date().toISOString(),
+        completedAt: null,
+        exitCode: null,
+        host: host.name,
+    };
+    writeRunMeta(meta);
+    const { task, exitCode } = await dispatchPromptToHost(host, {
+        agent: config.agent,
+        prompt: resolveJobPrompt(config),
+        mode: normalizeMode(config.mode),
+        effort: config.effort,
+        model: config.config?.model,
+        timeout: config.timeout, // enforced by the REMOTE agents run
+        remoteCwd: config.remoteCwd,
+        name: config.name,
+        cwd: runDir,
+        follow: !opts.detached,
+    });
+    meta.hostTaskId = task.id;
+    // Sync path: a real exit code finalizes now. -1 (follow window closed) and
+    // the detached path leave the meta `running` for the monitor to reconcile.
+    if (!opts.detached && exitCode !== null && exitCode !== undefined && exitCode !== -1) {
+        meta.status = exitCode === 0 ? 'completed' : 'failed';
+        meta.exitCode = exitCode;
+        meta.completedAt = new Date().toISOString();
+    }
+    writeRunMeta(meta);
+    timer.end({ status: meta.status, exitCode: meta.exitCode ?? undefined, runId });
+    return { meta, reportPath: null };
+}
+/** Spawn a job as a detached process and return immediately with run metadata. */
+async function executeCommandJobForeground(config) {
+    const timer = createTimer('agent.run', {
+        jobName: config.name,
+        mode: config.mode,
+        schedule: config.schedule,
+    });
+    const runId = generateRunId();
+    const runDir = getRunDir(config.name, runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    const stdoutPath = path.join(runDir, 'stdout.log');
+    const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
+    const meta = {
+        jobName: config.name,
+        runId,
+        command: config.command,
+        pid: null,
+        spawnedAt: Date.now(),
+        status: 'running',
+        startedAt: new Date().toISOString(),
+        completedAt: null,
+        exitCode: null,
+    };
+    writeRunMeta(meta);
+    const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
+    const cmd = buildShellCommand(config.command);
+    const env = commandSpawnEnv(config);
+    process.stderr.write(`[agents] routine ${config.name}: running command\n`);
+    const result = await new Promise((resolve) => {
+        const child = spawn(cmd[0], cmd.slice(1), {
+            stdio: ['ignore', stdoutFd, stdoutFd],
+            ...backgroundSpawnOptions({ fdStdio: true }),
+            env,
+        });
+        meta.pid = child.pid || null;
+        writeRunMeta(meta);
+        let settled = false;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                fs.closeSync(stdoutFd);
+            }
+            catch { /* fd already closed */ }
+            resolve(r);
+        };
+        const timeoutTimer = setTimeout(() => {
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, 'SIGTERM');
+            }
+            catch { /* process already exited */ }
+            setTimeout(() => {
+                try {
+                    if (child.pid)
+                        process.kill(-child.pid, 'SIGKILL');
+                }
+                catch { /* process already exited */ }
+            }, 5000);
+            finish({ exitCode: null, status: 'timeout' });
+        }, timeoutMs);
+        child.on('exit', (code) => {
+            clearTimeout(timeoutTimer);
+            finish({ exitCode: code, status: code === 0 ? 'completed' : 'failed' });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeoutTimer);
+            finish({ exitCode: 1, status: 'failed', error: err.message });
+        });
+    });
+    meta.status = result.status;
+    meta.exitCode = result.exitCode ?? (result.status === 'completed' ? 0 : 1);
+    meta.completedAt = new Date().toISOString();
+    writeRunMeta(meta);
+    if (result.error) {
+        process.stderr.write(`[agents] routine ${config.name}: command spawn failed: ${result.error}\n`);
+    }
+    timer.end({
+        status: meta.status,
+        exitCode: meta.exitCode ?? undefined,
+        runId,
+        ...(result.error ? { error: result.error } : {}),
+    });
+    return { meta, reportPath: null };
+}
+/** Spawn a job as a detached process and return immediately with run metadata. */
 /** Spawn a job as a detached process and return immediately with run metadata. */
 export async function executeJobDetached(config) {
     const eligibility = checkJobDeviceEligibility(config);
@@ -568,6 +779,17 @@ export async function executeJobDetached(config) {
         process.stderr.write(`[agents] daemon: skipping '${config.name}' — ${eligibility.message}\n`);
         throw new Error(eligibility.message);
     }
+    // `host:` placement — dispatch over SSH and return; the monitor finalizes.
+    if (config.host) {
+        const { meta } = await executeJobOnHost(config, { detached: true });
+        return meta;
+    }
+    // Command-mode: fire a plain shell command detached (no agent, no rotation,
+    // no pinning, no sandbox overlay). Still writes a run record so the daemon,
+    // list/runs, and overdue tracking keep working.
+    if (config.command) {
+        return executeCommandJobDetached(config);
+    }
     // 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.
@@ -577,7 +799,7 @@ export async function executeJobDetached(config) {
     let cmd = buildJobCommand(config, resolvedPrompt);
     // workflow AND resume dispatch through `agents run` — never binary-pin them (pinning
     // rewrites cmd[0] to the agent binary → broken `<binary> run …`).
-    if (!dispatchesViaAgentsRun(config) && version) {
+    if (!dispatchesViaAgentsRun(config) && version && config.agent) {
         cmd = pinJobBinary(cmd, config.agent, version);
     }
     // Resume must run against the REAL home: `--resume <id>` resolves the session from
@@ -601,6 +823,7 @@ export async function executeJobDetached(config) {
                 e.TZ = config.timezone;
             return e;
         })()
+        // Non-command path only: config.agent is always set here (command/workflow branch earlier).
         : buildRoutineSpawnEnv(baseEnv, config.agent, version, config.timezone);
     const effectiveAgent = config.workflow ? 'claude' : config.agent;
     const meta = {
@@ -640,6 +863,74 @@ export async function executeJobDetached(config) {
     writeRunMeta(meta);
     return meta;
 }
+/**
+ * Detached (fire-and-forget) execution for a command-mode routine. Mirrors the
+ * agent detached flow: write an initial running record, spawn the shell command
+ * un-sandboxed, unref, then record the pid. The daemon does not wait for exit;
+ * `monitorRunningJobs` reaps the record on the next tick.
+ */
+function executeCommandJobDetached(config) {
+    const runId = generateRunId();
+    const runDir = getRunDir(config.name, runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    const stdoutPath = path.join(runDir, 'stdout.log');
+    const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
+    // Wrap the shell so the child records its own exit code to <runDir>/exit-code.
+    // The in-process `child.on('exit')` below writes the terminal record while the
+    // daemon is alive (the common case); the file lets monitorRunningJobs recover
+    // the real status if the daemon restarted between spawn and exit. (win32 relies
+    // on the exit event only.)
+    const exitCodePath = path.join(runDir, 'exit-code');
+    // Run the command in a SUBSHELL `( … )` so that if it calls `exit`, only the
+    // subshell exits — the outer shell still captures `$?` and writes the file.
+    const cmd = process.platform === 'win32'
+        ? buildShellCommand(config.command)
+        : ['/bin/sh', '-c',
+            `(\n${config.command}\n)\n__ac_rc=$?; printf '%s' "$__ac_rc" > ${shSingleQuote(exitCodePath)} 2>/dev/null; exit $__ac_rc`];
+    const env = commandSpawnEnv(config);
+    const meta = {
+        jobName: config.name,
+        runId,
+        command: config.command,
+        pid: null,
+        spawnedAt: Date.now(),
+        status: 'running',
+        startedAt: new Date().toISOString(),
+        completedAt: null,
+        exitCode: null,
+    };
+    const child = spawn(cmd[0], cmd.slice(1), {
+        stdio: ['ignore', stdoutFd, stdoutFd],
+        ...backgroundSpawnOptions({ fdStdio: true }),
+        env,
+    });
+    // Record the real terminal status ourselves — the daemon stays alive after this
+    // fire-and-forget call, so the exit event fires here. (monitorRunningJobs no
+    // longer force-fails command jobs; it reads exit-code only on the restart edge.)
+    let settled = false;
+    const settle = (status, exitCode) => {
+        if (settled)
+            return;
+        settled = true;
+        meta.status = status;
+        meta.exitCode = exitCode;
+        meta.completedAt = new Date().toISOString();
+        writeRunMeta(meta);
+    };
+    child.on('exit', (code) => settle(code === 0 ? 'completed' : 'failed', code ?? 1));
+    child.on('error', (err) => {
+        settle('failed', 1);
+        process.stderr.write(`[agents] daemon: command spawn failed for job "${config.name}": ${err.message}\n`);
+    });
+    child.unref();
+    try {
+        fs.closeSync(stdoutFd);
+    }
+    catch { /* fd already closed */ }
+    meta.pid = child.pid || null;
+    writeRunMeta(meta);
+    return meta;
+}
 function extractAndSaveReport(stdoutPath, agentType, runDir) {
     try {
         const report = extractReport(stdoutPath, agentType);
@@ -769,6 +1060,26 @@ function isPidOurs(pid, spawnedAt) {
         return true;
     }
 }
+/**
+ * Finalize one `host:`-placed run by healing its host-task sidecar against the
+ * remote `.exit` (lib/hosts/reconcile.ts). Mutates + persists the meta only
+ * when the sidecar reached a terminal state.
+ */
+function finalizeHostRun(meta) {
+    try {
+        const task = loadHostTask(meta.hostTaskId);
+        if (!task)
+            return;
+        const healed = reconcileHostTask(task);
+        if (healed.status !== 'completed' && healed.status !== 'failed')
+            return;
+        meta.status = healed.status;
+        meta.exitCode = healed.exitCode ?? (healed.status === 'completed' ? 0 : 1);
+        meta.completedAt = healed.finishedAt ?? new Date().toISOString();
+        writeRunMeta(meta);
+    }
+    catch { /* unreachable host or unreadable sidecar — retry next sweep */ }
+}
 /** Scan all runs marked "running" and finalize any whose process has exited. */
 export function monitorRunningJobs() {
     const runsDir = getRunsDir();
@@ -788,30 +1099,54 @@ export function monitorRunningJobs() {
                 const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
                 if (meta.status !== 'running')
                     continue;
+                // `host:`-placed run — no local pid to watch. Reconcile against the
+                // remote `.exit` (completion is confirmed, never guessed: an
+                // unreachable host leaves the run `running` for the next sweep).
+                if (meta.hostTaskId) {
+                    finalizeHostRun(meta);
+                    continue;
+                }
                 if (!meta.pid)
                     continue;
                 const runDirPath = path.join(jobRunsPath, runDirEntry.name);
                 const stdoutPath = path.join(runDirPath, 'stdout.log');
+                // Command-mode records carry no agent; there is no stream-json report to
+                // parse or extract. Reap them on pid liveness alone.
+                const isCommandRun = Boolean(meta.command) || !meta.agent;
                 const wallClockMs = Date.now() - Date.parse(meta.startedAt);
                 if (Number.isFinite(wallClockMs) && wallClockMs > MAX_WALL_CLOCK_MS) {
                     meta.status = 'timeout';
                     meta.completedAt = new Date().toISOString();
                     writeRunMeta(meta);
-                    extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
+                    if (!isCommandRun)
+                        extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
                     continue;
                 }
                 if (!isPidOurs(meta.pid, meta.spawnedAt)) {
-                    const inferred = inferFinalStatusFromLog(stdoutPath, meta.agent);
-                    if (inferred) {
-                        meta.status = inferred.status;
-                        meta.exitCode = inferred.exitCode;
+                    if (isCommandRun) {
+                        // Command routines normally record their own terminal status via
+                        // child.on('exit') (so this record would already be non-'running' and
+                        // skipped above). Reaching here means the daemon restarted mid-run and
+                        // missed the exit event — recover the true code from the exit-code file
+                        // the child wrote; its absence means the child was killed/crashed.
+                        const ec = readCommandExitCode(runDirPath);
+                        meta.status = ec === 0 ? 'completed' : 'failed';
+                        meta.exitCode = ec;
                     }
                     else {
-                        meta.status = 'failed';
+                        const inferred = inferFinalStatusFromLog(stdoutPath, meta.agent);
+                        if (inferred) {
+                            meta.status = inferred.status;
+                            meta.exitCode = inferred.exitCode;
+                        }
+                        else {
+                            meta.status = 'failed';
+                        }
                     }
                     meta.completedAt = new Date().toISOString();
                     writeRunMeta(meta);
-                    extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
+                    if (!isCommandRun)
+                        extractAndSaveReport(stdoutPath, meta.agent, runDirPath);
                 }
             }
             catch { /* corrupt or unreadable meta.json */ }

package/dist/lib/sandbox.d.ts

@@ -9,7 +9,15 @@
 import type { JobConfig } from './routines.js';
 /** Build a restricted environment for a sandboxed process, setting HOME to the overlay. */
 export declare function buildSpawnEnv(overlayHome: string, extraEnv?: Record<string, string>): Record<string, string>;
-/** Get the overlay HOME directory path for a named job. */
+/**
+ * Get the overlay HOME directory path for a named job.
+ *
+ * The job name originates from routine YAML (`name:` field or file basename),
+ * which can arrive from a synced user/system config repo. `safeJoin` contains
+ * it to a single segment beneath the routines dir so a crafted name such as
+ * `../../../..` cannot steer `prepareJobHome`/`cleanJobHome` (which does a
+ * recursive `rmSync`) at a path outside `~/.agents/routines`.
+ */
 export declare function getJobHomePath(name: string): string;
 /** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
 export declare function prepareJobHome(config: JobConfig): string;

package/dist/lib/sandbox.js

@@ -11,6 +11,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 import { getRoutinesDir, getUserAgentsDir } from './state.js';
+import { safeJoin } from './paths.js';
 import { createLink } from './platform/index.js';
 function resolveRealHome() {
     const home = os.homedir();
@@ -79,9 +80,17 @@ export function buildSpawnEnv(overlayHome, extraEnv) {
     }
     return env;
 }
-/** Get the overlay HOME directory path for a named job. */
+/**
+ * Get the overlay HOME directory path for a named job.
+ *
+ * The job name originates from routine YAML (`name:` field or file basename),
+ * which can arrive from a synced user/system config repo. `safeJoin` contains
+ * it to a single segment beneath the routines dir so a crafted name such as
+ * `../../../..` cannot steer `prepareJobHome`/`cleanJobHome` (which does a
+ * recursive `rmSync`) at a path outside `~/.agents/routines`.
+ */
 export function getJobHomePath(name) {
-    return path.join(getRoutinesDir(), name, 'home');
+    return path.join(safeJoin(getRoutinesDir(), name), 'home');
 }
 /** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
 export function prepareJobHome(config) {

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

@@ -207,6 +207,15 @@ export declare function agentGetSync(name: string): {
     bundle: SecretsBundle;
     env: Record<string, string>;
 } | null;
+/**
+ * Synchronous liveness check: is a broker actually LISTENING and answering (not
+ * just a lingering socket file)? Used to decide whether the auto-cache may take
+ * the synchronous warm path — a dead broker whose socket outlived it (crash,
+ * OOM, version-skew teardown) must NOT drag a foreground read through the
+ * worker's 20s cold-start budget. A stale socket refuses instantly, so this is
+ * fast in both the alive and dead cases. macOS only.
+ */
+export declare function agentReachableSync(): boolean;
 /**
  * Synchronously evict one bundle from the broker. Called after a mutating
  * keychain write (add / rotate / remove / rename / delete) so the broker never
@@ -237,25 +246,54 @@ 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;
+/** 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. */
+export declare const MIN_HOLD_MS: number;
+export declare const MAX_HOLD_MS: number;
+/**
+ * How long an unlocked / auto-cached bundle is held before the next read
+ * re-prompts. Defaults to DEFAULT_TTL_MS (7d); override with
+ * `secrets.agent.holdMs` (milliseconds) in agents.yaml — e.g. 86400000 for a 24h
+ * cap. Clamped to [MIN_HOLD_MS, MAX_HOLD_MS] so a typo can neither disable the
+ * hold nor pin a secret in memory indefinitely. Best-effort: an unreadable or
+ * non-numeric value falls back to the 7d default. Pure except for the meta read.
+ */
+export declare function secretsHoldMs(): number;
+/** Pure clamp for a configured `holdMs`: a positive finite number is bounded to
+ * [MIN_HOLD_MS, MAX_HOLD_MS]; anything else (absent, 0, negative, NaN, non-number)
+ * falls back to the 7d default. Exported for direct unit testing. */
+export declare function clampHoldMs(v: unknown): number;
 /**
  * Fire-and-forget: populate the broker with a freshly-resolved bundle so the
  * NEXT process reads it without a prompt. Used by the auto-cache path after a
- * real keychain read of a `daily`-policy bundle. Adds no latency to the caller
- * — it spawns a detached `secrets _agent-load` worker (passing the resolved env
- * over stdin, never argv) and returns immediately.
+ * real keychain read of a `daily`-policy bundle, so the NEXT concurrent read is
+ * silent. Env travels over stdin, never argv.
+ *
+ * Reliability (this is what makes `daily` actually "stick"): when a broker is
+ * ALREADY listening, warm it SYNCHRONOUSLY with a bounded wait so the bundle is
+ * held by the time this process exits. The old detached-only path lost the race
+ * under load — a short-lived reader (`agents secrets export`, a release-script
+ * loop) exited before the unref'd worker connected, so the cache silently never
+ * populated and every read re-prompted despite the `daily` policy. Only when the
+ * broker must COLD-START (no socket yet) do we fall back to the detached worker,
+ * so a first-ever read never blocks on a multi-second broker boot.
  *
- * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping with a
- * generous budget) rather than a tight inline retry loop: under heavy load the
- * broker is itself a cold-starting full CLI and can take several seconds to bind
- * the socket, so a short fixed budget would give up before it's ready and the
- * cache would silently never populate. Best-effort; never throws. macOS only.
+ * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping) rather
+ * than a tight inline retry loop. Best-effort; never throws. macOS only.
  */
 export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number): void;
 /**
  * Body of the hidden `secrets _agent-load` worker. Reads one `{name, bundle,
  * env, ttlMs}` payload from stdin, ensures the broker is up (robust, generous
- * budget), and loads the bundle into it. Detached from the originating read, so
- * its latency is invisible — which is why it can afford a long ensure budget.
+ * budget), and loads the bundle into it.
+ *
+ * Exit code is load-truthful: 0 ONLY when the bundle was actually loaded into a
+ * reachable broker; non-zero on any failure (malformed payload, broker couldn't
+ * be brought up, or the load transport failed). The synchronous caller
+ * (agentAutoLoadSync) relies on this to decide whether to skip the detached
+ * fallback — a bare "process exited 0" would otherwise be a false-positive
+ * success that silently reintroduces the very re-prompt storm this path fixes.
  */
 export declare function runAgentLoadFromStdin(): Promise<void>;
 /** Store a resolved bundle in the broker. Returns false on transport failure. */