@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/ssh-tunnel.js

@@ -22,27 +22,26 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { randomBytes } from 'crypto';
-import { Transform } from 'stream';
 import { sshExec, SSH_OPTS } from './ssh-exec.js';
+import { backgroundSpawnOptions } from './platform/process.js';
 import { encodePowerShell } from './browser/drivers/ssh.js';
 import { getDevice } from './devices/registry.js';
 import { sshTargetFor } from './devices/connect.js';
 import { hostNameFor } from './devices/ssh-config.js';
 import { getCacheDir } from './state.js';
 import { openComputerClient, resolveTcpEndpoint } from './computer-rpc.js';
-/** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure. */
+/** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure.
+ *
+ * Composes the shared hardened baseline (`SSH_OPTS`) rather than re-listing it,
+ * so the tunnel inherits the same options — crucially the keepalive, which lets
+ * a dropped `-N` tunnel exit instead of lingering as a zombie on the laptop. */
 export function buildTunnelArgs(user, host, localPort, remotePort) {
     return [
         '-L',
         `${localPort}:127.0.0.1:${remotePort}`,
         `${user}@${host}`,
         '-N',
-        '-o',
-        'StrictHostKeyChecking=accept-new',
-        '-o',
-        'BatchMode=yes',
-        '-o',
-        'ConnectTimeout=10',
+        ...SSH_OPTS,
     ];
 }
 /**
@@ -58,7 +57,7 @@ export function startSSHTunnel(user, host, localPort, remotePort, opts = {}) {
         const args = buildTunnelArgs(user, host, localPort, remotePort);
         const tunnel = spawn('ssh', args, {
             stdio: opts.detached ? 'ignore' : ['ignore', 'ignore', 'pipe'],
-            detached: Boolean(opts.detached),
+            ...(opts.detached ? backgroundSpawnOptions() : { detached: false, windowsHide: true }),
         });
         let stderr = '';
         tunnel.stderr?.on('data', (data) => {
@@ -150,10 +149,15 @@ export async function resolveRemoteDevice(name) {
     return { device, target, user, host };
 }
 /**
- * PowerShell that streams base64 from stdin, decodes it incrementally to
- * %LOCALAPPDATA%\agents\computer-helper-win.exe, and stops any running instance
- * first so the file isn't locked. The CryptoStream/FromBase64Transform decode
- * is streaming — the ~156MB exe never lands in memory whole on the remote.
+ * Single-quote a string for embedding inside a PowerShell literal.
+ */
+function psSingleQuote(s) {
+    return "'" + s.replace(/'/g, "''") + "'";
+}
+/**
+ * PowerShell that resolves the destination under %LOCALAPPDATA%\agents and
+ * stops any running instance first so the file is not locked. The caller copies
+ * the exe with scp and then verifies the byte count separately.
  */
 export function buildPushScript() {
     return [
@@ -161,15 +165,18 @@ export function buildPushScript() {
         `New-Item -ItemType Directory -Force -Path $dir | Out-Null`,
         `$dst = Join-Path $dir '${WIN_HELPER_EXE}'`,
         `Get-Process -Name 'computer-helper-win' -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue`,
-        `$si = [Console]::OpenStandardInput()`,
-        `$t = New-Object Security.Cryptography.FromBase64Transform`,
-        `$cs = New-Object Security.Cryptography.CryptoStream($si, $t, [Security.Cryptography.CryptoStreamMode]::Read)`,
-        `$fs = [IO.File]::Create($dst)`,
-        `$cs.CopyTo($fs)`,
-        `$fs.Close(); $cs.Close()`,
         `Write-Output $dst`,
     ].join('; ');
 }
+/** PowerShell that verifies scp wrote the expected number of bytes. */
+export function buildVerifyPushScript(remotePath, expectedBytes) {
+    return [
+        `$dst = ${psSingleQuote(remotePath)}`,
+        `$item = Get-Item -LiteralPath $dst -ErrorAction Stop`,
+        `if ($item.Length -ne ${expectedBytes}) { throw "helper copy length mismatch: expected ${expectedBytes}, got $($item.Length)" }`,
+        `Write-Output "$dst $($item.Length)"`,
+    ].join('; ');
+}
 /**
  * PowerShell that registers the daemon as a LOGON scheduled task. Interactive
  * logon type + Highest run level so the daemon runs in the real desktop session
@@ -195,51 +202,32 @@ export function buildUnregisterTaskScript(taskName) {
         `Get-Process -Name 'computer-helper-win' -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue`,
     ].join('; ');
 }
+/** Convert a Windows path returned by PowerShell into the scp/SFTP path form. */
+export function scpRemotePath(remotePath) {
+    return remotePath.replace(/\\/g, '/');
+}
 /**
- * `setup --host`: push the exe, then register + start the LOGON task. Both hops
- * go through `sshExec` (BatchMode key auth — the same hardening the browser
- * driver and `agents ssh` use). Throws with the remote stderr on any failure.
- */
-/**
- * Base64-encode a byte stream in 3-byte-aligned chunks so the concatenated
- * output is valid (every chunk boundary lands on a base64 quantum).
+ * Build the scp argv used for the helper exe transfer. Exported so tests can
+ * assert the real binary copy path keeps BatchMode and does not route bytes
+ * through a PowerShell decoder.
  */
-class Base64Encode extends Transform {
-    leftover = Buffer.alloc(0);
-    _transform(chunk, _enc, cb) {
-        const buf = this.leftover.length ? Buffer.concat([this.leftover, chunk]) : chunk;
-        const usable = buf.length - (buf.length % 3);
-        this.leftover = Buffer.from(buf.subarray(usable));
-        if (usable > 0)
-            this.push(buf.subarray(0, usable).toString('base64'));
-        cb();
-    }
-    _flush(cb) {
-        if (this.leftover.length)
-            this.push(this.leftover.toString('base64'));
-        cb();
-    }
+export function buildScpArgs(target, remotePath, filePath) {
+    return [...SSH_OPTS, filePath, `${target}:${scpRemotePath(remotePath)}`];
 }
 /**
- * Stream a local file to a remote command's stdin over ssh, base64-encoded on
- * the fly. Async spawn + piping honors backpressure; the previous
- * `spawnSync({ input })` blob deadlocked once the ssh socket buffer filled
- * (~4MB) on large files (the 157MB Windows helper reproduced this reliably),
- * and worse, reported a false success leaving a 0-byte remote file. Rejects on
- * any pipe error so a broken transfer fails loudly instead.
+ * Copy a local file to the remote destination with scp. This is a binary
+ * transfer; no base64 transform runs on either side.
  */
-function streamFileOverSsh(target, remoteCmd, filePath, timeoutMs = 600_000) {
+function copyFileOverScp(target, remotePath, filePath, timeoutMs = 600_000) {
     return new Promise((resolve, reject) => {
-        const child = spawn('ssh', [...SSH_OPTS, target, remoteCmd], {
-            stdio: ['pipe', 'pipe', 'pipe'],
+        const child = spawn('scp', buildScpArgs(target, remotePath, filePath), {
+            stdio: ['ignore', 'ignore', 'pipe'],
         });
         let stderr = '';
-        let stdout = '';
         child.stderr.on('data', (d) => (stderr += d.toString()));
-        child.stdout.on('data', (d) => (stdout += d.toString()));
         const timer = setTimeout(() => {
             child.kill('SIGKILL');
-            reject(new Error(`ssh push to ${target} timed out after ${timeoutMs}ms`));
+            reject(new Error(`scp push to ${target} timed out after ${timeoutMs}ms`));
         }, timeoutMs);
         const fail = (e) => {
             clearTimeout(timer);
@@ -247,30 +235,41 @@ function streamFileOverSsh(target, remoteCmd, filePath, timeoutMs = 600_000) {
             reject(e);
         };
         child.on('error', fail);
-        child.stdin.on('error', fail); // EPIPE if the remote decoder dies mid-stream
         child.on('close', (code) => {
             clearTimeout(timer);
-            resolve({ code, stderr: stderr || stdout });
+            resolve({ code, stderr });
         });
-        const src = fs.createReadStream(filePath);
-        src.on('error', fail);
-        // disk -> aligned base64 -> ssh stdin; .pipe() applies backpressure
-        src.pipe(new Base64Encode()).pipe(child.stdin);
     });
 }
+/**
+ * `setup --host`: push the exe, then register + start the LOGON task. Remote
+ * PowerShell hops go through `sshExec` (BatchMode key auth — the same hardening
+ * the browser driver and `agents ssh` use), and the large exe rides a binary
+ * scp transfer. Throws with the remote stderr on any failure.
+ */
 export async function setupRemoteHelper(name) {
     const { target } = await resolveRemoteDevice(name);
     const exe = resolveWinHelperExe();
     if (!exe) {
         throw new Error(`Windows helper exe not built. Run: bash scripts/build-win.sh`);
     }
-    // Push: stream the exe from disk, base64-encoded on the fly, to the remote
-    // decoder. Streaming (vs a single spawnSync `input` blob) honors ssh socket
-    // backpressure — the blob path deadlocks once the socket buffer fills (~4MB).
-    const push = await streamFileOverSsh(target, encodePowerShell(buildPushScript()), exe);
+    const prep = sshExec(target, encodePowerShell(buildPushScript()), { timeoutMs: 60_000 });
+    if (prep.code !== 0) {
+        throw new Error(`preparing helper exe path on '${name}' failed (exit ${prep.code ?? 'null'}): ${prep.stderr.trim() || prep.stdout.trim()}`);
+    }
+    const remotePath = prep.stdout.trim().split(/\r?\n/).filter(Boolean).at(-1);
+    if (!remotePath) {
+        throw new Error(`preparing helper exe path on '${name}' did not return a destination path`);
+    }
+    const push = await copyFileOverScp(target, remotePath, exe);
     if (push.code !== 0) {
         throw new Error(`pushing helper exe to '${name}' failed (exit ${push.code ?? 'null'}): ${push.stderr.trim()}`);
     }
+    const expectedBytes = fs.statSync(exe).size;
+    const verify = sshExec(target, encodePowerShell(buildVerifyPushScript(remotePath, expectedBytes)), { timeoutMs: 60_000 });
+    if (verify.code !== 0) {
+        throw new Error(`verifying helper exe on '${name}' failed (exit ${verify.code ?? 'null'}): ${verify.stderr.trim() || verify.stdout.trim()}`);
+    }
     // Register + start the LOGON task.
     const reg = sshExec(target, encodePowerShell(buildRegisterTaskScript(REMOTE_HELPER_PORT, REMOTE_TASK_NAME)), {
         timeoutMs: 60_000,

package/dist/lib/staleness/writers/hooks.js

@@ -32,7 +32,7 @@ function buildHooksWriter(agent) {
             }
             // Native hook registration in settings.json/hooks.json. Grok auto-
             // discovers from ~/.grok/hooks/ so the file copy is sufficient.
-            if (agent === 'claude' || agent === 'codex' || agent === 'gemini' || agent === 'antigravity' || agent === 'kimi') {
+            if (agent === 'claude' || agent === 'codex' || agent === 'gemini' || agent === 'antigravity' || agent === 'kimi' || agent === 'droid') {
                 registerHooksToSettings(agent, versionHome);
             }
             return { synced };

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

@@ -49,6 +49,7 @@ export declare const loadPrune: ModuleLoader;
 export declare const loadTrash: ModuleLoader;
 export declare const loadRestore: ModuleLoader;
 export declare const loadDoctor: ModuleLoader;
+export declare const loadCheck: ModuleLoader;
 export declare const loadStatus: ModuleLoader;
 export declare const loadProfiles: ModuleLoader;
 export declare const loadSecrets: ModuleLoader;
@@ -57,6 +58,7 @@ export declare const loadHelper: ModuleLoader;
 export declare const loadMenubar: ModuleLoader;
 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;
@@ -66,9 +68,12 @@ export declare const loadBudget: ModuleLoader;
 export declare const loadAlias: ModuleLoader;
 export declare const loadPty: ModuleLoader;
 export declare const loadTmux: ModuleLoader;
+export declare const loadWatchdog: ModuleLoader;
 export declare const loadBrowser: ModuleLoader;
 export declare const loadComputer: ModuleLoader;
 export declare const loadHosts: ModuleLoader;
+export declare const loadLogs: ModuleLoader;
+export declare const loadEvents: ModuleLoader;
 export declare const loadSsh: ModuleLoader;
 export declare const loadPull: ModuleLoader;
 export declare const loadPush: ModuleLoader;
@@ -77,6 +82,9 @@ export declare const loadSetup: ModuleLoader;
 export declare const loadSessions: ModuleLoader;
 export declare const loadTeams: ModuleLoader;
 export declare const loadCloud: ModuleLoader;
+export declare const loadMessage: ModuleLoader;
+export declare const loadServe: ModuleLoader;
+export declare const loadAudit: ModuleLoader;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help

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

@@ -27,6 +27,7 @@ export const loadPrune = async () => (await import('../../commands/prune.js')).r
 export const loadTrash = async () => (await import('../../commands/trash.js')).registerTrashCommands;
 export const loadRestore = async () => (await import('../../commands/trash.js')).registerRestoreCommand;
 export const loadDoctor = async () => (await import('../../commands/doctor.js')).registerDoctorCommand;
+export const loadCheck = async () => (await import('../../commands/check.js')).registerCheckCommand;
 export const loadStatus = async () => (await import('../../commands/status.js')).registerStatusCommand;
 export const loadProfiles = async () => (await import('../../commands/profiles.js')).registerProfilesCommands;
 export const loadSecrets = async () => (await import('../../commands/secrets.js')).registerSecretsCommands;
@@ -35,6 +36,7 @@ export const loadHelper = async () => (await import('../../commands/helper.js'))
 export const loadMenubar = async () => (await import('../../commands/menubar.js')).registerMenubarCommands;
 export const loadBeta = async () => (await import('../../commands/beta.js')).registerBetaCommands;
 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;
@@ -44,9 +46,12 @@ export const loadBudget = async () => (await import('../../commands/budget.js'))
 export const loadAlias = async () => (await import('../../commands/alias.js')).registerAliasCommand;
 export const loadPty = async () => (await import('../../commands/pty.js')).registerPtyCommands;
 export const loadTmux = async () => (await import('../../commands/tmux.js')).registerTmuxCommands;
+export const loadWatchdog = async () => (await import('../../commands/watchdog.js')).registerWatchdogCommand;
 export const loadBrowser = async () => (await import('../../commands/browser.js')).registerBrowserCommand;
 export const loadComputer = async () => (await import('../../commands/computer.js')).registerComputerCommand;
 export const loadHosts = async () => (await import('../../commands/hosts.js')).registerHostsCommand;
+export const loadLogs = async () => (await import('../../commands/logs.js')).registerLogsCommand;
+export const loadEvents = async () => (await import('../../commands/events.js')).registerEventsCommand;
 export const loadSsh = async () => (await import('../../commands/ssh.js')).registerSshCommands;
 export const loadPull = async () => (await import('../../commands/pull.js')).registerPullCommand;
 export const loadPush = async () => (await import('../../commands/push.js')).registerPushCommand;
@@ -55,6 +60,9 @@ export const loadSetup = async () => (await import('../../commands/setup.js')).r
 export const loadSessions = async () => (await import('../../commands/sessions.js')).registerSessionsCommands;
 export const loadTeams = async () => (await import('../../commands/teams.js')).registerTeamsCommands;
 export const loadCloud = async () => (await import('../../commands/cloud.js')).registerCloudCommands;
+export const loadMessage = async () => (await import('../../commands/message.js')).registerMessageCommand;
+export const loadServe = async () => (await import('../../commands/serve.js')).registerServeCommand;
+export const loadAudit = async () => (await import('../../commands/audit.js')).registerAuditCommands;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
@@ -62,7 +70,7 @@ export const loadCloud = async () => (await import('../../commands/cloud.js')).r
  * 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']);
+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.
  *
@@ -111,6 +119,7 @@ export const COMMAND_LOADERS = {
     trash: [loadTrash],
     restore: [loadRestore],
     doctor: [loadDoctor],
+    check: [loadCheck],
     status: [loadStatus],
     profiles: [loadProfiles],
     secrets: [loadSecrets],
@@ -119,6 +128,7 @@ export const COMMAND_LOADERS = {
     menubar: [loadMenubar],
     beta: [loadBeta],
     sync: [loadSync],
+    lock: [loadLock],
     'refresh-rules': [loadRefreshRules],
     drive: [loadDrive],
     factory: [loadFactory],
@@ -128,9 +138,12 @@ export const COMMAND_LOADERS = {
     alias: [loadAlias],
     pty: [loadPty],
     tmux: [loadTmux],
+    watchdog: [loadWatchdog],
     browser: [loadBrowser],
     computer: [loadComputer],
     hosts: [loadHosts],
+    logs: [loadLogs],
+    events: [loadEvents],
     ssh: [loadSsh],
     devices: [loadSsh],
     pull: [loadPull],
@@ -140,4 +153,7 @@ export const COMMAND_LOADERS = {
     sessions: [loadSessions],
     teams: [loadTeams],
     cloud: [loadCloud],
+    message: [loadMessage],
+    serve: [loadServe],
+    audit: [loadAudit],
 };

package/dist/lib/state.d.ts

@@ -120,6 +120,8 @@ export declare function getRoutinesDir(): string;
 export declare function getProjectRoutinesDir(cwd?: string): string | null;
 /** Path to routine execution logs (~/.agents/.history/runs/). */
 export declare function getRunsDir(): string;
+/** Root for per-agent mailboxes (~/.agents/.history/mailbox/). */
+export declare function getMailboxRootDir(): string;
 /** Path to installed agent CLI binaries (~/.agents/.history/versions/). */
 export declare function getVersionsDir(): string;
 /** Path to version-switching shim scripts (~/.agents/.cache/shims/). */
@@ -226,6 +228,17 @@ export declare function getEnabledExtraRepos(): Array<{
 export declare function ensureAgentsDir(): void;
 /** Return an empty Meta object used when no agents.yaml exists yet. */
 export declare function createDefaultMeta(): Meta;
+/**
+ * Per-device machine-local version pins — `~/.agents/devices/<machine>/agents.yaml`.
+ * Committed and synced, but each machine only ever writes its OWN folder, so
+ * pulls never conflict. `<machine>` = machineId() (Tailscale-aligned short name).
+ */
+export declare function getDeviceMetaPath(): string;
+/**
+ * Machine-local per-version resource tracking — `~/.agents/.history/version-resources.json`.
+ * Gitignored (under .history/) and regenerable; never synced.
+ */
+export declare function getVersionResourcesPath(): string;
 /**
  * Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed.
  *

package/dist/lib/state.js

@@ -28,6 +28,7 @@ import * as os from 'os';
 import * as yaml from 'yaml';
 import { ensureLockTarget, atomicWriteFileSync, withFileLock } from './fs-atomic.js';
 import { SEEDED_REGISTRIES } from './types.js';
+import { machineId } from './machine-id.js';
 const HOME = process.env.HOME ?? os.homedir();
 /**
  * Compare two filesystem paths for identity, resolving symlinks and (on
@@ -87,6 +88,7 @@ const RUNS_DIR = path.join(HISTORY_DIR, 'runs');
 const TEAMS_AGENTS_DIR = path.join(HISTORY_DIR, 'teams', 'agents');
 const BACKUPS_DIR = path.join(HISTORY_DIR, 'backups');
 const TRASH_DIR = path.join(HISTORY_DIR, 'trash');
+const MAILBOX_DIR = path.join(HISTORY_DIR, 'mailbox');
 // Cache bucket (regenerable).
 const SHIMS_DIR = path.join(CACHE_DIR, 'shims');
 const HOOK_SHIMS_DIR = path.join(SHIMS_DIR, 'hooks');
@@ -309,6 +311,8 @@ export function getProjectRoutinesDir(cwd = process.cwd()) {
 }
 /** Path to routine execution logs (~/.agents/.history/runs/). */
 export function getRunsDir() { return RUNS_DIR; }
+/** Root for per-agent mailboxes (~/.agents/.history/mailbox/). */
+export function getMailboxRootDir() { return MAILBOX_DIR; }
 /** Path to installed agent CLI binaries (~/.agents/.history/versions/). */
 export function getVersionsDir() { return VERSIONS_DIR; }
 /** Path to version-switching shim scripts (~/.agents/.cache/shims/). */
@@ -495,13 +499,37 @@ function safeMtimeMs(filePath) {
         return 0;
     }
 }
-/** Compute the combined cache stamp for the user + system agents.yaml files. */
+/**
+ * Per-device machine-local version pins — `~/.agents/devices/<machine>/agents.yaml`.
+ * Committed and synced, but each machine only ever writes its OWN folder, so
+ * pulls never conflict. `<machine>` = machineId() (Tailscale-aligned short name).
+ */
+export function getDeviceMetaPath() {
+    return path.join(USER_AGENTS_DIR, 'devices', machineId(), 'agents.yaml');
+}
+/**
+ * Machine-local per-version resource tracking — `~/.agents/.history/version-resources.json`.
+ * Gitignored (under .history/) and regenerable; never synced.
+ */
+export function getVersionResourcesPath() {
+    return path.join(HISTORY_DIR, 'version-resources.json');
+}
+/**
+ * Combined cache stamp across all four Meta sources: central + system
+ * agents.yaml, this machine's device pins, and the version-resources tracking.
+ * A delimited string, NOT a numeric sum — summing down-scaled epoch-ms values
+ * loses precision (float64 rounds sub-unit terms away at ~1.75e12), so a change
+ * in any one file must contribute at full resolution.
+ */
 function currentMetaStamp() {
-    return safeMtimeMs(META_FILE) + safeMtimeMs(SYSTEM_META_FILE) * 1e-3;
+    return safeMtimeMs(META_FILE)
+        + '|' + safeMtimeMs(SYSTEM_META_FILE)
+        + '|' + safeMtimeMs(getDeviceMetaPath())
+        + '|' + safeMtimeMs(getVersionResourcesPath());
 }
 /** Memoize a parsed Meta against the current file mtimes. */
 function rememberMeta(meta) {
-    metaCache = { mtime: currentMetaStamp(), meta };
+    metaCache = { stamp: currentMetaStamp(), meta };
     return meta;
 }
 function withMetaLock(fn) {
@@ -526,11 +554,78 @@ function withMetaLock(fn) {
         }
     });
 }
+/** Atomic write only when the on-disk content differs — avoids needless mtime
+ * bumps (which would thrash the meta cache) on no-op field routing. */
+function writeIfChanged(filePath, content) {
+    let current = null;
+    try {
+        current = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch { /* absent */ }
+    if (current === content)
+        return;
+    atomicWriteFileSync(filePath, content);
+}
+/**
+ * Partition the in-memory Meta across three files by sync-domain:
+ *   - central  `~/.agents/agents.yaml`             — portable, everything else
+ *   - device   `~/.agents/devices/<machine>/agents.yaml` — `agents:` pins (per-device)
+ *   - history  `~/.agents/.history/version-resources.json` — `versions:` (machine-local)
+ * All callers funnel through writeMeta → here, so nothing else changes. Empty
+ * `agents:` / `versions:` are not written (no empty committed files).
+ */
 function writeMetaUnlocked(meta) {
-    const content = META_HEADER + yaml.stringify(meta);
-    atomicWriteFileSync(META_FILE, content);
+    const { agents, versions, ...central } = meta;
+    // Write the machine-local files FIRST, then strip central — so a crash mid-write
+    // never removes pins/versions from central before they're persisted elsewhere.
+    const devicePath = getDeviceMetaPath();
+    if (agents && Object.keys(agents).length > 0) {
+        fs.mkdirSync(path.dirname(devicePath), { recursive: true });
+        writeIfChanged(devicePath, META_HEADER + yaml.stringify({ agents }));
+    }
+    else if (fs.existsSync(devicePath)) {
+        // Every pin was cleared. Persist the emptied map instead of skipping the
+        // write — otherwise the stale device file survives and overlayMachineLocal
+        // re-applies the removed pin on the next read, leaving a dangling default
+        // (e.g. a launcher pointing at a version that was just uninstalled).
+        writeIfChanged(devicePath, META_HEADER + yaml.stringify({ agents: {} }));
+    }
+    if (versions && Object.keys(versions).length > 0) {
+        const vrPath = getVersionResourcesPath();
+        fs.mkdirSync(path.dirname(vrPath), { recursive: true });
+        writeIfChanged(vrPath, JSON.stringify(versions, null, 2) + '\n');
+    }
+    writeIfChanged(META_FILE, META_HEADER + yaml.stringify(central));
     metaCache = null;
 }
+/**
+ * Overlay this machine's local state onto a central-portable Meta:
+ *   - `agents:` from the device file (device wins; the union both preserves the
+ *     one-level merge and self-heals a pre-migration central that still has pins)
+ *   - `versions:` from the history JSON (wholesale replace; falls back to
+ *     whatever central carried when the history file doesn't exist yet)
+ */
+function overlayMachineLocal(meta) {
+    const devicePath = getDeviceMetaPath();
+    if (fs.existsSync(devicePath)) {
+        try {
+            const dm = yaml.parse(fs.readFileSync(devicePath, 'utf-8'));
+            if (dm?.agents)
+                meta.agents = { ...meta.agents, ...dm.agents };
+        }
+        catch { /* ignore malformed device file */ }
+    }
+    const vrPath = getVersionResourcesPath();
+    if (fs.existsSync(vrPath)) {
+        try {
+            const vr = JSON.parse(fs.readFileSync(vrPath, 'utf-8'));
+            if (vr)
+                meta.versions = vr;
+        }
+        catch { /* ignore malformed history file */ }
+    }
+    return meta;
+}
 function applyRegistrySeeds(meta) {
     const seeded = new Set(meta.seededPresets || []);
     let changed = false;
@@ -590,10 +685,7 @@ export function readMeta() {
     // what we last parsed. Reduces N readMeta calls per CLI invocation to ~2 stat
     // syscalls plus an in-memory object spread.
     if (metaCache) {
-        const userMtime = safeMtimeMs(META_FILE);
-        const systemMtime = safeMtimeMs(SYSTEM_META_FILE);
-        const stamp = userMtime + systemMtime * 1e-3;
-        if (stamp === metaCache.mtime) {
+        if (currentMetaStamp() === metaCache.stamp) {
             return metaCache.meta;
         }
     }
@@ -666,6 +758,7 @@ export function readMeta() {
                 ...userMeta?.registries,
             };
         }
+        overlayMachineLocal(meta);
         if (applyRegistrySeeds(meta)) {
             writeMeta(meta);
             return rememberMeta(meta);
@@ -673,6 +766,7 @@ export function readMeta() {
         return rememberMeta(meta);
     }
     const meta = createDefaultMeta();
+    overlayMachineLocal(meta);
     if (applyRegistrySeeds(meta)) {
         writeMeta(meta);
     }

package/dist/lib/sync-umbrella.d.ts

@@ -1,11 +1,12 @@
 /**
  * Umbrella `agents sync` orchestration — "make this machine current".
  *
- * Bare `agents sync` fetches remote state (config repos + secrets + sessions)
- * then reconciles it into every installed agent's version home. Each stage is
- * an existing exported library function; this module only sequences them and
- * decides — from the flags — which stages run (`planUmbrellaStages`). The
- * planner is pure so the flag matrix is unit-tested without any I/O.
+ * Bare `agents sync` fetches the config repos then reconciles them into every
+ * installed agent's version home. Secrets and sessions are opt-in stages
+ * (`--secrets` / `--sessions`) — see `planUmbrellaStages` for why they're off by
+ * default. Each stage is an existing exported library function; this module only
+ * sequences them and decides — from the flags — which stages run. The planner is
+ * pure so the flag matrix is unit-tested without any I/O.
  *
  * Stage backends:
  *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
@@ -32,11 +33,17 @@ export interface UmbrellaPlan {
 }
 /**
  * Decide which stages run. Pure — no I/O. Semantics:
- *   bare (no flags)        fetch all three, then reconcile
+ *   bare (no flags)        fetch repos, then reconcile
  *   --local                reconcile only, no fetch
- *   --cloud                fetch (all, or the selected subset), skip reconcile
+ *   --cloud                fetch repos (or the selected subset), skip reconcile
  *   --repos/--secrets/...  fetch only the selected types, then reconcile
  * `--local` wins over everything; `--cloud` suppresses reconcile.
+ *
+ * Secrets and sessions are NOT part of the bare default — they are opt-in via
+ * `--secrets` / `--sessions`. Pulling every secret bundle onto the machine on a
+ * bare `agents sync` is more blast radius than the verb should carry by
+ * default, and session transcripts are queryable on demand (`agents sessions
+ * --host <machine>`) so they don't need eager mirroring.
  */
 export declare function planUmbrellaStages(f: UmbrellaFlags): UmbrellaPlan;
 export interface UmbrellaResult {

package/dist/lib/sync-umbrella.js

@@ -1,11 +1,12 @@
 /**
  * Umbrella `agents sync` orchestration — "make this machine current".
  *
- * Bare `agents sync` fetches remote state (config repos + secrets + sessions)
- * then reconciles it into every installed agent's version home. Each stage is
- * an existing exported library function; this module only sequences them and
- * decides — from the flags — which stages run (`planUmbrellaStages`). The
- * planner is pure so the flag matrix is unit-tested without any I/O.
+ * Bare `agents sync` fetches the config repos then reconciles them into every
+ * installed agent's version home. Secrets and sessions are opt-in stages
+ * (`--secrets` / `--sessions`) — see `planUmbrellaStages` for why they're off by
+ * default. Each stage is an existing exported library function; this module only
+ * sequences them and decides — from the flags — which stages run. The planner is
+ * pure so the flag matrix is unit-tested without any I/O.
  *
  * Stage backends:
  *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
@@ -20,11 +21,17 @@ import { getUserAgentsDir, getEnabledExtraRepos } from './state.js';
 import { listRemoteBundles, pullBundle } from './secrets/sync.js';
 /**
  * Decide which stages run. Pure — no I/O. Semantics:
- *   bare (no flags)        fetch all three, then reconcile
+ *   bare (no flags)        fetch repos, then reconcile
  *   --local                reconcile only, no fetch
- *   --cloud                fetch (all, or the selected subset), skip reconcile
+ *   --cloud                fetch repos (or the selected subset), skip reconcile
  *   --repos/--secrets/...  fetch only the selected types, then reconcile
  * `--local` wins over everything; `--cloud` suppresses reconcile.
+ *
+ * Secrets and sessions are NOT part of the bare default — they are opt-in via
+ * `--secrets` / `--sessions`. Pulling every secret bundle onto the machine on a
+ * bare `agents sync` is more blast radius than the verb should carry by
+ * default, and session transcripts are queryable on demand (`agents sessions
+ * --host <machine>`) so they don't need eager mirroring.
  */
 export function planUmbrellaStages(f) {
     if (f.local) {
@@ -39,8 +46,9 @@ export function planUmbrellaStages(f) {
             reconcile: !f.cloud,
         };
     }
-    // No per-type selector: bare = all + reconcile; --cloud = all, no reconcile.
-    return { fetchRepos: true, fetchSecrets: true, fetchSessions: true, reconcile: !f.cloud };
+    // No per-type selector: bare = repos + reconcile; --cloud = repos, no
+    // reconcile. Secrets/sessions stay off unless explicitly selected above.
+    return { fetchRepos: true, fetchSecrets: false, fetchSessions: false, reconcile: !f.cloud };
 }
 /**
  * Execute the planned stages in order: repos -> secrets -> sessions -> reconcile.