@phnx-labs/agents-cli 1.22.39 → 1.22.40

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: {

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) {
@@ -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/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;

package/dist/lib/secrets/push.js

@@ -1,9 +1,9 @@
 /**
  * Push one bundle's values to a remote host over SSH — the provisioning
- * primitive behind `agents secrets export --host` and, from RUSH-1968, behind
+ * primitive behind `agents secrets export --device` and, from RUSH-1968, behind
  * `agents fleet apply --provision-secrets`.
  *
- * This logic used to live inline in the `export --host` command action. It moved
+ * This logic used to live inline in the `export --device` command action. It moved
  * here because `lib/fleet/apply.ts` needs it and a lib MUST NOT import a command
  * module — and because the absence of a callable primitive is part of why
  * `fleet apply` never provisioned secrets at all, leaving an operator to
@@ -17,7 +17,7 @@
  *   interleaving stray lines into it.
  * - **Resolve once, push N times.** `resolveBundleForPush` is separate because
  *   reading a bundle can prompt (Touch ID); doing it per host would prompt per
- *   host. `export --host a,b,c` resolves once and pushes three times.
+ *   host. `export --device a,b,c` resolves once and pushes three times.
  */
 import { sshExec } from '../ssh-exec.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../hosts/remote-cmd.js';
@@ -89,6 +89,7 @@ export function planPushTransport(resolved, bundle, host, opts) {
         const { remoteCmd, input } = buildRemoteFileImportCommand(bundle, resolved.dotenv, {
             passphrase: opts.passphrase ?? '',
             force: opts.force,
+            policyNever: opts.policyNever,
         });
         return { kind: 'ssh', remoteCmd, input, multiplex: false };
     }
@@ -100,7 +101,7 @@ export function planPushTransport(resolved, bundle, host, opts) {
         // the wire over ssh stdin.
         return {
             kind: 'ssh',
-            remoteCmd: buildWindowsStdinImportCommand(bundle, { force: opts.force }),
+            remoteCmd: buildWindowsStdinImportCommand(bundle, { force: opts.force, policyNever: opts.policyNever }),
             input: resolved.dotenv,
             multiplex: false,
         };
@@ -110,7 +111,11 @@ export function planPushTransport(resolved, bundle, host, opts) {
     // path the READ inverse (`remoteResolveEnv`) uses.
     return {
         kind: 'remote-secrets',
-        args: ['import', bundle, '--from', '-', ...(opts.force ? ['--force'] : [])],
+        args: [
+            'import', bundle, '--from', '-',
+            ...(opts.force ? ['--force'] : []),
+            ...(opts.policyNever ? ['--policy', 'never', '--i-understand'] : []),
+        ],
         input: resolved.dotenv,
         multiplex: false,
     };
@@ -158,13 +163,6 @@ export function pushResolvedBundleToHost(resolved, bundle, host, opts) {
                 : `pushed '${bundle}' but could not verify it on the remote: ${verdict.reason}`);
         }
     }
-    if (opts.policyNever) {
-        const policy = remoteSecretsRaw(host, ['policy', bundle, 'never', '--i-understand'], { osLookupName: host, secret: true });
-        if (policy.code !== 0) {
-            const msg = (policy.stderr || policy.stdout || '').trim();
-            return fail(`pushed '${bundle}' but could not set remote policy never${msg ? `: ${msg}` : ''}`);
-        }
-    }
     for (const step of planLiteralRestoration(bundle, opts.literalValues)) {
         const removed = remoteSecretsRaw(host, step.removeArgs, { osLookupName: host, secret: true });
         if (removed.code !== 0) {

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

@@ -1,6 +1,6 @@
 /**
  * Remote secrets — read and use `agents secrets` bundles that live on another
- * host, over the same hardened SSH path that `agents secrets export --host`
+ * host, over the same hardened SSH path that `agents secrets export --device`
  * (the write inverse) already uses.
  *
  * This is the READ / USE direction:
@@ -10,7 +10,7 @@
  *              inject it ephemerally — never written to this machine's keychain.
  *
  * Trust model: relies on the operator's existing SSH access to the host (same
- * boundary as `export --host` / `run --host`). Bundle names are shell-quoted
+ * boundary as `export --device` / `run --device`). Bundle names are shell-quoted
  * into the remote command; resolved VALUES return over ssh stdout; a forwarded
  * file-backend passphrase travels over ssh stdin (first line) so it never lands
  * in argv / `ps` / remote shell history. Nothing is persisted locally.
@@ -27,9 +27,8 @@ import { type SshExecResult } from '../ssh-exec.js';
  *   - **Managed pinned host keys.** Verify against the CLI-owned known_hosts
  *     store (`known-hosts.ts`), not `~/.ssh/known_hosts`. A CHANGED key on a
  *     known host is refused (`StrictHostKeyChecking` `yes` once pinned,
- *     `accept-new` — which still refuses a changed key, only learns a genuinely
- *     new one — before that). So a machine-in-the-middle swapping a pinned host's
- *     key can never receive or return a secret.
+ *     `accept-new` before that). Callers that copy durable provider credentials
+ *     must separately require an existing pin before invoking this transport.
  *   - **No multiplex reuse.** `multiplex: false` — a credential channel never
  *     leaves a persistent `ControlMaster` socket lingering (60s `ControlPersist`)
  *     that any other `agents` invocation to that host would silently reuse.
@@ -38,6 +37,8 @@ export declare function credentialTransportSshOpts(target: string): {
     hostKeyOpts: string[];
     multiplex: false;
 };
+/** Refuse durable credential transfer until the destination SSH key is pinned. */
+export declare function assertCredentialTransportHostPinned(target: string, pinned?: boolean): void;
 /**
  * Trust boundary for a remote-resolved env map. A peer's `secrets export` output
  * is untrusted input: a compromised or misconfigured host could return keys that
@@ -56,9 +57,9 @@ export declare function credentialTransportSshOpts(target: string): {
  */
 export declare function isDangerousRemoteEnvKey(name: string): boolean;
 /**
- * Resolve a `--host` value to an ssh target STRING for the remote-secrets path.
+ * Resolve a `--device` value to an ssh target STRING for the remote-secrets path.
  * Delegates to the single host/device resolver (`resolveHost`, RUSH-1967) so a
- * name here dials the exact same box `run --host` does; on a miss, treats the
+ * name here dials the exact same box `run --device` does; on a miss, treats the
  * value as a raw ssh target and validates it against injection. Named distinctly
  * from `../devices/resolve-target.ts` (which returns richer shapes) so importing
  * the wrong one can't silently change which machine you dial.
@@ -67,7 +68,7 @@ export declare function resolveHostSshTarget(nameOrAlias: string): Promise<strin
 /**
  * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
  * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
- * works. `--device`/`--devices` resolve identically to `--host`/`--hosts` so the
+ * works. `--device`/`--devices` resolve identically to `--device`/`--hosts` so the
  * fleet-wide `--device` vocabulary (see `agents run --device`, `agents feed --host`)
  * works on the secrets remote commands too. Empty when none is set.
  */
@@ -109,7 +110,7 @@ export declare function remoteSecretsRaw(target: string, args: string[], opts?:
  * appear (the macOS file-store guard then hard-errors "needs
  * AGENTS_SECRETS_PASSPHRASE") — this inherits the caller's real terminal, so the
  * remote sees a genuine TTY and its hidden passphrase prompt surfaces and reads
- * the keystrokes. This is the transport for `unlock --host`: you type the remote
+ * the keystrokes. This is the transport for `unlock --device`: you type the remote
  * bundle's passphrase at your own terminal. Output is NOT captured (it streams
  * to the terminal); only the exit code is returned.
  */
@@ -203,7 +204,7 @@ export declare function verifyRemoteKeychainPush(target: string, bundle: string,
 }): RemoteKeychainWriteVerification;
 /**
  * The `bash -lc` command + stdin payload that drives a **file-backed** remote
- * import for `secrets export --host … --remote-backend file`.
+ * import for `secrets export --device … --remote-backend file`.
  *
  * The file store is passphrase-free by default: with `AGENTS_SECRETS_PASSPHRASE`
  * unset the remote `agents secrets import --backend file` auto-provisions the
@@ -226,6 +227,7 @@ export declare function verifyRemoteKeychainPush(target: string, bundle: string,
 export declare function buildRemoteFileImportCommand(bundle: string, dotenv: string, opts?: {
     passphrase?: string;
     force?: boolean;
+    policyNever?: boolean;
 }): {
     remoteCmd: string;
     input: string;