@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/lib/{routines.d.ts → scheduling/routines.d.ts}

@@ -6,9 +6,16 @@
  * run metadata persistence, prompt variable expansion, and one-shot "at" time
  * scheduling.
  */
-import { type ResolvedExecutionContext, type ProjectResolution, type PlacementMode, type RoutineKind, type ContextFsProbe } from './routine-context.js';
-import type { AgentId } from './types.js';
-import type { LoopConfig } from './loop.js';
+import { type ResolvedExecutionContext, type ProjectResolution, type PlacementMode, type RoutineKind, type ContextFsProbe } from '../routine-context.js';
+import type { AgentId, RunStrategy } from '../types.js';
+import type { LoopConfig } from '../loop.js';
+import { JobScheduler } from '../scheduler.js';
+export declare function fireConditionLabel(job: JobConfig): string;
+export declare function nextRunForDisplay(job: JobConfig, scheduler: JobScheduler): Date | null;
+export declare function nextRunLabel(job: JobConfig, scheduler: JobScheduler, now: Date): string;
+export declare function localLatestRun(job: JobConfig): RunMeta | null;
+export declare function listJobsForDisplay(cwd?: string): JobConfig[];
+export declare function buildRoutineListJson(): Record<string, unknown>[];
 /** Tool/site/directory allow-list for sandboxed job execution. */
 export interface JobAllowConfig {
     tools?: string[];
@@ -17,7 +24,7 @@ export interface JobAllowConfig {
 }
 /**
  * Where a routine's job body executes when the daemon fires it.
- * Distinct from `devices` (which daemon may *fire*) and from the CLI `--host`
+ * Distinct from `devices` (which daemon may *fire*) and from the CLI `--device`
  * remote-management passthrough (manage routines *on* another machine).
  */
 export type HostStrategy = 'local' | 'host' | 'fleet' | 'cloud';
@@ -184,7 +191,7 @@ export interface JobConfig {
      * registered host, device, capability tag, or user@host) instead of locally.
      * Distinct from `devices`: `devices` says which daemon may FIRE the job,
      * `host` says where the dispatched run EXECUTES. CLI flag: `--run-on`
-     * (`--host` on routines commands already means "manage routines on that
+     * (`--device` on routines commands already means "manage routines on that
      * machine" via the remote passthrough).
      *
      * When `hostStrategy` is set, it owns placement semantics; `host` is then
@@ -200,7 +207,7 @@ export interface JobConfig {
      *              double-fire; the firing pin stays on `devices`)
      * - `cloud`  — dispatch via the agent's native cloud provider
      *
-     * CLI flag: `--placement` (not `--host`, which is the remote-management
+     * CLI flag: `--placement` (not `--device`, which is the remote-management
      * passthrough). Omitted strategy falls back to `host` when `host:` is set,
      * otherwise `local`.
      */
@@ -218,6 +225,16 @@ export interface JobConfig {
     allow?: JobAllowConfig;
     config?: Record<string, unknown>;
     version?: string;
+    /**
+     * Explicit per-routine version/account selection strategy — the same
+     * vocabulary as `agents run --strategy` (RUN_STRATEGIES). Overrides
+     * `run.<agent>.strategy` from the FIRING device's own agents.yaml
+     * (getConfiguredRunStrategy) so a routine's selection policy travels with the
+     * definition instead of depending on whichever box happens to fire it.
+     * Conflicts with `version:` (an exact pin leaves nothing to select) —
+     * validateJob rejects the pair.
+     */
+    strategy?: RunStrategy;
     /**
      * Pin this routine to a signed-in account by identity (its login email, or its
      * account key) instead of rotating. At launch it resolves to whichever
@@ -268,6 +285,29 @@ export interface JobConfig {
      * - Absent/empty — routine belongs to no project ("Operations" group).
      */
     projects?: string[];
+    /**
+     * Set only by `lib/monitors/dispatch.ts` on the one-off job it synthesizes for
+     * a monitor's `run` action. Such a job is NOT a routine: it has no definition
+     * file, `agents routines` never lists it, and its name can therefore never
+     * appear in this device's routine activation manifest
+     * (`~/.agents/devices/<machine>/agents.yaml` → `routines:`). Gating it on that
+     * manifest refused every monitor action fleet-wide with `wrong_owner` and an
+     * empty allowlist (RUSH-2681), so {@link jobRunsOnThisDevice} skips the
+     * manifest for it. Exactly-once ownership is already resolved BEFORE dispatch
+     * by the monitor's own `device:` pin (`monitorRunsOnThisDevice`,
+     * `lib/monitors/config.ts`) — re-gating here was double-gating on the wrong
+     * key.
+     *
+     * Deliberately narrow: a monitor's `routine` action fires a REAL routine, which
+     * keeps its activation gate, so a routine defined but not activated on this
+     * device is still refused.
+     *
+     * Runtime-only, enforced at both ends of the schema boundary: `writeJob`
+     * strips it, and `readJobFileResult` refuses a definition that carries it
+     * (a hand-authored one would otherwise fire on every box regardless of
+     * activation, since the daemon's load path never calls `validateJob`).
+     */
+    dispatchedBy?: 'monitor';
 }
 /**
  * Canonical form of a routine's `projects` field: drop non-string and empty
@@ -463,8 +503,13 @@ export declare function finalizeRunMeta(meta: RunMeta, status: RunMeta['status']
  * `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.
+ *
+ * A monitor-dispatched job ({@link JobConfig.dispatchedBy} `=== 'monitor'`) skips
+ * the routine activation manifest: it is not a routine, so its name can never be
+ * a member and the lookup could only ever answer "not activated here"
+ * (RUSH-2681). Its ownership was already decided by the monitor's `device:` pin.
  */
-export declare function jobRunsOnThisDevice(config: Pick<JobConfig, 'name' | 'devices'>): boolean;
+export declare function jobRunsOnThisDevice(config: Pick<JobConfig, 'name' | 'devices' | 'dispatchedBy'>): boolean;
 /**
  * The ONE device that owns a routine — the single daemon allowed to fire it.
  *
@@ -528,7 +573,7 @@ export declare function placementRequiresFiringPin(strategy: HostStrategy): bool
 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". */
+    /** One-line copy-paste suggestion, e.g. "agents routines run NAME --device a". */
     suggestion: string;
     /** Comma-separated allowed devices label, e.g. "a, b". */
     allowedLabel: string;
@@ -541,7 +586,7 @@ export interface JobEligibilityResult {
  * 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;
+export declare function checkJobDeviceEligibility(config: Pick<JobConfig, 'name' | 'devices' | 'dispatchedBy'>): JobEligibilityResult | null;
 /**
  * List all job configs, scanning project > user > system routine dirs.
  * Higher layers shadow lower ones of the same name (first-seen wins): a project

package/dist/lib/{routines.js → scheduling/routines.js}

@@ -10,17 +10,137 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { Cron } from 'croner';
-import { getRoutinesDir, getSystemRoutinesDir, getRunsDir, ensureAgentsDir, getProjectRoutinesDir } from './state.js';
+import { getRoutinesDir, getSystemRoutinesDir, getRunsDir, ensureAgentsDir, getProjectRoutinesDir } from '../state.js';
 import * as os from 'os';
-import { safeJoin, isSafeSegmentName } from './paths.js';
-import { isSafeProjectName, loadProjectDef, projectBasePath } from './projects.js';
-import { resolveRoutineExecutionContext, } from './routine-context.js';
-import { atomicWriteFileSync } from './fs-atomic.js';
-import { ALL_AGENT_IDS, ROUTINE_AGENT_IDS } from './agents.js';
-import { machineId, normalizeHost } from './machine-id.js';
-import { resolveActor } from './actor.js';
-import { percentile } from './percentile.js';
-import { enabledRoutineNames, replaceEnabledRoutines, routineEnabledOnThisDevice, setRoutineEnabledOnThisDevice, } from './routine-activation.js';
+import { safeJoin, isSafeSegmentName } from '../paths.js';
+import { isSafeProjectName, loadProjectDef, projectBasePath } from '../projects.js';
+import { resolveRoutineExecutionContext, } from '../routine-context.js';
+import { atomicWriteFileSync } from '../fs-atomic.js';
+import { ALL_AGENT_IDS, ROUTINE_AGENT_IDS } from '../agents.js';
+import { RUN_STRATEGIES } from '../accounting/rotate.js';
+import { machineId, normalizeHost } from '../machine-id.js';
+import { resolveActor } from '../actor.js';
+import { percentile } from '../percentile.js';
+import { enabledRoutineNames, devicesWithRoutineEnabled, replaceEnabledRoutines, routineEnabledOnThisDevice, setRoutineEnabledOnThisDevice, } from '../routine-activation.js';
+import { humanizeCron, humanizeNextRun } from '../routines-format.js';
+import { discoverProjectRoutines } from '../routines-project.js';
+import { listProjectDefs } from '../projects.js';
+import { monitorRunningJobs } from '../runner.js';
+import { JobScheduler } from '../scheduler.js';
+import { detectOverdueJobs } from '../overdue.js';
+export function fireConditionLabel(job) {
+    if (job.schedule)
+        return humanizeCron(job.schedule, job.timezone);
+    if (job.trigger) {
+        if (job.trigger.type === 'github_event') {
+            const scope = job.trigger.repo
+                ? ` (${job.trigger.repo}${job.trigger.branch ? `@${job.trigger.branch}` : ''})`
+                : '';
+            const filters = [
+                job.trigger.action ? `action=${job.trigger.action}` : null,
+                job.trigger.label ? `label=${job.trigger.label}` : null,
+            ].filter(Boolean).join(', ');
+            return `on github:${job.trigger.event}${scope}${filters ? ` (${filters})` : ''}`;
+        }
+        const filters = [
+            job.trigger.action ? `action=${job.trigger.action}` : null,
+            job.trigger.teamKey ? `team=${job.trigger.teamKey}` : null,
+            job.trigger.label ? `label=${job.trigger.label}` : null,
+            job.trigger.stateTo ? `stateTo=${job.trigger.stateTo}` : null,
+            job.trigger.stateFrom ? `stateFrom=${job.trigger.stateFrom}` : null,
+        ].filter(Boolean).join(', ');
+        return `on linear:${job.trigger.event}${filters ? ` (${filters})` : ''}`;
+    }
+    return '-';
+}
+export function nextRunForDisplay(job, scheduler) {
+    if (isPastOneShotRoutine(job))
+        return null;
+    return scheduler.getNextRun(job.name);
+}
+export function nextRunLabel(job, scheduler, now) {
+    if (isPastOneShotRoutine(job))
+        return 'expired';
+    return humanizeNextRun(scheduler.getNextRun(job.name) ?? null, now, job.timezone);
+}
+export function localLatestRun(job) {
+    return jobRunsOnThisDevice(job) ? getLatestRun(job.name) : null;
+}
+export function listJobsForDisplay(cwd) {
+    const jobs = listJobs(cwd);
+    const seen = new Set(jobs.map((j) => j.name));
+    for (const discovered of discoverProjectRoutines()) {
+        if (seen.has(discovered.name))
+            continue;
+        seen.add(discovered.name);
+        jobs.push(discovered.config);
+    }
+    return jobs;
+}
+export function buildRoutineListJson() {
+    try {
+        monitorRunningJobs();
+    }
+    catch { /* best-effort orphan reap */ }
+    const jobs = listJobsForDisplay(process.cwd());
+    if (jobs.length === 0)
+        return [];
+    const scheduler = new JobScheduler(async () => { });
+    scheduler.loadAll();
+    try {
+        const overdueSet = new Set();
+        try {
+            for (const job of detectOverdueJobs())
+                overdueSet.add(job.name);
+        }
+        catch {
+            // Best-effort indicator; never block the list on detection errors.
+        }
+        const now = new Date();
+        const knownProjectNames = new Set(listProjectDefs().map((project) => project.name));
+        return jobs.map((job) => {
+            const latestRun = localLatestRun(job);
+            const enabledDevices = devicesWithRoutineEnabled(job.name);
+            return {
+                name: job.name,
+                agent: job.agent ?? null,
+                workflow: job.workflow ?? null,
+                command: job.command ?? null,
+                repo: job.repo ?? null,
+                schedule: job.schedule ?? null,
+                scheduleHuman: fireConditionLabel(job),
+                trigger: job.trigger ?? null,
+                timezone: job.timezone ?? null,
+                devices: enabledDevices,
+                enabledDevices,
+                host: job.host ?? null,
+                hostStrategy: resolveHostStrategy(job),
+                source: job.source ?? null,
+                sourceRepo: job.source?.repo ?? job.repo ?? null,
+                sourceBranch: job.source?.branch ?? null,
+                runOnce: Boolean(job.runOnce),
+                catchup: job.catchup !== false,
+                oneShot: isOneShotRoutine(job),
+                expired: isPastOneShotRoutine(job, now),
+                runsHere: jobRunsOnThisDevice(job),
+                enabled: job.enabled,
+                overdue: overdueSet.has(job.name),
+                nextRun: nextRunForDisplay(job, scheduler)?.toISOString() ?? null,
+                nextRunHuman: nextRunLabel(job, scheduler, now),
+                lastStatus: latestRun?.status ?? null,
+                exitCode: latestRun?.exitCode ?? null,
+                failureReason: latestRun?.errorMessage ?? null,
+                lastRunStartedAt: latestRun?.startedAt ?? null,
+                lastRunCompletedAt: latestRun?.completedAt ?? null,
+                projects: job.projects ?? [],
+                projectGroup: computeProjectGroup(job.projects, knownProjectNames),
+            };
+        });
+    }
+    finally {
+        scheduler.stopAll();
+    }
+}
 export const HOST_STRATEGIES = ['local', 'host', 'fleet', 'cloud'];
 /** Canonical set of accepted GitHub trigger events — single source for validation. */
 export const GITHUB_TRIGGER_EVENTS = [
@@ -230,11 +350,18 @@ export function finalizeRunMeta(meta, status, exitCode, opts) {
  * `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.
+ *
+ * A monitor-dispatched job ({@link JobConfig.dispatchedBy} `=== 'monitor'`) skips
+ * the routine activation manifest: it is not a routine, so its name can never be
+ * a member and the lookup could only ever answer "not activated here"
+ * (RUSH-2681). Its ownership was already decided by the monitor's `device:` pin.
  */
 export function jobRunsOnThisDevice(config) {
-    const activated = routineEnabledOnThisDevice(config.name);
-    if (activated !== null)
-        return activated;
+    if (config.dispatchedBy !== 'monitor') {
+        const activated = routineEnabledOnThisDevice(config.name);
+        if (activated !== null)
+            return activated;
+    }
     const owner = routineOwnerDevice(config);
     // Unrestricted: no pin means fleet-wide by design (`watchdog`, `check-updates`).
     if (owner === null)
@@ -346,7 +473,7 @@ export function checkJobDeviceEligibility(config) {
     // refuse the run for exactly the same reason.
     const firstHost = routineOwnerDevice(config) ?? allowed[0] ?? 'HOST';
     const message = `Job '${config.name}' can only run on: ${allowedLabel}`;
-    const suggestion = `agents routines run ${config.name} --host ${firstHost}`;
+    const suggestion = `agents routines run ${config.name} --device ${firstHost}`;
     return { message, suggestion, allowedLabel, firstHost };
 }
 /** Default values applied to every job config when fields are omitted. */
@@ -499,6 +626,18 @@ export function readJobFileResult(filePath) {
         && !Array.isArray(parsed.devices)) {
         return { config: null, problem: '`devices:` must be a list — routine is inert' };
     }
+    // Fail closed on `dispatchedBy`. It is a runtime-only marker set by
+    // lib/monitors/dispatch.ts on a job that has no definition file, and it makes
+    // `jobRunsOnThisDevice` SKIP this device's routine activation manifest. A
+    // routine YAML carrying it would therefore fire on every box regardless of
+    // activation, on every path (scheduler, overdue, webhook) — the same
+    // unrestricted-and-silent outcome the `devices:` guard above exists to
+    // prevent, and the daemon's load path never calls validateJob. It is never
+    // written back (writeJob deletes it), so its presence here means hand-authored
+    // state, not drift.
+    if (Object.prototype.hasOwnProperty.call(parsed, 'dispatchedBy')) {
+        return { config: null, problem: '`dispatchedBy:` is a runtime-only monitor marker, not a routine field — routine is inert' };
+    }
     return {
         config: {
             ...JOB_DEFAULTS,
@@ -556,6 +695,10 @@ export function writeJob(config) {
     if (output.catchup === true || output.catchup === undefined)
         delete output.catchup;
     delete output.devices;
+    // Runtime-only monitor marker — a definition on disk must never carry it (see
+    // the read-side guard in readJobFileResult), so strip it at the one schema
+    // boundary rather than trusting every caller.
+    delete output.dispatchedBy;
     // Persist projects in canonical form: deduplicated, first-seen order, field
     // omitted when nothing survives. This is the schema boundary, so a routine
     // written from any path (add, edit, enable/disable re-write) lands canonical
@@ -739,6 +882,17 @@ export function validateJob(config) {
             errors.push(`resume is only supported for agents with native --resume (${RESUMABLE_AGENTS.join(', ')}); got '${config.agent}'`);
         }
     }
+    if (config.strategy !== undefined) {
+        if (!RUN_STRATEGIES.includes(config.strategy)) {
+            errors.push(`strategy must be one of: ${RUN_STRATEGIES.join(', ')}`);
+        }
+        if (!hasAgent) {
+            errors.push('strategy only applies to agent routines (drop it for workflow/command routines)');
+        }
+        if (config.version) {
+            errors.push(`strategy ${config.strategy} conflicts with version ${config.version} — an exact pin leaves nothing to select; drop strategy or the version pin`);
+        }
+    }
     if (config.mode && !['plan', 'edit', 'auto', 'skip', 'full'].includes(config.mode)) {
         errors.push("mode must be plan, edit, auto, or skip ('full' accepted as alias for skip)");
     }
@@ -773,6 +927,11 @@ export function validateJob(config) {
     if (strategy === 'host' && (!config.host || config.host.trim() === '')) {
         errors.push("hostStrategy: host requires host: (set via --run-on or host: in YAML)");
     }
+    // `host: auto` is fire-time fleet placement (resolveDeviceAuto), never a
+    // literal SSH target — it is only meaningful under hostStrategy: fleet.
+    if (config.host === 'auto' && strategy !== 'fleet') {
+        errors.push("host: auto requires hostStrategy: fleet (set via --run-on auto) — 'auto' is a fire-time device pick, not a machine name");
+    }
     // Remote placement (host/fleet/cloud) can't carry workflow/loop/command yet —
     // those live on the firing machine.
     if (strategy === 'host' || strategy === 'fleet' || strategy === 'cloud') {

package/dist/lib/secrets/agent.js

@@ -1439,7 +1439,7 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
         // hosts it and it holds no unlocks. Evicting a daemon-hosted broker orphans
         // the daemon's socket and starts the Touch ID storm — see
         // shouldClientEvictSkewedBroker.
-        const { isDaemonRunning } = await import('../daemon.js');
+        const { isDaemonRunning } = await import('../daemon/daemon.js');
         if (!shouldClientEvictSkewedBroker(isDaemonRunning(), (await agentStatus()).length))
             return true;
         await teardownStaleBroker();
@@ -1454,7 +1454,7 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
     // backbone rather than a separate launchd service. If bringing the daemon up
     // makes the broker answer, we're done.
     try {
-        const { ensureDaemonStarted } = await import('../daemon.js');
+        const { ensureDaemonStarted } = await import('../daemon/daemon.js');
         if (ensureDaemonStarted()) {
             const d0 = Date.now() + timeoutMs;
             while (Date.now() < d0) {

package/dist/lib/secrets/audit.js

@@ -33,7 +33,7 @@
  *                         underlying resolve emits its own `secrets.get`.
  *  - `secrets.view`     — a bundle's (masked) metadata was inspected via `view`.
  */
-import { emit } from '../events.js';
+import { emit } from '../feed/events.js';
 import { recordSecretUsage } from './usage-db.js';
 /**
  * Map each audit event onto the usage-DB kind it is counted as. `secrets.get` is

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

@@ -14,7 +14,7 @@
  *    bytes land. A file-backed bundle is discovered by the presence of its
  *    metadata item in the file store.
  *  - `vault`: a single age-encrypted ~/.agents/vault.age file unlocked by
- *    `agents login`; intended for user-managed cross-machine file sync.
+ *    `agents secrets vault unlock`; intended for user-managed cross-machine file sync.
  *
  * Server-backed cross-machine sync is handled by src/lib/secrets/sync.ts via
  * an explicit encrypted export/import flow; the bundle layer also supports the
@@ -281,13 +281,13 @@ export declare function filterAgentHitBySubsetAndExpiry(hit: {
     env: Record<string, string>;
 };
 /**
- * Guard for remote-bundle callers (`bundle@host` / `--host`) — the SSH
+ * Guard for remote-bundle callers (`bundle@host` / `--device`) — the SSH
  * resolver in `remoteResolveEnv` does not thread --keys or --allow-expired
  * yet. Silently applying them would inject the full remote env or an expired
  * value, defeating the least-privilege intent, so we fail loud.
  *
  * Exported so `agents run --secrets bundle@host` and `agents secrets exec
- * --host` share the exact same error text; the tests exercise this helper
+ * --device` share the exact same error text; the tests exercise this helper
  * directly instead of driving the whole CLI.
  */
 export declare function assertRemoteBundleFlagsUnsupported(bundleName: string, host: string, opts: {
@@ -305,7 +305,7 @@ export declare function resolveBundleEnv(bundle: SecretsBundle, _opts?: ResolveB
  * path in index.ts can share it without a bundles↔index import cycle. See that
  * module for the full contract.
  */
-export { isHeadlessSecretsContext } from './headless.js';
+export { isHeadlessSecretsContext, isAgentInvocationContext } from './headless.js';
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
  *

package/dist/lib/secrets/bundles.js

@@ -14,7 +14,7 @@
  *    bytes land. A file-backed bundle is discovered by the presence of its
  *    metadata item in the file store.
  *  - `vault`: a single age-encrypted ~/.agents/vault.age file unlocked by
- *    `agents login`; intended for user-managed cross-machine file sync.
+ *    `agents secrets vault unlock`; intended for user-managed cross-machine file sync.
  *
  * Server-backed cross-machine sync is handled by src/lib/secrets/sync.ts via
  * an explicit encrypted export/import flow; the bundle layer also supports the
@@ -27,7 +27,7 @@ import * as yaml from 'yaml';
 import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, isKeychainBackendOverridden, keychainServiceAlias, keychainUsesFileFallback, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
 import { fileStore } from './filestore.js';
 import { getVaultSession, vaultDeleteItem, vaultExists, vaultGetItems, vaultGetItem, vaultHasItem, vaultListItems, vaultSetItems, vaultSetItem, } from './vault.js';
-import { emit } from '../events.js';
+import { emit } from '../feed/events.js';
 import { emitSecretAudit } from './audit.js';
 import { readMeta, getHelpersDir } from '../state.js';
 import { assertNameActiveInResourceProfile, filterNamesForActiveResourceProfile } from '../resource-profiles.js';
@@ -111,7 +111,7 @@ export function bundleBackend(name) {
 function assertVaultBackendUsable(name) {
     if (getVaultSession().loggedIn)
         return;
-    throw new Error(`Synced bundle '${name}' needs an active login. Run: agents login`);
+    throw new Error(`Synced bundle '${name}' needs an active login. Run: agents secrets vault unlock`);
 }
 /** Allowed values for a secret's `type` metadata field. */
 export const SECRET_TYPES = [
@@ -280,7 +280,7 @@ export function readBundle(name) {
             throw new BundleUndecryptableError(`Bundle '${name}': failed to decrypt — wrong AGENTS_SECRETS_PASSPHRASE or tampered file store. (${err.message})`);
         }
         if (vaultExists() && !getVaultSession().loggedIn) {
-            throw new Error(`Synced secrets are locked. Run: agents login`);
+            throw new Error(`Synced secrets are locked. Run: agents secrets vault unlock`);
         }
         // Distinguish a genuinely-absent bundle from a present-but-unreadable one
         // (a locked login keychain, or a legacy ACL'd metadata item before first
@@ -1065,13 +1065,13 @@ export function filterAgentHitBySubsetAndExpiry(hit, opts) {
     return { bundle: hit.bundle, env };
 }
 /**
- * Guard for remote-bundle callers (`bundle@host` / `--host`) — the SSH
+ * Guard for remote-bundle callers (`bundle@host` / `--device`) — the SSH
  * resolver in `remoteResolveEnv` does not thread --keys or --allow-expired
  * yet. Silently applying them would inject the full remote env or an expired
  * value, defeating the least-privilege intent, so we fail loud.
  *
  * Exported so `agents run --secrets bundle@host` and `agents secrets exec
- * --host` share the exact same error text; the tests exercise this helper
+ * --device` share the exact same error text; the tests exercise this helper
  * directly instead of driving the whole CLI.
  */
 export function assertRemoteBundleFlagsUnsupported(bundleName, host, opts, flagLabels) {
@@ -1211,7 +1211,7 @@ export function resolveBundleEnv(bundle, _opts = {}) {
  * path in index.ts can share it without a bundles↔index import cycle. See that
  * module for the full contract.
  */
-export { isHeadlessSecretsContext } from './headless.js';
+export { isHeadlessSecretsContext, isAgentInvocationContext } from './headless.js';
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
  *
@@ -1365,7 +1365,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     const json = metaFetched.get(metaItem);
     if (json === undefined) {
         if (vaultExists() && !getVaultSession().loggedIn) {
-            throw new Error(`Synced secrets are locked. Run: agents login`);
+            throw new Error(`Synced secrets are locked. Run: agents secrets vault unlock`);
         }
         throw new Error(`Secrets bundle '${name}' not found.`);
     }

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

@@ -25,3 +25,19 @@
  * the per-caller broker-only pattern used across the headless secrets readers.
  */
 export declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/**
+ * True when this process runs structurally inside a coding-agent session: any
+ * `agents run` launch (AGENTS_RUNTIME / AGENT_SESSION_ID ride the child env —
+ * exec.ts buildExecEnv — and are inherited by every shell the agent spawns), or
+ * a harness's own tool shell launched outside agents-cli (Claude Code stamps
+ * CLAUDECODE on its Bash tool).
+ *
+ * Distinct from isHeadlessSecretsContext above on both axes: it is
+ * platform-independent (no biometry involved), and a TTY does not clear it (an
+ * agent inside tmux has one). Its job is the materialization boundary, not the
+ * prompt boundary: a command that would PRINT a plaintext value refuses under
+ * an agent, because anything printed lands in the agent's context and session
+ * transcript. The agent path to secret values is injection — `secrets exec`,
+ * `run --secrets` — which places them only in a child process env.
+ */
+export declare function isAgentInvocationContext(env?: NodeJS.ProcessEnv): boolean;

package/dist/lib/secrets/headless.js

@@ -33,3 +33,24 @@ export function isHeadlessSecretsContext(env = process.env, platform = process.p
         return true;
     return false;
 }
+/**
+ * True when this process runs structurally inside a coding-agent session: any
+ * `agents run` launch (AGENTS_RUNTIME / AGENT_SESSION_ID ride the child env —
+ * exec.ts buildExecEnv — and are inherited by every shell the agent spawns), or
+ * a harness's own tool shell launched outside agents-cli (Claude Code stamps
+ * CLAUDECODE on its Bash tool).
+ *
+ * Distinct from isHeadlessSecretsContext above on both axes: it is
+ * platform-independent (no biometry involved), and a TTY does not clear it (an
+ * agent inside tmux has one). Its job is the materialization boundary, not the
+ * prompt boundary: a command that would PRINT a plaintext value refuses under
+ * an agent, because anything printed lands in the agent's context and session
+ * transcript. The agent path to secret values is injection — `secrets exec`,
+ * `run --secrets` — which places them only in a child process env.
+ */
+export function isAgentInvocationContext(env = process.env) {
+    return Boolean(env.AGENTS_RUNTIME ||
+        env.AGENT_SESSION_ID ||
+        env.AGENTS_SESSION_ID ||
+        env.CLAUDECODE);
+}

package/dist/lib/secrets/index.js

@@ -73,7 +73,7 @@ function spawnKeychainHelper(bin, args, opts, timeoutMs) {
     if (keychainDaemonBootEnabled && !keychainDaemonBootAttempted) {
         keychainDaemonBootAttempted = true;
         // Fire-and-forget: daemon start must not block the foreground secrets op.
-        import('../daemon.js')
+        import('../daemon/daemon.js')
             .then(({ ensureDaemonStarted }) => ensureDaemonStarted())
             .catch(() => { });
     }

package/dist/lib/secrets/list-filter.d.ts

@@ -1,7 +1,7 @@
 /**
  * Filters for `agents secrets list`.
  *
- * The listing had no filtering at all: `--host`/`--device` pick a machine and
+ * The listing had no filtering at all: `--device`/`--device` pick a machine and
  * `--json` picks a format, but nothing selected over the bundles themselves. On
  * a fleet with fifty-odd bundles the answerable questions — which ones read with
  * no Touch ID at all, which hold a raw literal, which have already expired, what

package/dist/lib/secrets/list-filter.js

@@ -1,7 +1,7 @@
 /**
  * Filters for `agents secrets list`.
  *
- * The listing had no filtering at all: `--host`/`--device` pick a machine and
+ * The listing had no filtering at all: `--device`/`--device` pick a machine and
  * `--json` picks a format, but nothing selected over the bundles themselves. On
  * a fleet with fifty-odd bundles the answerable questions — which ones read with
  * no Touch ID at all, which hold a raw literal, which have already expired, what
@@ -17,7 +17,7 @@
  * unknown value is a loud error naming the valid set (never a silent ignore),
  * and every axis narrows independently so they AND-compose.
  */
-import { parseCommaSeparatedList } from '../../commands/utils.js';
+import { parseCommaSeparatedList } from '../format.js';
 // From the leaf module, NOT discover.js — the latter imports `../sqlite.js`, so
 // reaching through it for one parser would pull node:sqlite into every `agents
 // secrets` invocation and print Node's SQLite ExperimentalWarning on stderr.

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

@@ -31,7 +31,7 @@ export interface PushBundleOptions {
      * what pushed operators toward exporting the master key fleet-wide (RUSH-1968).
      */
     passphrase?: string;
-    /** Label for the audit trail — `export --host` vs `fleet apply`. */
+    /** Label for the audit trail — `export --device` vs `fleet apply`. */
     operation: string;
     /** Preserve an automation account's permanent prompt-free policy remotely. */
     policyNever?: boolean;