@phnx-labs/agents-cli 1.20.93 → 1.21.1

package/dist/lib/rules/run-sync.js

@@ -0,0 +1,92 @@
+/**
+ * Rules preset auto-apply at `agents run` launch time.
+ *
+ * `agents rules switch <agent>@<version> --preset <name>` persists the active
+ * preset (`state.ts:setActiveRulesPreset`) and immediately recompiles it into
+ * the version home via `syncResourcesToVersion` → the rules writer
+ * (`staleness/writers/rules.ts`). Same for `agents add`/`use`. But nothing
+ * re-applies the preset on a LATER `agents run` — if `setActiveRulesPreset`
+ * is ever called without a follow-up sync (or a subrule file changes after
+ * the last sync), the harness launches against a stale rules file until the
+ * next explicit `agents rules switch` / `agents sync`.
+ *
+ * This closes that gap the same way `runLaunchSync` (project-launch.ts)
+ * recompiles PROJECT rules on every launch: idempotent, and skip-fast when
+ * nothing changed. The skip-fast reuses the staleness checkers' mtime+size
+ * fingerprint comparison (`staleness/checkers/rules.ts`,
+ * `staleness/fingerprint.ts`) against a small per-(agent,version) sentinel —
+ * the same "hash the cheap inputs, compare, skip the write on a match" shape
+ * `installScope` (project-launch.ts) uses for plugin marketplaces. The common
+ * case (no preset or subrule change since the last run) costs one JSON read
+ * plus a handful of `stat()` calls — no recompose, no write.
+ *
+ * Version-level scope only — the active preset is keyed by (agent, version),
+ * matching `getActiveRulesPreset`. Per-model preset scoping is a follow-up.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS } from '../agents.js';
+import { getActiveRulesPreset, getCacheDir } from '../state.js';
+import { getWriter } from '../staleness/registry.js';
+import { buildRules, isRulesStale } from '../staleness/checkers/rules.js';
+/** ~/.agents/.cache/rules-run-sync/ — regenerable; a lost sentinel just costs one extra compose+write. */
+function sentinelPath(agent, version) {
+    const key = `${agent}@${version}`.replace(/[^a-zA-Z0-9@._-]/g, '_');
+    return path.join(getCacheDir(), 'rules-run-sync', `${key}.json`);
+}
+function loadSentinel(agent, version) {
+    try {
+        return JSON.parse(fs.readFileSync(sentinelPath(agent, version), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function saveSentinel(agent, version, sentinel) {
+    const p = sentinelPath(agent, version);
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(sentinel));
+    }
+    catch {
+        // Best-effort — a failed write just means the next run redoes the compose+write.
+    }
+}
+/**
+ * Re-apply the active rules preset for (agent, version) into its version
+ * home when the composed source set has drifted since the last time this ran.
+ * Returns true when the version-home rules file was (re)written.
+ *
+ * No-cwd fingerprint on purpose: the version-home rules file never includes
+ * the project layer (see `staleness/writers/rules.ts` — project rules are
+ * resolved separately, at launch, into the workspace `AGENTS.md` by
+ * `compileRulesForProject`). Fingerprinting with a cwd would pull the project
+ * layer's subrules into the comparison and trigger a pointless version-home
+ * rewrite every time a project's own `.agents/rules/` changes.
+ *
+ * Silent on any failure (no rules.yaml, unknown preset, unsupported agent) —
+ * mirrors `syncResourcesToVersion`'s own catch-and-skip for rules: a bad
+ * preset must never block a launch, and this now also runs on the hot path.
+ */
+export function applyActiveRulesPresetAtRun(agent, version, versionHome) {
+    const cap = AGENTS[agent].capabilities.rules;
+    if (cap === false)
+        return false;
+    const rulesWriter = getWriter('rules', agent);
+    if (!rulesWriter)
+        return false;
+    const preset = getActiveRulesPreset(agent, version);
+    const current = buildRules(agent, version, '');
+    const stored = loadSentinel(agent, version);
+    if (stored && stored.preset === preset && !isRulesStale(stored.entry, agent, version, '')) {
+        return false; // skip-fast: preset unchanged AND composed source set unchanged
+    }
+    try {
+        rulesWriter.write({ version, versionHome, selection: { preset }, cwd: '' });
+    }
+    catch {
+        return false;
+    }
+    saveSentinel(agent, version, { preset, entry: current });
+    return true;
+}

package/dist/lib/scheduler.js

@@ -6,7 +6,7 @@
  * on startup and reloads them on SIGHUP.
  */
 import { Cron } from 'croner';
-import { listJobs, deleteJob, isPastEndAt, isPastOneShotRoutine, isOneShotRoutine, setJobEnabled, shouldPurgeCompletedOneShotRoutine, jobRunsOnThisDevice, } from './routines.js';
+import { listJobs, deleteJob, isPastEndAt, isPastOneShotRoutine, isOneShotRoutine, setJobEnabled, shouldPurgeCompletedOneShotRoutine, jobRunsOnThisDevice, hasAmbiguousDevicePin, routineOwnerDevice, } from './routines.js';
 /** In-memory cron scheduler that triggers a callback when jobs fire. */
 export class JobScheduler {
     jobs = new Map();
@@ -20,7 +20,17 @@ export class JobScheduler {
             // Trigger-only jobs (no cron schedule) fire via the webhook receiver,
             // not the cron loop — skip them here. Jobs pinned to another device
             // (routines are fleet-synced) never enter this machine's cron loop.
-            if (!config.enabled || !config.schedule || !jobRunsOnThisDevice(config))
+            if (!config.enabled || !config.schedule)
+                continue;
+            // A multi-device pin is a misconfiguration: it used to fire the routine
+            // once per listed device. It now fires only on the owner, but say so —
+            // silently reinterpreting someone's config is how this went unnoticed.
+            if (hasAmbiguousDevicePin(config)) {
+                const owner = routineOwnerDevice(config);
+                console.warn(`Job '${config.name}' pins ${config.devices.length} devices; a routine runs on exactly one. ` +
+                    `Firing only on '${owner}'. Fix with: agents routines devices ${config.name} --set ${owner}`);
+            }
+            if (!jobRunsOnThisDevice(config))
                 continue;
             if (shouldPurgeCompletedOneShotRoutine(config)) {
                 deleteJob(config.name);

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

@@ -193,11 +193,10 @@ export declare function rekeyStatus(): {
  * Throws when the item cannot be reached — on macOS, when the signed helper is
  * unavailable. That is deliberate: this primitive gates destructive writes as
  * well as reads. Through `bundleExists()` it guards the `--force` overwrite
- * checks in `agents secrets create` (`../../commands/secrets.ts`), the
- * bundle-rename purge (`./bundles.ts`), the pull-rollback bookkeeping
- * (`./sync.ts`), and the reuse-never-overwrite rule for `R2_SYNC_ENC_KEY`
- * (`../session/sync/provision.ts`). A false "absent" silently disarms every one
- * of them, so an unreachable keychain must fail loudly rather than answer "no".
+ * checks in `agents secrets create` (`../../commands/secrets.ts`) and the
+ * bundle-rename purge (`./bundles.ts`), and the pull-rollback bookkeeping
+ * (`./sync.ts`). A false "absent" silently disarms every one of them, so an
+ * unreachable keychain must fail loudly rather than answer "no".
  *
  * Tests needing this path without a helper install a backend via
  * `setKeychainBackendForTest()`, which short-circuits on the next line.

package/dist/lib/secrets/index.js

@@ -680,11 +680,10 @@ export function rekeyStatus() {
  * Throws when the item cannot be reached — on macOS, when the signed helper is
  * unavailable. That is deliberate: this primitive gates destructive writes as
  * well as reads. Through `bundleExists()` it guards the `--force` overwrite
- * checks in `agents secrets create` (`../../commands/secrets.ts`), the
- * bundle-rename purge (`./bundles.ts`), the pull-rollback bookkeeping
- * (`./sync.ts`), and the reuse-never-overwrite rule for `R2_SYNC_ENC_KEY`
- * (`../session/sync/provision.ts`). A false "absent" silently disarms every one
- * of them, so an unreachable keychain must fail loudly rather than answer "no".
+ * checks in `agents secrets create` (`../../commands/secrets.ts`) and the
+ * bundle-rename purge (`./bundles.ts`), and the pull-rollback bookkeeping
+ * (`./sync.ts`). A false "absent" silently disarms every one of them, so an
+ * unreachable keychain must fail loudly rather than answer "no".
  *
  * Tests needing this path without a helper install a backend via
  * `setKeychainBackendForTest()`, which short-circuits on the next line.

package/dist/lib/session/active.d.ts

@@ -265,6 +265,14 @@ export declare function activeStatusFromCloudStatus(status: CloudTaskStatus): Ac
 export interface ActiveQueryOptions {
     /** Skip the `ps` scan for ad-hoc headless agents. */
     skipHeadless?: boolean;
+    /**
+     * A `--local` query: this machine only. Never dial a remote-host teammate
+     * (one dispatched via `agents teams add --device`) over ssh — report its
+     * last-persisted meta.json state instead of polling it. RUSH-2118: without
+     * this, `agents sessions --active --local` still fired one ssh round-trip
+     * per remote-host teammate (finished or not) on every call.
+     */
+    localOnly?: boolean;
 }
 /**
  * A live process can only borrow an indexed session file if that transcript
@@ -421,8 +429,14 @@ export declare function computeLiveSignals(kind: string, sessionFile: string | u
  * and truncates. Exported for tests.
  */
 export declare function summarizeMission(prompt: string | null | undefined): string | undefined;
-/** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
-export declare function listTeamsActive(): Promise<ActiveSession[]>;
+/**
+ * Live teams teammates. Reuses AgentManager which already polls PIDs via
+ * `kill -0`. `localOnly` (RUSH-2118) skips the ssh round-trip AgentManager
+ * would otherwise issue for every distributed (remote-host) teammate.
+ */
+export declare function listTeamsActive(opts?: {
+    localOnly?: boolean;
+}): Promise<ActiveSession[]>;
 /** Live editor-terminal agents across every IDE window. */
 export declare function listTerminalsActive(): Promise<ActiveSession[]>;
 /** Cloud tasks still in a non-terminal state. `tasks.db` may not exist; that's fine. */

package/dist/lib/session/active.js

@@ -697,9 +697,13 @@ export function summarizeMission(prompt) {
         return undefined;
     return cleaned.length > 80 ? `${cleaned.slice(0, 79)}…` : cleaned;
 }
-/** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
-export async function listTeamsActive() {
-    const mgr = new AgentManager();
+/**
+ * Live teams teammates. Reuses AgentManager which already polls PIDs via
+ * `kill -0`. `localOnly` (RUSH-2118) skips the ssh round-trip AgentManager
+ * would otherwise issue for every distributed (remote-host) teammate.
+ */
+export async function listTeamsActive(opts = {}) {
+    const mgr = new AgentManager(undefined, undefined, undefined, undefined, undefined, opts.localOnly ?? false);
     const running = await mgr.listRunning();
     return running.map((a) => {
         // The teammate's OWN transcript is `remoteSessionId` (captured from its first
@@ -1438,7 +1442,7 @@ export async function listTmuxAgentSessions() {
 export async function getActiveSessions(opts = {}) {
     const [tmuxAgents, teams, terminals, cloud] = await Promise.all([
         listTmuxAgentSessions().catch(() => []),
-        listTeamsActive().catch(() => []),
+        listTeamsActive({ localOnly: opts.localOnly }).catch(() => []),
         listTerminalsActive().catch(() => []),
         Promise.resolve(listCloudActive()),
     ]);

package/dist/lib/session/bundle.js

@@ -19,12 +19,16 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import * as crypto from 'crypto';
 import { SYNC_AGENTS, mirrorPath } from './sync/agents.js';
-import { hashContent } from './sync/manifest.js';
 import { redactSecrets } from '../redact.js';
 import { encryptTranscript, decryptTranscriptBody } from './sync/transcript-crypto.js';
 export const BUNDLE_KIND = 'agents-session-bundle';
 export const BUNDLE_VERSION = 1;
+/** SHA-256 of a file body, used for the bundle's dedup/conflict check on import. */
+function hashContent(content) {
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
 /** Look up the sync spec for an agent id (undefined → agent not sync-representable). */
 export function specForAgent(agentId) {
     return SYNC_AGENTS.find(s => s.id === agentId);

package/dist/lib/session/remote-list.d.ts

@@ -1,12 +1,4 @@
 import type { SessionMeta } from './types.js';
-/**
- * The command run on each peer: answer for itself, as JSON, without recursing.
- * `forwardedArgs` carry the caller's own query/filters (already including the
- * leading `sessions` and a `--json`) so each peer returns a comparable slice.
- * A Windows peer gets a PowerShell invocation (ssh lands in cmd.exe/PowerShell
- * there, where `bash -lc` is not a command); every other OS keeps `bash -lc`.
- */
-export declare function remoteListCommand(forwardedArgs: string[], os?: string): string;
 /**
  * Parse a peer's `sessions --json` stdout into `SessionMeta[]`, tagging each
  * with `machine`. Defensive against version skew / partial output: non-JSON or
@@ -17,15 +9,9 @@ export declare function remoteListCommand(forwardedArgs: string[], os?: string):
  */
 export declare function parseRemoteList(stdout: string, machine: string): SessionMeta[];
 export declare function parseRemoteListPayload(stdout: string, machine: string, safeResolver?: boolean): {
-    sessions: SessionMeta[];
+    items: SessionMeta[];
     valid: boolean;
 };
-/** Convert one completed peer process into the exact aggregation result. This
- * is the production parent/peer seam and is exercised with real child output. */
-export declare function remoteListCaptureResult(code: number | null, stdout: string, machine: string, display: string, safeResolver?: boolean): {
-    sessions: SessionMeta[];
-    unreachable?: string;
-};
 export interface RemoteListResult {
     sessions: SessionMeta[];
     /** How many peer machines we attempted to reach (drives the empty-fleet tip). */

package/dist/lib/session/remote-list.js

@@ -17,32 +17,12 @@ import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from '../devices/connect.js';
-import { resolveExplicitTargets } from '../devices/resolve-target.js';
-import { loadDevices, isControlDevice, isDialableDevice } from '../devices/registry.js';
+import { loadDevices } from '../devices/registry.js';
 import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
-import { machineId, normalizeHost } from './sync/config.js';
+import { gatherRemoteAgentsJson } from '../remote-agents-json.js';
+import { normalizeHost } from './sync/config.js';
 import { NO_FANOUT_ENV } from './remote-active.js';
 import { terminalWidth } from './width.js';
-/** Per-host SSH budget. Slightly above SSH_OPTS' ConnectTimeout=10 so a
- * reachable-but-slow remote still answers before we give up. */
-const REMOTE_TIMEOUT_MS = 12_000;
-/**
- * The command run on each peer: answer for itself, as JSON, without recursing.
- * `forwardedArgs` carry the caller's own query/filters (already including the
- * leading `sessions` and a `--json`) so each peer returns a comparable slice.
- * A Windows peer gets a PowerShell invocation (ssh lands in cmd.exe/PowerShell
- * there, where `bash -lc` is not a command); every other OS keeps `bash -lc`.
- */
-export function remoteListCommand(forwardedArgs, os) {
-    if (remoteShellFor(os) === 'powershell') {
-        return buildWindowsAgentsCommand({
-            args: forwardedArgs,
-            env: { [NO_FANOUT_ENV]: '1' },
-        });
-    }
-    const inner = [`${NO_FANOUT_ENV}=1`, 'agents', ...forwardedArgs].map((t, i) => i === 0 ? t : shellQuote(t)).join(' ');
-    return `bash -lc ${shellQuote(inner)}`;
-}
 /**
  * Parse a peer's `sessions --json` stdout into `SessionMeta[]`, tagging each
  * with `machine`. Defensive against version skew / partial output: non-JSON or
@@ -83,61 +63,22 @@ export function parseRemoteListPayload(stdout, machine, safeResolver = false) {
         parsed = JSON.parse(stdout);
     }
     catch {
-        return { sessions: [], valid: false };
+        return { items: [], valid: false };
     }
     if (!Array.isArray(parsed))
-        return { sessions: [], valid: false };
+        return { items: [], valid: false };
     const out = [];
     for (const x of parsed) {
         if (!x || typeof x !== 'object' || Array.isArray(x))
-            return { sessions: [], valid: false };
+            return { items: [], valid: false };
         if (safeResolver && !isSafeResolverRow(x)) {
-            return { sessions: [], valid: false };
+            return { items: [], valid: false };
         }
         // `_remote` marks these as living on the peer's disk (not a local mirror),
         // so the picker routes read/resume back over SSH instead of the local FS.
         out.push({ ...x, machine, _remote: true });
     }
-    return { sessions: out, valid: true };
-}
-/** Convert one completed peer process into the exact aggregation result. This
- * is the production parent/peer seam and is exercised with real child output. */
-export function remoteListCaptureResult(code, stdout, machine, display, safeResolver = false) {
-    if (code !== 0)
-        return { sessions: [], unreachable: display };
-    const parsed = parseRemoteListPayload(stdout, machine, safeResolver);
-    return parsed.valid ? { sessions: parsed.sessions } : { sessions: [], unreachable: display };
-}
-/** Run one remote `agents sessions … --json` and capture stdout. Resolves
- * `{ code: null }` on spawn error or timeout (host treated as dead). */
-function sshCapture(target, remoteCmd, timeoutMs) {
-    assertValidSshTarget(target);
-    return new Promise((resolve) => {
-        const args = [...SSH_OPTS, ...controlOpts(), target, remoteCmd];
-        const child = spawn('ssh', args, { stdio: ['ignore', 'pipe', 'ignore'] });
-        let stdout = '';
-        let settled = false;
-        const done = (code) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            resolve({ code, stdout });
-        };
-        const timer = setTimeout(() => { child.kill('SIGKILL'); done(null); }, timeoutMs);
-        child.stdout.on('data', (d) => { stdout += d.toString(); });
-        child.on('error', () => done(null));
-        child.on('close', (code) => done(code));
-    });
-}
-async function fetchByTarget(target, machine, display, forwardedArgs, os) {
-    const { code, stdout } = await sshCapture(target, remoteListCommand(forwardedArgs, os), REMOTE_TIMEOUT_MS);
-    const safeResolver = forwardedArgs.includes('--resolve-safe-v1');
-    const result = remoteListCaptureResult(code, stdout, machine, display, safeResolver);
-    if (result.unreachable) {
-        process.stderr.write(chalk.gray(`  ${display}: unreachable or no agents CLI — skipped\n`));
-    }
-    return result;
+    return { items: out, valid: true };
 }
 /**
  * Gather listing sessions from other machines. With an explicit `hosts` list
@@ -147,51 +88,21 @@ async function fetchByTarget(target, machine, display, forwardedArgs, os) {
  * already `--json`) so every peer returns the same slice this machine asked for.
  */
 export async function gatherRemoteList(forwardedArgs, hosts) {
-    const self = machineId();
-    const targets = [];
-    if (hosts && hosts.length > 0) {
-        // Resolve each token through the device registry so an explicit --host/--device
-        // dials the exact same address (and machine id) as the auto-discovery sweep.
-        targets.push(...await resolveExplicitTargets(hosts));
-    }
-    else {
-        let reg;
-        try {
-            reg = await loadDevices();
-        }
-        catch {
-            return { sessions: [], deviceCount: 0, unreachable: ['device registry'] };
-        }
-        for (const d of Object.values(reg)) {
-            // Live SSH-probe verdict first, cached tailscale snapshot only as a
-            // fallback — see isDialableDevice. A manually-registered device has no
-            // tailscale peer entry, so gating on `online` alone hid its sessions.
-            if (!isDialableDevice(d))
-                continue;
-            if (normalizeHost(d.name) === self)
-                continue;
-            // Control-only devices (a phone/tablet running the cockpit) drive the fleet
-            // but never run agents — never dial them, whatever their platform reads as.
-            if (isControlDevice(d))
-                continue;
-            // Only machines that can actually run the CLI. iOS/tablet nodes register as
-            // `unknown` platform and can never answer, so skip them rather than burn a
-            // full ConnectTimeout on each.
-            if (d.platform !== 'windows' && d.platform !== 'linux' && d.platform !== 'macos')
-                continue;
-            try {
-                targets.push({ target: sshTargetFor(d), machine: normalizeHost(d.name), name: d.name, os: d.platform });
-            }
-            catch {
-                // No address on the profile — nothing to dial; skip silently.
-            }
-        }
-    }
-    const results = await Promise.all(targets.map((t) => fetchByTarget(t.target, t.machine, t.name, forwardedArgs, t.os)));
+    const safeResolver = forwardedArgs.includes('--resolve-safe-v1');
+    const result = await gatherRemoteAgentsJson({
+        args: forwardedArgs,
+        noFanoutEnv: NO_FANOUT_ENV,
+        hosts,
+        parse: (stdout, machine) => parseRemoteListPayload(stdout, machine, safeResolver),
+    });
     return {
-        sessions: results.flatMap((r) => r.sessions),
-        deviceCount: targets.length,
-        unreachable: results.map((r) => r.unreachable).filter((n) => !!n),
+        sessions: result.items,
+        deviceCount: result.deviceCount,
+        unreachable: [
+            ...(result.discoveryFailed ? ['device registry'] : []),
+            ...result.skipped,
+            ...result.parseFailed,
+        ],
     };
 }
 /** Resolve a peer's SSH target (and OS) from the device registry by its

package/dist/lib/session/sync/config.d.ts

@@ -1,7 +1,15 @@
 /**
- * Configuration for cross-machine session sync: R2 credentials and this
- * machine's stable identity. Credentials come from the `r2.backups` secrets
- * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
+ * R2 credential resolution + this machine's stable identity. The only field
+ * `agents sessions export --encrypt` / `import` actually consume is the
+ * shared `R2_SYNC_ENC_KEY` transcript key (`resolveSyncEncKey`); the other R2
+ * fields (account/bucket/access keys) are validated here as a presence gate —
+ * no `r2.backups` bundle configured means no shared key, so export/import
+ * fall back to an ephemeral one. There is no R2 network client in this
+ * codebase today (it moved with the rest of the R2/CRDT background sync this
+ * bundle used to back — see git history for `./r2.ts`); a future R2-backed
+ * feature (an export destination, a fleet cache) would add one where it's
+ * actually wired. Credentials come from the `r2.backups` secrets bundle (OS
+ * keychain on macOS, libsecret on Linux) — never from env or disk.
  */
 /** Secrets bundle holding the R2 credentials. */
 export declare const SYNC_BUNDLE = "r2.backups";
@@ -16,8 +24,8 @@ export interface R2Config {
      * Shared 32-byte key (hex or base64) for client-side transcript encryption,
      * held in the bundle as `R2_SYNC_ENC_KEY`. Optional and deliberately separate
      * from the R2 credentials so rotating the access token never orphans already
-     * encrypted objects. When absent, transcripts upload unencrypted (with a loud
-     * per-cycle warning) — see transcript-crypto.ts + pushOwn.
+     * encrypted bundles. `agents sessions export --encrypt` prefers this key when
+     * present, else mints and prints an ephemeral one — see transcript-crypto.ts.
      */
     syncEncKey?: string;
 }

package/dist/lib/session/sync/config.js

@@ -1,7 +1,15 @@
 /**
- * Configuration for cross-machine session sync: R2 credentials and this
- * machine's stable identity. Credentials come from the `r2.backups` secrets
- * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
+ * R2 credential resolution + this machine's stable identity. The only field
+ * `agents sessions export --encrypt` / `import` actually consume is the
+ * shared `R2_SYNC_ENC_KEY` transcript key (`resolveSyncEncKey`); the other R2
+ * fields (account/bucket/access keys) are validated here as a presence gate —
+ * no `r2.backups` bundle configured means no shared key, so export/import
+ * fall back to an ephemeral one. There is no R2 network client in this
+ * codebase today (it moved with the rest of the R2/CRDT background sync this
+ * bundle used to back — see git history for `./r2.ts`); a future R2-backed
+ * feature (an export destination, a fleet cache) would add one where it's
+ * actually wired. Credentials come from the `r2.backups` secrets bundle (OS
+ * keychain on macOS, libsecret on Linux) — never from env or disk.
  */
 import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../../secrets/bundles.js';
 /** Secrets bundle holding the R2 credentials. */
@@ -12,13 +20,13 @@ export const SYNC_BUNDLE = 'r2.backups';
  * without real credentials (no silent fallback).
  */
 function resolveR2Config() {
-    // The daemon monitor loop is headless by construction (no TTY, ever), so
-    // isHeadlessSecretsContext() is true here and this resolves broker-only — a
-    // broker miss can never pop an unattended Touch ID sheet on the user's screen
-    // (the same broker-only-when-headless rationale the secrets readers use). Using
-    // the shared predicate rather than a literal keeps it consistent with the other callers
-    // and lets any interactive caller of loadR2Config still prompt.
-    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'sessions-sync', agentOnly: isHeadlessSecretsContext() });
+    // A headless caller (no TTY — e.g. a routine or SSH-dispatched command) must
+    // resolve broker-only: isHeadlessSecretsContext() true means a broker miss
+    // can never pop an unattended Touch ID sheet on the user's screen (the same
+    // broker-only-when-headless rationale the secrets readers use). Using the
+    // shared predicate rather than a literal keeps it consistent with the other
+    // callers and lets any interactive caller of loadR2Config still prompt.
+    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'session-transport', agentOnly: isHeadlessSecretsContext() });
     const accountId = env.R2_ACCOUNT_ID?.trim();
     const bucket = env.R2_BUCKET_NAME?.trim();
     const accessKeyId = env.R2_ACCESS_KEY_ID?.trim();
@@ -31,7 +39,7 @@ function resolveR2Config() {
         !secretAccessKey && 'R2_SECRET_ACCESS_KEY',
     ].filter(Boolean);
     if (missing.length > 0) {
-        throw new Error(`Sessions sync: bundle '${SYNC_BUNDLE}' is missing ${missing.join(', ')}. ` +
+        throw new Error(`Session R2 transport: bundle '${SYNC_BUNDLE}' is missing ${missing.join(', ')}. ` +
             `Add them with: agents secrets add ${SYNC_BUNDLE} <KEY>`);
     }
     return {
@@ -40,8 +48,8 @@ function resolveR2Config() {
         accessKeyId: accessKeyId,
         secretAccessKey: secretAccessKey,
         // Default to the account's R2 endpoint; an explicit R2_ENDPOINT override
-        // points sync at any S3-compatible store (MinIO, another provider) — which
-        // is also how the feature is verified end-to-end without live R2.
+        // points at any S3-compatible store (MinIO, another provider) — which is
+        // also how the feature is verified end-to-end without live R2.
         endpoint: env.R2_ENDPOINT?.trim() || `https://${accountId}.r2.cloudflarestorage.com`,
         syncEncKey,
     };

package/dist/lib/startup/command-registry.d.ts

@@ -67,7 +67,6 @@ export declare const loadBeta: ModuleLoader;
 export declare const loadSync: ModuleLoader;
 export declare const loadLock: ModuleLoader;
 export declare const loadRefreshRules: ModuleLoader;
-export declare const loadDrive: ModuleLoader;
 export declare const loadFactory: ModuleLoader;
 export declare const loadUsage: ModuleLoader;
 export declare const loadCost: ModuleLoader;
@@ -96,7 +95,6 @@ export declare const loadTeams: ModuleLoader;
 export declare const loadCloud: ModuleLoader;
 export declare const loadMessage: ModuleLoader;
 export declare const loadSend: ModuleLoader;
-export declare const loadHq: ModuleLoader;
 export declare const loadFeed: ModuleLoader;
 export declare const loadActivity: ModuleLoader;
 export declare const loadMailboxes: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -45,7 +45,6 @@ export const loadBeta = async () => (await import('../../commands/beta.js')).reg
 export const loadSync = async () => (await import('../../commands/sync.js')).registerSyncCommand;
 export const loadLock = async () => (await import('../../commands/lock.js')).registerLockCommand;
 export const loadRefreshRules = async () => (await import('../../commands/refresh-rules.js')).registerRefreshRulesCommand;
-export const loadDrive = async () => (await import('../../commands/drive.js')).registerDriveCommands;
 export const loadFactory = async () => (await import('../../commands/factory.js')).registerFactoryCommands;
 export const loadUsage = async () => (await import('../../commands/usage.js')).registerUsageCommand;
 export const loadCost = async () => (await import('../../commands/cost.js')).registerCostCommand;
@@ -74,7 +73,6 @@ export const loadTeams = async () => (await import('../../commands/teams.js')).r
 export const loadCloud = async () => (await import('../../commands/cloud.js')).registerCloudCommands;
 export const loadMessage = async () => (await import('../../commands/message.js')).registerMessageCommand;
 export const loadSend = async () => (await import('../../commands/send.js')).registerSendCommand;
-export const loadHq = async () => (await import('../../commands/hq.js')).registerHqCommand;
 export const loadFeed = async () => (await import('../../commands/feed.js')).registerFeedCommand;
 export const loadActivity = async () => (await import('../../commands/activity.js')).registerActivityCommand;
 export const loadMailboxes = async () => (await import('../../commands/mailboxes.js')).registerMailboxesCommand;
@@ -90,7 +88,7 @@ export const loadFunnel = async () => (await import('../../commands/funnel.js'))
  * inherit the root's custom help formatter rather than getting the per-command
  * recursive pass. Keeping that ordering preserves their `--help` output exactly.
  */
-export const LAZY_COMMAND_NAMES = new Set(['sessions', 'teams', 'cloud', 'message', 'hq', 'serve']);
+export const LAZY_COMMAND_NAMES = new Set(['sessions', 'teams', 'cloud', 'message', 'serve']);
 /**
  * User-typed top-level command name -> ordered list of module loaders to run.
  *
@@ -161,7 +159,6 @@ export const COMMAND_LOADERS = {
     sync: [loadSync],
     lock: [loadLock],
     'refresh-rules': [loadRefreshRules],
-    drive: [loadDrive],
     factory: [loadFactory],
     usage: [loadUsage],
     cost: [loadCost],
@@ -199,7 +196,6 @@ export const COMMAND_LOADERS = {
     message: [loadMessage],
     send: [loadSend],
     notify: [loadSend],
-    hq: [loadHq],
     feed: [loadFeed],
     activity: [loadActivity],
     mailboxes: [loadMailboxes],

package/dist/lib/state.d.ts

@@ -23,6 +23,13 @@
  * and leaves a back-compat symlink at the old path.
  */
 import type { Meta } from './types.js';
+/**
+ * Header prepended to every agents.yaml the CLI writes (central and per-device
+ * docs). Carries the yaml-language-server schema hint so editors validate the
+ * file against `schema/agents-yaml.schema.json`. Exported so
+ * `lib/device-config.ts` writes a sibling device's doc with the same header.
+ */
+export declare const META_HEADER = "# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json\n\n";
 /** Root of the system data directory (~/.agents/.system/). */
 export declare function getAgentsDir(): string;
 /** Root of the system data directory (~/.agents/.system/). */
@@ -194,8 +201,6 @@ export declare function getSystemPluginsDir(): string;
 export declare function getExtraPluginsDir(alias: string): string;
 /** Path to a project-scoped plugins directory (<project>/.agents/plugins/), or null when none. */
 export declare function getProjectPluginsDir(cwd?: string): string | null;
-/** Path to synced remote session data (~/.agents/.cache/drive/). */
-export declare function getDriveDir(): string;
 /** Path to soft-deleted resources (~/.agents/.history/trash/). */
 export declare function getTrashDir(): string;
 /** Path to local session indexer storage (~/.agents/.history/sessions/). */