@phnx-labs/agents-cli 1.20.93 → 1.21.0

package/dist/commands/setup-preferences.js

@@ -0,0 +1,142 @@
+/**
+ * Preferences onboarding — the guided path over the same device-config keys the
+ * `agents devices …` commands write (lib/device-config.ts). Two questions, each
+ * TTY-only, skippable, and absent non-interactively:
+ *
+ *   1. "Which machine do you sit at?"   → `interactive.host` (central config:)
+ *   2. "Which browser should agents drive on THIS machine?"
+ *                                       → `browser.profile` (device-local default)
+ *
+ * Shared by the bare `agents setup` flow (a short step after the capability
+ * hub) and by `agents setup fleet` (interactive host after a successful sync).
+ * Unset always keeps today's behavior — skipping is a real choice, not a
+ * partial state.
+ */
+import chalk from 'chalk';
+import { listInstalledBrowsers } from '../lib/browser/chrome.js';
+import { DEFAULT_BROWSER_PROFILE_NAME, createProfile, findFreeProfilePort, getConfiguredDefaultProfileName, getProfile, } from '../lib/browser/profiles.js';
+import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
+import { getConfigValue, setConfigValue } from '../lib/device-config.js';
+import { loadDevices } from '../lib/devices/registry.js';
+import { machineId } from '../lib/machine-id.js';
+import { isInteractiveTerminal } from './utils.js';
+const SKIP = '__skip__';
+/** Registered macOS device names, sorted — the interactive-host candidates. */
+export function macDeviceNames(reg) {
+    return Object.values(reg)
+        .filter((d) => d.platform === 'macos')
+        .map((d) => d.name)
+        .sort();
+}
+/**
+ * The interactive-host picker's highlighted default: this machine when it is a
+ * candidate (the common case — you run setup on the box you sit at), else the
+ * first candidate. null when there are no candidates.
+ */
+export function defaultInteractiveHostChoice(candidates, self = machineId()) {
+    if (candidates.length === 0)
+        return null;
+    return candidates.includes(self) ? self : candidates[0];
+}
+/**
+ * The browser picker's highlighted default — the same browser auto-detect
+ * would win, since `listInstalledBrowsers` returns platform priority order
+ * (macOS: chrome first). null when nothing is installed.
+ */
+export function defaultBrowserChoice(installed) {
+    return installed.length > 0 ? installed[0].browserType : null;
+}
+/**
+ * Offer to set the interactive host when none is configured and the registry
+ * has more than one macOS device. Returns true when a host was set. Silent
+ * no-op non-TTY, when already set, or with fewer than two candidates (the
+ * answer is obvious or absent).
+ */
+export async function maybePickInteractiveHost() {
+    if (!isInteractiveTerminal())
+        return false;
+    if (getConfigValue('interactive.host').value !== undefined)
+        return false;
+    const macs = macDeviceNames(await loadDevices());
+    if (macs.length < 2)
+        return false;
+    const { select } = await import('@inquirer/prompts');
+    const self = machineId();
+    const picked = await select({
+        message: 'Which machine do you sit at? (agents open browser windows and artifacts there)',
+        default: defaultInteractiveHostChoice(macs, self) ?? SKIP,
+        choices: [
+            ...macs.map((n) => ({ name: n === self ? `${n}  ${chalk.dim('(this machine)')}` : n, value: n })),
+            { name: `Skip ${chalk.dim('— decide later: agents devices set-interactive <name>')}`, value: SKIP },
+        ],
+    });
+    if (picked === SKIP)
+        return false;
+    setConfigValue('interactive.host', picked);
+    console.log(chalk.green(`Interactive host: '${picked}'`) + chalk.dim(' — marked ★ interactive in `agents devices list`.'));
+    return true;
+}
+/**
+ * Offer to pin this machine's default browser profile to a chosen browser.
+ * Only asked when there is nothing to preserve: no configured device default
+ * AND no existing `default` profile (an existing profile is the user's earlier
+ * choice — never re-pinned behind their back). Returns true when a profile was
+ * created and set as the device default. Silent no-op non-TTY.
+ */
+export async function maybePickBrowserProfile() {
+    if (!isInteractiveTerminal())
+        return false;
+    if (getConfiguredDefaultProfileName())
+        return false;
+    if (await getProfile(DEFAULT_BROWSER_PROFILE_NAME))
+        return false;
+    const installed = listInstalledBrowsers();
+    if (installed.length === 0)
+        return false;
+    const { select } = await import('@inquirer/prompts');
+    const picked = await select({
+        message: 'Which browser should agents drive on THIS machine?',
+        default: defaultBrowserChoice(installed) ?? SKIP,
+        choices: [
+            ...installed.map((b) => ({ name: `${b.browserType}  ${chalk.dim(b.binary)}`, value: b.browserType })),
+            { name: `Skip ${chalk.dim('— auto-detect on first use (priority order)')}`, value: SKIP },
+        ],
+    });
+    if (picked === SKIP)
+        return false;
+    const chosen = installed.find((b) => b.browserType === picked) ?? installed[0];
+    const freePort = await findFreeProfilePort();
+    const profile = {
+        name: DEFAULT_BROWSER_PROFILE_NAME,
+        description: `${chosen.browserType} profile (chosen during setup)`,
+        browser: chosen.browserType,
+        binary: chosen.binary,
+        endpoints: [`cdp://127.0.0.1:${freePort}`],
+        viewport: { width: DEFAULT_VIEWPORT.width, height: DEFAULT_VIEWPORT.height },
+    };
+    await createProfile(profile);
+    // The same key `agents browser profiles set-default` writes (device-local).
+    setConfigValue('browser.profile', profile.name);
+    console.log(chalk.green(`Browser: '${chosen.browserType}'`) +
+        chalk.dim(` — profile "${profile.name}" is this machine's default (agents browser profiles set-default to change).`));
+    return true;
+}
+/**
+ * The bare-`agents setup` preferences step: interactive host, then browser.
+ * Runs AFTER the capability hub so it never delays the bootstrap. Never
+ * throws — a prompt cancel or a failed pick ends the step quietly and lets
+ * setup complete (the same semantics as the capability hub).
+ */
+export async function runPreferencesStep() {
+    if (!isInteractiveTerminal())
+        return;
+    try {
+        const pickedHost = await maybePickInteractiveHost();
+        const pickedBrowser = await maybePickBrowserProfile();
+        if (pickedHost || pickedBrowser)
+            console.log();
+    }
+    catch {
+        // Cancel (ctrl-c) or a picker failure — the step is optional; end it.
+    }
+}

package/dist/commands/setup.js

@@ -24,6 +24,7 @@ import { registerSetupShareCommand, runShareWizard } from './setup-share.js';
 import { registerSetupMineCommand } from './setup-mine.js';
 import { registerSetupSecretsCommand } from './setup-secrets.js';
 import { registerSetupFleetCommand } from './setup-fleet.js';
+import { runPreferencesStep } from './setup-preferences.js';
 const HOME = os.homedir();
 /**
  * Import an existing unmanaged agent installation into agents-cli.
@@ -130,15 +131,6 @@ export async function runSetup(program, options = {}) {
     if (dev.ok && dev.synced > 0) {
         console.log(chalk.gray(`Discovered ${dev.synced} device${dev.synced === 1 ? '' : 's'} on your tailnet (agents devices list).`));
     }
-    // Offer guided cross-machine session-sync provisioning (interactive, opt-in,
-    // and never blocking — any failure/decline falls through to the rest of setup).
-    try {
-        const { promptAndProvisionSessionSync } = await import('./sync-provision.js');
-        await promptAndProvisionSessionSync({ explicit: false });
-    }
-    catch (err) {
-        console.log(chalk.yellow(`Session-sync setup skipped: ${err.message}`));
-    }
     // Offer to import existing unmanaged installations
     if (unmanaged.length > 0 && isInteractiveTerminal()) {
         console.log(chalk.bold('\nFound existing installations:\n'));
@@ -201,6 +193,10 @@ export async function runSetup(program, options = {}) {
     // own guided flow. TTY-only and fully opt-in — a non-interactive `agents setup`
     // stops at the system-repo bootstrap above, unchanged.
     await runSetupHub();
+    // Preferences step: the two questions that keep agents off the wrong machine —
+    // which box you sit at (interactive host) and which browser agents drive here.
+    // TTY-only, skippable, and writes the same keys as `agents devices …`.
+    await runPreferencesStep();
     console.log(chalk.bold('\nSetup complete. Try:'));
     console.log(chalk.cyan('  agents view                 ') + chalk.gray(' # see what\'s installed'));
     console.log(chalk.cyan('  agents run <agent> "hello"  ') + chalk.gray(' # run an agent'));
@@ -307,6 +303,9 @@ export function registerSetupCommand(program) {
         1. Clones the system repo into ~/.agents/.system/
         2. Imports any unmanaged agent installations it finds
         3. On a TTY, offers to set up optional capabilities (browser/computer/share/secrets/fleet)
+        4. On a TTY, asks preferences: which machine you sit at (interactive host)
+           and which browser agents drive here — both skippable, both the same
+           keys 'agents devices set-interactive' / 'browser profiles set-default' write
 
       Capability setup can also be run any time on its own:
         agents setup browser    # detect a browser + create the default profile

package/dist/commands/ssh.js

@@ -47,9 +47,12 @@ import { crabboxList, crabboxFind, crabboxSshArgv } from '../lib/crabbox/cli.js'
 import { boxAddress, boxStatus, fmtIdleShort, fmtExpiresShort } from './lease.js';
 import { authCellColor, formatCheckedAge, isDeadVerdict, probeLocalFleetAuth, readAuthHealthCache, summarizeHostAuth, summarizeVerdicts, verdictColor, verdictLabel, writeFleetAuthRows, } from '../lib/auth-health.js';
 import { runFleetLogin } from '../lib/fleet/remote-login.js';
+import { getConfigValue, listConfig, setConfigValue, unsetConfigValue } from '../lib/device-config.js';
+import { setHelpSections } from '../lib/help.js';
 /** One-line summary of a device for `list`. `isSelf` marks the machine this
- * command is running on so it stands out from the rest of the tailnet. */
-function deviceSummary(d, isSelf = false, stats) {
+ * command is running on so it stands out from the rest of the tailnet.
+ * `isInteractive` marks the configured interactive host (`devices set-interactive`). */
+function deviceSummary(d, isSelf = false, stats, isInteractive = false) {
     const addr = hostNameFor(d) ?? chalk.gray('no address');
     // Prefer a fresh live verdict (this run's probe, else the written-back
     // reachability) over the stale tailscale.online snapshot (RUSH-1965).
@@ -63,7 +66,8 @@ function deviceSummary(d, isSelf = false, stats) {
     const marker = isSelf ? chalk.cyan('▸ ') : '  ';
     const name = isSelf ? chalk.bold.cyan(d.name.padEnd(16)) : chalk.bold(d.name.padEnd(16));
     const here = isSelf ? chalk.cyan('  ← this machine') : '';
-    return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}`;
+    const interactive = isInteractive ? chalk.yellow('  ★ interactive') : '';
+    return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}${interactive}`;
 }
 const HEADROOM_BADGE = {
     idle: chalk.green('○ idle'),
@@ -90,9 +94,9 @@ function pctCell(v, width) {
  * Without it (probe skipped) the classic reachability line is used. A fleet
  * capacity summary is appended whenever stats were gathered.
  */
-function renderDeviceTable(reg, names, self, statsMap, full = false) {
+function renderDeviceTable(reg, names, self, statsMap, full = false, interactiveHost) {
     if (!statsMap)
-        return names.map((n) => deviceSummary(reg[n], n === self));
+        return names.map((n) => deviceSummary(reg[n], n === self, undefined, n === interactiveHost));
     const lines = [];
     const head = '  ' +
         chalk.gray('device'.padEnd(16)) +
@@ -132,7 +136,8 @@ function renderDeviceTable(reg, names, self, statsMap, full = false) {
             : '';
         const badge = HEADROOM_BADGE[headroom(stats)];
         const here = isSelf ? chalk.cyan('  ← this machine') : '';
-        lines.push(`${marker}${label}${plat} ${cores}${load}${mem}${freeTotal}  ${badge}${relay}${here}`);
+        const interactive = name === interactiveHost ? chalk.yellow('  ★ interactive') : '';
+        lines.push(`${marker}${label}${plat} ${cores}${load}${mem}${freeTotal}  ${badge}${relay}${here}${interactive}`);
     }
     // Fleet capacity summary — total cores + how much RAM is free right now.
     const cap = fleetCapacity(statsMap.values());
@@ -685,10 +690,13 @@ function registerDevicesCommands(program) {
 Typical workflow:
   agents devices sync            # curate: pick which tailscale nodes to keep (TTY)
   agents devices sync --yes      # non-interactive: register all non-ignored nodes
-  agents devices list            # see what's registered
+  agents devices list            # see what's registered (★ = interactive host)
   agents devices ignore ipad165  # dismiss a node so it's never re-suggested
   agents devices disable zion    # exclude a device from Factory auto-launch
   agents devices prefer mac-mini # boost a device in Factory auto-launch ranking
+  agents devices set-interactive zion        # where agents show YOU artifacts
+  agents devices configure mac-mini --max-agents 4 --scheduler off
+  agents devices note mac-mini "runs the releases — don't reboot"
   agents devices set win-mini --auth password --bundle muqsit
   agents devices render --write  # write ~/.ssh/config.d/agents include
   agents fleet update            # roll out latest agents-cli to every online device
@@ -824,12 +832,214 @@ Typical workflow:
             process.exit(1);
         }
     });
+    const setInteractiveCmd = devicesCmd
+        .command('set-interactive [name]')
+        .description('Get or set the interactive host — the one device that shows YOU artifacts (browser opens, dashboards, rendered plans). Stored fleet-wide as config.interactiveHost in central agents.yaml.')
+        .option('--unset', 'clear the interactive host')
+        .option('--json', 'output machine-readable JSON')
+        .action(async (name, opts) => {
+        try {
+            if (opts.unset) {
+                unsetConfigValue('interactive.host');
+                if (opts.json)
+                    process.stdout.write(JSON.stringify({ interactiveHost: null }, null, 2) + '\n');
+                else
+                    console.log(chalk.green('Cleared the interactive host.'));
+                return;
+            }
+            if (name) {
+                await mustGetDevice(name);
+                setConfigValue('interactive.host', name);
+                if (opts.json)
+                    process.stdout.write(JSON.stringify({ interactiveHost: name }, null, 2) + '\n');
+                else
+                    console.log(chalk.green(`Interactive host: '${name}'`) + chalk.gray(' — agents show you artifacts there. Clear with --unset.'));
+                return;
+            }
+            const current = getConfigValue('interactive.host').value;
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ interactiveHost: current ?? null }, null, 2) + '\n');
+            }
+            else if (current) {
+                console.log(`${chalk.bold('Interactive host:')} ${chalk.cyan(current)}`);
+            }
+            else {
+                console.log(chalk.gray("No interactive host set. Set one with 'agents devices set-interactive <name>'."));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(setInteractiveCmd, {
+        examples: `
+      agents devices set-interactive zion      # zion is where artifacts open for you
+      agents devices set-interactive           # print the current interactive host
+      agents devices set-interactive --unset   # back to no interactive host
+      agents devices set-interactive --json    # machine-readable (for skills)
+    `,
+        notes: `
+      The interactive host answers "which online macOS device do I show this on?"
+      so skills stop guessing. It is marked ★ interactive in 'agents devices list'.
+      The value syncs fleet-wide (central agents.yaml, config.interactiveHost);
+      per-device settings live under 'agents devices configure' instead.
+    `,
+    });
+    const configureCmd = devicesCmd
+        .command('configure <name>')
+        .description('Get or set per-device config: --max-agents, --scheduler. Written to ~/.agents/devices/<name>/agents.yaml (works for any device — the devices/ tree syncs). Unset = default behavior.')
+        .option('--max-agents <n>', 'cap concurrent agents (Factory auto-launch counts device-wide; teams placement counts the team’s roster on the device)')
+        .option('--scheduler <on|off>', 'allow the routines scheduler (daemon) to fire on this device (takes effect on daemon reload/restart)')
+        .option('--json', 'output machine-readable JSON')
+        .action(async (name, opts) => {
+        try {
+            await mustGetDevice(name);
+            const parseOnOff = (flag, raw) => {
+                if (raw === 'on')
+                    return true;
+                if (raw === 'off')
+                    return false;
+                throw new Error(`--${flag} expects 'on' or 'off', got '${raw}'.`);
+            };
+            const writes = [];
+            if (opts.maxAgents !== undefined) {
+                const n = Number(opts.maxAgents);
+                if (!Number.isInteger(n))
+                    throw new Error(`--max-agents expects an integer, got '${opts.maxAgents}'.`);
+                writes.push(['agents.max-concurrent', n]);
+            }
+            if (opts.scheduler !== undefined)
+                writes.push(['scheduler.enabled', parseOnOff('scheduler', opts.scheduler)]);
+            if (writes.length > 0) {
+                for (const [key, value] of writes)
+                    setConfigValue(key, value, { device: name });
+                if (!opts.json) {
+                    for (const [key, value] of writes) {
+                        console.log(chalk.green(`Set ${key} = ${JSON.stringify(value)}`) + chalk.gray(` on '${name}'.`));
+                    }
+                }
+            }
+            if (opts.json || writes.length === 0) {
+                const entries = listConfig({ device: name }).filter((e) => e.spec.scope === 'device');
+                if (opts.json) {
+                    const config = {};
+                    for (const e of entries)
+                        if (e.value !== undefined)
+                            config[e.spec.name] = e.value;
+                    process.stdout.write(JSON.stringify({ device: name, config }, null, 2) + '\n');
+                }
+                else {
+                    console.log(chalk.bold(`Config for '${name}'`));
+                    for (const e of entries) {
+                        const value = e.value === undefined ? chalk.gray('— (default)') : chalk.cyan(JSON.stringify(e.value));
+                        console.log(`  ${e.spec.name.padEnd(24)} ${value}${chalk.gray(`  ${e.spec.description}`)}`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(configureCmd, {
+        examples: `
+      agents devices configure mac-mini --max-agents 4      # cap concurrent agents
+      agents devices configure mac-mini --scheduler off     # no routines firing there
+      agents devices configure mac-mini                     # print its current config
+      agents devices configure mac-mini --json              # machine-readable
+    `,
+        notes: `
+      Run it on any machine for any device: the value lands in
+      ~/.agents/devices/<name>/agents.yaml locally and reaches the device on the
+      next 'agents repo push/pull'. Unset keys keep today's behavior.
+      --scheduler takes effect when the daemon reloads or restarts on that
+      device ('agents routines start' / the reload a 'routines add' sends).
+      For the default browser profile use 'agents browser profiles set-default
+      <name>'; for free-form text use 'agents devices note'.
+    `,
+    });
+    const noteCmd = devicesCmd
+        .command('note <name> [text...]')
+        .description('Append a free-form note to a device (repeat to append more). No text prints the notes; --clear empties them.')
+        .option('--clear', 'remove all notes from the device')
+        .option('--json', 'output machine-readable JSON')
+        .action(async (name, text, opts) => {
+        try {
+            await mustGetDevice(name);
+            if (opts.clear) {
+                unsetConfigValue('notes', { device: name });
+                if (opts.json)
+                    process.stdout.write(JSON.stringify({ device: name, notes: [] }, null, 2) + '\n');
+                else
+                    console.log(chalk.green(`Cleared notes on '${name}'.`));
+                return;
+            }
+            if (text.length > 0) {
+                const existing = getConfigValue('notes', { device: name }).value ?? [];
+                const notes = [...existing, text.join(' ')];
+                setConfigValue('notes', notes, { device: name });
+                if (opts.json)
+                    process.stdout.write(JSON.stringify({ device: name, notes }, null, 2) + '\n');
+                else
+                    console.log(chalk.green(`Noted on '${name}':`) + ` ${text.join(' ')}`);
+                return;
+            }
+            const notes = getConfigValue('notes', { device: name }).value ?? [];
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ device: name, notes }, null, 2) + '\n');
+            }
+            else if (notes.length > 0) {
+                console.log(chalk.bold(`Notes for '${name}'`));
+                for (const n of notes)
+                    console.log(`  ${chalk.gray('•')} ${n}`);
+            }
+            else {
+                console.log(chalk.gray(`No notes on '${name}'. Add one with 'agents devices note ${name} "..."'.`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(noteCmd, {
+        examples: `
+      agents devices note mac-mini "runs the releases — don't reboot"
+      agents devices note mac-mini "4 displays attached"   # appends a second note
+      agents devices note mac-mini                         # print its notes
+      agents devices note mac-mini --clear                 # drop them all
+    `,
+        notes: `
+      Notes are operator memory for a box (why it exists, what to never do to
+      it). They sync like every other device doc; 'agents devices list --json'
+      carries them under config.notes.
+    `,
+    });
+    /** Device-scope config block for `list --json`, keyed by yamlKey (set keys only). */
+    const deviceConfigJson = (name) => {
+        const config = {};
+        for (const entry of listConfig({ device: name })) {
+            if (entry.spec.scope !== 'device' || entry.value === undefined)
+                continue;
+            config[entry.spec.yamlKey] = entry.value;
+        }
+        return Object.keys(config).length > 0 ? config : undefined;
+    };
     const runList = async (opts = {}) => {
         const reg = await loadDevices();
         const names = Object.keys(reg).sort();
+        const interactiveHost = getConfigValue('interactive.host').value;
         if (opts.json) {
-            // Registry-only, always fast — the Factory extension polls this path.
-            process.stdout.write(JSON.stringify(names.map((n) => reg[n]), null, 2) + '\n');
+            // Registry + local device docs, always fast — the Factory extension polls
+            // this path. Each row carries its device-scope `config` (maxAgents,
+            // schedulerEnabled, notes, defaultBrowserProfile — set keys
+            // only) and an `interactive` flag for the configured interactive host.
+            process.stdout.write(JSON.stringify(names.map((n) => {
+                const config = deviceConfigJson(n);
+                return { ...reg[n], interactive: n === interactiveHost, ...(config ? { config } : {}) };
+            }), null, 2) + '\n');
             return;
         }
         if (names.length === 0) {
@@ -867,7 +1077,7 @@ Typical workflow:
                 await writeReachability(collectReachabilityWriteBacks(reg, statsMap)).catch(() => { });
         }
         console.log(chalk.bold(`Devices (${names.length})`));
-        for (const line of renderDeviceTable(reg, names, self, statsMap, opts.full))
+        for (const line of renderDeviceTable(reg, names, self, statsMap, opts.full, interactiveHost))
             console.log(line);
         if (freshness?.servedFromCache && freshness.oldestFetchedAt != null) {
             console.log(chalk.gray(`  updated ${formatCheckedAge(freshness.oldestFetchedAt)} — pass --refresh (--live) for a live probe`));

package/dist/commands/sync.d.ts

@@ -2,8 +2,8 @@
  * `agents sync` — synchronize central resources into an installed agent version.
  *
  * Forms:
- *   agents sync                                         # umbrella: fetch config repos -> reconcile all (secrets/sessions opt-in)
- *   agents sync --repos|--secrets|--sessions            # umbrella: fetch only those, then reconcile
+ *   agents sync                                         # umbrella: fetch config repos -> reconcile all (secrets opt-in)
+ *   agents sync --repos|--secrets                       # umbrella: fetch only those, then reconcile
  *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
  *   agents sync --local                                 # umbrella: reconcile all, no fetch
  *   agents sync system                                  # one repo: git pull --rebase (pull-only mirror)

package/dist/commands/sync.js

@@ -2,8 +2,8 @@
  * `agents sync` — synchronize central resources into an installed agent version.
  *
  * Forms:
- *   agents sync                                         # umbrella: fetch config repos -> reconcile all (secrets/sessions opt-in)
- *   agents sync --repos|--secrets|--sessions            # umbrella: fetch only those, then reconcile
+ *   agents sync                                         # umbrella: fetch config repos -> reconcile all (secrets opt-in)
+ *   agents sync --repos|--secrets                       # umbrella: fetch only those, then reconcile
  *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
  *   agents sync --local                                 # umbrella: reconcile all, no fetch
  *   agents sync system                                  # one repo: git pull --rebase (pull-only mirror)
@@ -47,7 +47,7 @@ import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos } from '../l
 export function registerSyncCommand(program) {
     addHostOption(program.command('sync [agentSpec] [repo]'))
         .summary('Make this machine current, or sync resources into one agent')
-        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude", "claude@2.1.142", a selector: @latest / @oldest / @pinned (= @default), or @all for every installed version.\n\nAppend a [repo] (or pass --repo) to scope the sync to a single DotAgent repo — system / user / project / <alias>. e.g. "agents sync claude@all system" reconciles only the system repo\'s resources into every installed Claude.\n\nGive a DotAgent repo name ALONE — "agents sync system" / "agents sync user" / "agents sync <alias>" — to git-sync that one repo: refuse if the tree is dirty, else git pull --rebase against origin. The user repo and extra aliases also push local commits up; the system repo is a pull-only mirror.\n\nWith NO agent, runs the umbrella verb: fetch the config repos then reconcile them into every installed agent. Secrets and sessions are opt-in — add --secrets to pull secret bundles or --sessions to sync transcripts (sessions are also queryable live via "agents sessions --host <machine>"). Also: --cloud (fetch only), --local (reconcile only).')
+        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude", "claude@2.1.142", a selector: @latest / @oldest / @pinned (= @default), or @all for every installed version.\n\nAppend a [repo] (or pass --repo) to scope the sync to a single DotAgent repo — system / user / project / <alias>. e.g. "agents sync claude@all system" reconciles only the system repo\'s resources into every installed Claude.\n\nGive a DotAgent repo name ALONE — "agents sync system" / "agents sync user" / "agents sync <alias>" — to git-sync that one repo: refuse if the tree is dirty, else git pull --rebase against origin. The user repo and extra aliases also push local commits up; the system repo is a pull-only mirror.\n\nWith NO agent, runs the umbrella verb: fetch the config repos then reconcile them into every installed agent. Secrets are opt-in — add --secrets to pull secret bundles. Session transcripts are queryable live via "agents sessions --host <machine>", or moved with "agents sessions export/import". Also: --cloud (fetch only), --local (reconcile only).')
         .option('--agent <agent>', 'Agent identifier (legacy form; prefer the positional spec)')
         .option('--agent-version <version>', 'Version to sync into (legacy form; prefer "agent@version")')
         .option('--repo <name>', 'Scope the sync to a single DotAgent repo: system / user / project / <alias> (also accepted as a positional)')
@@ -60,7 +60,6 @@ export function registerSyncCommand(program) {
         // Umbrella verb (no agent given): make this machine current.
         .option('--repos', 'Umbrella: git-pull ~/.agents + enabled ~/.agents-* extras', false)
         .option('--secrets', 'Umbrella: pull encrypted secret bundles from the remote', false)
-        .option('--sessions', 'Umbrella: sync session transcripts across machines', false)
         .option('--cloud', 'Umbrella: fetch all remote state but skip the local reconcile', false)
         .option('--local', "Umbrella: reconcile resources into installed agents only (no fetch)", false)
         .action(async (agentSpec, repo, opts) => {
@@ -206,7 +205,7 @@ async function runUmbrella(opts, quiet, outLog, errLog) {
     // Interactive bare `agents sync` (a TTY, no --yes, no scope flag) drops into
     // the two-checklist picker: which repos to sync from, which agents to sync
     // into. Any explicit flag or --yes keeps the non-interactive umbrella below.
-    const anyExplicitFlag = !!(opts.repos || opts.secrets || opts.sessions || opts.cloud || opts.local);
+    const anyExplicitFlag = !!(opts.repos || opts.secrets || opts.cloud || opts.local);
     if (!quiet && !opts.yes && !anyExplicitFlag && isInteractiveTerminal()) {
         await runInteractiveReconcile(opts, outLog, errLog);
         return;
@@ -214,7 +213,6 @@ async function runUmbrella(opts, quiet, outLog, errLog) {
     const flags = {
         repos: opts.repos,
         secrets: opts.secrets,
-        sessions: opts.sessions,
         cloud: opts.cloud,
         local: opts.local,
     };
@@ -238,9 +236,6 @@ async function runUmbrella(opts, quiet, outLog, errLog) {
             if (result.secrets) {
                 parts.push(result.secrets.skipped ? 'secrets skipped' : `secrets ${result.secrets.pulled} pulled`);
             }
-            if (result.sessions) {
-                parts.push(result.sessions.ran ? `sessions ${result.sessions.merged} merged` : 'sessions off');
-            }
             if (result.reconciled)
                 parts.push('reconciled');
             outLog(chalk.green(`✓ sync: ${parts.join(' · ') || 'nothing to do'}`));

package/dist/commands/watchdog.js

@@ -24,6 +24,9 @@ import { setHelpSections } from '../lib/help.js';
 import { parseDuration } from '../lib/hooks/cache.js';
 import { getRuntimeStateDir } from '../lib/state.js';
 import { setJobEnabled } from '../lib/routines.js';
+import { getActiveSessions } from '../lib/session/active.js';
+import { mailboxIdForActiveSession } from '../lib/mailbox-target.js';
+import { gcMailbox } from '../lib/mailbox-gc.js';
 import { ensureWatchdogRoutine, isWatchdogRoutineEnabled, watchdogRoutineExists, WATCHDOG_ROUTINE_NAME, WATCHDOG_ROUTINE_SCHEDULE, } from '../lib/watchdog/routine.js';
 import { runWatchdogTick, writePolicySentinel, DEFAULT_THRESHOLDS, } from '../lib/watchdog/runner.js';
 /** Default state dir the runner and these subcommands share. */
@@ -58,6 +61,21 @@ function humanMs(ms) {
         return `${Math.round(ms / 60_000)}m`;
     return `${Math.round(ms / 1000)}s`;
 }
+/**
+ * Run the mailbox liveness sweep against the same session set the tick just used.
+ * Idempotent and cheap: archiving a message twice is a no-op, and GC only scans
+ * directories. Failures are swallowed so a mailbox-root problem cannot break the
+ * watchdog tick.
+ */
+async function runMailboxGc(sessions) {
+    const activeBoxIds = new Set(sessions.map(mailboxIdForActiveSession).filter((id) => !!id));
+    try {
+        gcMailbox(activeBoxIds);
+    }
+    catch {
+        // GC is best-effort housekeeping; the next tick will retry.
+    }
+}
 function colorForOutcome(o) {
     if (o.injected)
         return chalk.green;
@@ -118,7 +136,7 @@ export function registerWatchdogCommand(program) {
         // path is the daemon routine, which runs `agents watchdog --nudge` — so the
         // routine's enabled state IS the on/off switch, not a flag read here.
         const computeWillInject = () => opts.nudge === true;
-        const tickOnce = async (willInject) => runWatchdogTick({
+        const tickOnce = async (willInject, sessions) => runWatchdogTick({
             nudge: willInject,
             nudgeText: opts.text,
             smart: opts.smart === true,
@@ -126,10 +144,13 @@ export function registerWatchdogCommand(program) {
             thresholds,
             allowGhosttyFocus: opts.allowGhosttyFocus === true,
             stateDir: stateDir(),
+            sessions,
         });
         if (!opts.watch) {
             const willInject = computeWillInject();
-            const result = await tickOnce(willInject);
+            const sessions = await getActiveSessions();
+            const result = await tickOnce(willInject, sessions);
+            await runMailboxGc(sessions);
             if (opts.json)
                 console.log(JSON.stringify(result, null, 2));
             else
@@ -146,7 +167,9 @@ export function registerWatchdogCommand(program) {
         while (true) {
             // Re-evaluated each tick: picks up enable/disable flips mid-run.
             const willInject = computeWillInject();
-            const result = await tickOnce(willInject);
+            const sessions = await getActiveSessions();
+            const result = await tickOnce(willInject, sessions);
+            await runMailboxGc(sessions);
             if (opts.json)
                 console.log(JSON.stringify(result));
             else