@phnx-labs/agents-cli 1.20.54 → 1.20.56

package/dist/commands/tmux.js

@@ -24,7 +24,7 @@ import chalk from 'chalk';
 import { truncate } from '../lib/format.js';
 import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
-import { assertTmuxAvailable, attachTmux, capturePane, createSession, getDefaultSocketPath, getTmuxVersion, hasSession, isTmuxInstalled, killAll, killSession, listSessions, readSessionMeta, sendKeys, splitPane, TmuxCommandError, TmuxSessionError, TmuxUnavailableError, } from '../lib/tmux/index.js';
+import { assertTmuxAvailable, attachTmux, capturePane, createSession, getDefaultSocketPath, getTmuxVersion, hasSession, isTmuxInstalled, isTmuxVersionSupported, killAll, killSession, listSessions, MIN_TMUX_VERSION, readSessionMeta, sendKeys, splitPane, TmuxCommandError, TmuxSessionError, TmuxUnavailableError, } from '../lib/tmux/index.js';
 /** Register the `agents tmux` command tree. */
 export function registerTmuxCommands(program) {
     const tmux = program
@@ -70,14 +70,22 @@ export function registerTmuxCommands(program) {
     checkCmd.action((opts) => {
         const installed = isTmuxInstalled();
         const version = installed ? getTmuxVersion() : null;
+        const supported = isTmuxVersionSupported(version);
         if (opts.json) {
-            console.log(JSON.stringify({ installed, version, socket: getDefaultSocketPath() }));
+            console.log(JSON.stringify({ installed, supported, version, minimumVersion: MIN_TMUX_VERSION, socket: getDefaultSocketPath() }));
+            if (installed && !supported)
+                process.exitCode = 1;
             return;
         }
-        if (installed) {
+        if (installed && supported) {
             console.log(chalk.green('tmux:'), version ?? '(version unknown)');
             console.log(chalk.gray(`socket: ${getDefaultSocketPath()}`));
         }
+        else if (installed) {
+            console.log(chalk.yellow('tmux:'), `${version ?? '(version unknown)'} — unsupported`);
+            console.log(chalk.gray(`  agents requires tmux ${MIN_TMUX_VERSION} or newer.`));
+            process.exitCode = 1;
+        }
         else {
             console.log(chalk.yellow('tmux is not installed.'));
             console.log(chalk.gray(process.platform === 'darwin'

package/dist/index.js

@@ -874,7 +874,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
         // Bumping the suffix re-runs migrations for every user; binary releases that
         // don't change the schema must NOT re-run (they would destroy user content
         // when migration steps overlap with user-authored paths). See issue #20.
-        const sentinelValue = 'v11';
+        const sentinelValue = 'v12';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {

package/dist/lib/daemon.d.ts

@@ -12,6 +12,14 @@ export declare function readDaemonPid(): number | null;
 export declare function writeDaemonPid(pid: number): void;
 /** Remove the daemon PID file. */
 export declare function removeDaemonPid(): void;
+export interface DaemonHeartbeat {
+    lastTick: string;
+    pid: number;
+}
+export declare function writeHeartbeat(pid?: number): void;
+export declare function readHeartbeat(): DaemonHeartbeat | null;
+export declare function removeHeartbeat(): void;
+export declare function isDaemonWedged(): boolean;
 /** Check if the daemon process is alive by sending signal 0 to the stored PID. */
 export declare function isDaemonRunning(): boolean;
 /**
@@ -77,7 +85,7 @@ export declare function writeOwnerOnlyServiceManifest(filePath: string, content:
 export declare function generateLaunchdPlist(oauthToken?: string | null): string;
 /** Generate a Linux systemd user unit for auto-starting the daemon. */
 export declare function generateSystemdUnit(oauthToken?: string | null): string;
-export declare function getAgentsBinPath(): string;
+export declare function getAgentsBinPath(argv1?: string | undefined, execPath?: string): string;
 /** Start the daemon via launchd, systemd, or as a detached process. */
 export declare function startDaemon(): {
     pid: number | null;
@@ -128,6 +136,27 @@ export declare function getDaemonLaunch(agentsBin?: string): {
     command: string;
     args: string[];
 };
+/**
+ * Build the argv to relaunch the `agents` CLI with the given subcommand args.
+ *
+ * Resolves the real on-disk binary via getAgentsBinPath(), then dispatches: a
+ * `.js` entry runs under node (`node <entry> …`), a native/compiled binary runs
+ * directly (`<bin> …`).
+ *
+ * Callers MUST route self-spawns through this rather than hand-rolling
+ * `[process.execPath, process.argv[1], …]`: under the compiled standalone binary
+ * (#315) `process.argv[1]` is the bun virtual entry `/$bunfs/root/agents`, so the
+ * hand-rolled form becomes `agents /$bunfs/root/agents …` → the CLI receives the
+ * bunfs path as a subcommand and dies with "unknown command '/$bunfs/root/agents'".
+ * getAgentsBinPath() resolves that virtual entry to the physical process.execPath.
+ */
+export declare function getAgentsInvocation(subArgs: string[], agentsBin?: string): {
+    command: string;
+    args: string[];
+};
+export declare function validateDaemonBinary(binPath: string): {
+    warnings: string[];
+};
 interface StartDetachedOptions {
     /** CLI entry to launch (defaults to the running binary). Injectable for tests. */
     agentsBin?: string;
@@ -144,10 +173,13 @@ export declare function startDetached(opts?: StartDetachedOptions): {
 export declare function stopDaemon(): boolean;
 /** Get current daemon status including running state, PID, and enabled job count. */
 export declare function getDaemonStatus(): {
+    state: 'running' | 'wedged' | 'stopped';
     running: boolean;
     pid: number | null;
     jobCount: number;
     logPath: string;
+    binaryPath: string | null;
+    heartbeat: DaemonHeartbeat | null;
 };
 /** Read the daemon log, optionally limited to the last N lines. */
 export declare function readDaemonLog(lines?: number): string;

package/dist/lib/daemon.js

@@ -23,10 +23,13 @@ import { redactSecrets } from './redact.js';
 const PID_FILE = 'daemon.pid';
 const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'logs.jsonl';
+const HEARTBEAT_FILE = 'heartbeat.json';
 const LOG_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
 const LOG_ROTATE_COUNT = 3;
 const PLIST_NAME = 'com.phnx-labs.agents-daemon';
 const SYSTEMD_UNIT = 'agents-daemon.service';
+const MONITOR_TICK_MS = 60_000;
+const WEDGE_THRESHOLD_TICKS = 3;
 // A long-lived `claude setup-token` value stored in this secrets bundle/key is
 // baked into the daemon's service-manager environment so headless routine runs
 // authenticate without depending on the short-lived interactive Keychain OAuth
@@ -118,6 +121,48 @@ export function removeDaemonPid() {
         fs.unlinkSync(pidPath);
     }
 }
+function getHeartbeatPath() {
+    return path.join(getDaemonDir(), HEARTBEAT_FILE);
+}
+export function writeHeartbeat(pid = process.pid) {
+    const hb = { lastTick: new Date().toISOString(), pid };
+    try {
+        fs.writeFileSync(getHeartbeatPath(), JSON.stringify(hb), 'utf-8');
+    }
+    catch { /* best effort */ }
+}
+export function readHeartbeat() {
+    try {
+        const raw = fs.readFileSync(getHeartbeatPath(), 'utf-8');
+        const hb = JSON.parse(raw);
+        if (!hb.lastTick || !hb.pid)
+            return null;
+        return hb;
+    }
+    catch {
+        return null;
+    }
+}
+export function removeHeartbeat() {
+    try {
+        fs.unlinkSync(getHeartbeatPath());
+    }
+    catch { /* already removed */ }
+}
+export function isDaemonWedged() {
+    const pid = readDaemonPid();
+    if (!pid)
+        return false;
+    if (!isAlive(pid))
+        return false;
+    const hb = readHeartbeat();
+    if (!hb)
+        return false;
+    if (hb.pid !== pid)
+        return false;
+    const elapsed = Date.now() - Date.parse(hb.lastTick);
+    return elapsed > WEDGE_THRESHOLD_TICKS * MONITOR_TICK_MS;
+}
 /** Check if the daemon process is alive by sending signal 0 to the stored PID. */
 export function isDaemonRunning() {
     const pid = readDaemonPid();
@@ -323,9 +368,11 @@ export async function runDaemon() {
     catch (err) {
         log('ERROR', `Browser IPC failed to start: ${err.message}`);
     }
+    writeHeartbeat();
     const monitorInterval = setInterval(() => {
+        writeHeartbeat();
         monitorRunningJobs();
-    }, 60_000);
+    }, MONITOR_TICK_MS);
     // Cross-machine session sync: push this machine's transcripts to R2 and pull
     // every other machine's, ~every 90s. Skipped silently when the r2.backups
     // bundle is absent. An overlap guard prevents a slow cycle from stacking.
@@ -548,6 +595,7 @@ export async function runDaemon() {
         clearInterval(launchHealthInterval);
         clearTimeout(launchHealthKickoff);
         removeDaemonPid();
+        removeHeartbeat();
         process.exit(0);
     };
     process.on('SIGHUP', handleReload);
@@ -605,6 +653,7 @@ export function writeOwnerOnlyServiceManifest(filePath, content) {
 /** Generate a macOS launchd plist for auto-starting the daemon. */
 export function generateLaunchdPlist(oauthToken = readDaemonClaudeOAuthToken()) {
     const agentsBin = getAgentsBinPath();
+    const launch = getDaemonLaunch(agentsBin);
     const logPath = getLogPath();
     const oauthEntry = oauthToken
         ? `
@@ -619,9 +668,7 @@ export function generateLaunchdPlist(oauthToken = readDaemonClaudeOAuthToken())
   <string>${PLIST_NAME}</string>
   <key>ProgramArguments</key>
   <array>
-    <string>${agentsBin}</string>
-    <string>daemon</string>
-    <string>_run</string>
+${[launch.command, ...launch.args].map((arg) => `    <string>${xmlEscape(arg)}</string>`).join('\n')}
   </array>
   <key>RunAtLoad</key>
   <true/>
@@ -639,9 +686,15 @@ export function generateLaunchdPlist(oauthToken = readDaemonClaudeOAuthToken())
 </dict>
 </plist>`;
 }
+/** Quote one systemd ExecStart argument without delegating parsing to a shell. */
+function systemdExecArg(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
 /** Generate a Linux systemd user unit for auto-starting the daemon. */
 export function generateSystemdUnit(oauthToken = readDaemonClaudeOAuthToken()) {
     const agentsBin = getAgentsBinPath();
+    const launch = getDaemonLaunch(agentsBin);
+    const execStart = [launch.command, ...launch.args].map(systemdExecArg).join(' ');
     const oauthLine = oauthToken
         ? `\nEnvironment=${DAEMON_OAUTH_KEY}=${oauthToken}`
         : '';
@@ -651,7 +704,7 @@ After=network.target
 
 [Service]
 Type=simple
-ExecStart=${agentsBin} daemon _run
+ExecStart=${execStart}
 Restart=always
 RestartSec=10
 Environment=PATH=/usr/local/bin:/usr/bin:/bin:${os.homedir()}/.nvm/versions/node/v24.0.0/bin${oauthLine}
@@ -659,28 +712,39 @@ Environment=PATH=/usr/local/bin:/usr/bin:/bin:${os.homedir()}/.nvm/versions/node
 [Install]
 WantedBy=default.target`;
 }
-export function getAgentsBinPath() {
+const BUN_VIRTUAL_ROOT = /[/\\]\$bunfs[/\\]root[/\\]/;
+function resolveBunStandaloneEntry(entry, execPath) {
+    if (!BUN_VIRTUAL_ROOT.test(entry))
+        return entry;
+    if (!execPath || BUN_VIRTUAL_ROOT.test(execPath) || !fs.existsSync(execPath)) {
+        throw new Error(`Cannot resolve agents CLI: Bun standalone executable not found at ${execPath || '(empty path)'}`);
+    }
+    return execPath;
+}
+export function getAgentsBinPath(argv1 = process.argv[1], execPath = process.execPath) {
     // Prefer the binary actively executing this code. `which agents` returns
     // whatever happens to be first on PATH, which means a side-by-side dev
     // build at ~/.local/bin would silently spawn the registry-installed
-    // daemon and run stale code. process.argv[1] is the absolute path of
-    // the JS entrypoint the user actually invoked.
-    const argv1 = process.argv[1];
-    if (argv1 && fs.existsSync(argv1)) {
+    // daemon and run stale code. For a JS install, process.argv[1] is the
+    // absolute entrypoint the user actually invoked. A Bun standalone instead
+    // exposes its embedded /$bunfs/root entry at argv[1] and its physical signed
+    // executable at process.execPath; Bun reports both as existing paths.
+    const runningEntry = argv1 ? resolveBunStandaloneEntry(argv1, execPath) : undefined;
+    if (runningEntry && fs.existsSync(runningEntry)) {
         // The package's browser/computer entrypoints are sibling shims without a
         // `daemon` command. A daemon started as their IPC side effect must launch
         // through the main agents entrypoint instead of replaying the shim path.
-        const entryName = path.basename(argv1);
+        const entryName = path.basename(runningEntry);
         const compiledShim = /^(browser|computer)\.(c|m)?js$/.test(entryName);
         const installedShim = /^(browser|computer)$/.test(entryName);
         if (compiledShim || installedShim) {
-            const agentsEntry = path.join(path.dirname(argv1), compiledShim ? 'index.js' : 'agents');
+            const agentsEntry = path.join(path.dirname(runningEntry), compiledShim ? 'index.js' : 'agents');
             if (!fs.existsSync(agentsEntry)) {
                 throw new Error(`Cannot start agents daemon: main CLI entry not found at ${agentsEntry}`);
             }
             return agentsEntry;
         }
-        return argv1;
+        return runningEntry;
     }
     try {
         return execFileSync('which', ['agents'], { encoding: 'utf-8' }).trim();
@@ -842,11 +906,50 @@ export function buildDetachedDaemonEnv(baseEnv = process.env, oauthToken = readD
  * `which agents`), run it directly — it owns its own runtime resolution.
  */
 export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
+    const { warnings } = validateDaemonBinary(agentsBin);
+    for (const w of warnings)
+        process.stderr.write(`[agents] ${w}\n`);
     if (/\.(c|m)?js$/.test(agentsBin)) {
         return { command: process.execPath, args: [agentsBin, 'daemon', '_run'] };
     }
     return { command: agentsBin, args: ['daemon', '_run'] };
 }
+/**
+ * Build the argv to relaunch the `agents` CLI with the given subcommand args.
+ *
+ * Resolves the real on-disk binary via getAgentsBinPath(), then dispatches: a
+ * `.js` entry runs under node (`node <entry> …`), a native/compiled binary runs
+ * directly (`<bin> …`).
+ *
+ * Callers MUST route self-spawns through this rather than hand-rolling
+ * `[process.execPath, process.argv[1], …]`: under the compiled standalone binary
+ * (#315) `process.argv[1]` is the bun virtual entry `/$bunfs/root/agents`, so the
+ * hand-rolled form becomes `agents /$bunfs/root/agents …` → the CLI receives the
+ * bunfs path as a subcommand and dies with "unknown command '/$bunfs/root/agents'".
+ * getAgentsBinPath() resolves that virtual entry to the physical process.execPath.
+ */
+export function getAgentsInvocation(subArgs, agentsBin = getAgentsBinPath()) {
+    const resolvedBin = resolveBunStandaloneEntry(agentsBin, process.execPath);
+    if (/\.(c|m)?js$/.test(resolvedBin)) {
+        return { command: process.execPath, args: [resolvedBin, ...subArgs] };
+    }
+    return { command: resolvedBin, args: subArgs };
+}
+export function validateDaemonBinary(binPath) {
+    const warnings = [];
+    if (BUN_VIRTUAL_ROOT.test(binPath)) {
+        throw new Error(`Refusing to supervise daemon: resolved binary is a bun virtual path (${binPath}). ` +
+            `Install agents globally (npm i -g @phnx-labs/agents-cli) and restart.`);
+    }
+    if (/[/\\]\.agents[/\\]worktrees[/\\]/.test(binPath)) {
+        warnings.push(`Warning: daemon binary is inside a git worktree (${binPath}). ` +
+            `A worktree deletion will wedge the daemon. Use the globally installed binary instead.`);
+    }
+    if (!fs.existsSync(binPath) && !/\.(c|m)?js$/.test(binPath)) {
+        warnings.push(`Warning: daemon binary does not exist on disk (${binPath}).`);
+    }
+    return { warnings };
+}
 export function startDetached(opts = {}) {
     const agentsBin = opts.agentsBin ?? getAgentsBinPath();
     const logPath = opts.logPath ?? getLogPath();
@@ -948,13 +1051,27 @@ export function stopDaemon() {
 /** Get current daemon status including running state, PID, and enabled job count. */
 export function getDaemonStatus() {
     const running = isDaemonRunning();
+    const wedged = running && isDaemonWedged();
     const pid = readDaemonPid();
     let jobCount = 0;
     try {
         jobCount = listAllJobs().filter((j) => j.enabled).length;
     }
     catch { /* job listing failed */ }
-    return { running, pid, jobCount, logPath: getLogPath() };
+    let binaryPath = null;
+    try {
+        binaryPath = getAgentsBinPath();
+    }
+    catch { /* resolution failed */ }
+    return {
+        state: wedged ? 'wedged' : running ? 'running' : 'stopped',
+        running,
+        pid,
+        jobCount,
+        logPath: getLogPath(),
+        binaryPath,
+        heartbeat: readHeartbeat(),
+    };
 }
 /** Read the daemon log, optionally limited to the last N lines. */
 export function readDaemonLog(lines) {

package/dist/lib/devices/sync.d.ts

@@ -11,6 +11,13 @@ import type { PendingDevice } from './pending.js';
  * the wrong account). Returns undefined when the username isn't a safe ssh
  * identifier, so a weird value never lands in the registry. */
 export declare function localLoginUser(): string | undefined;
+/**
+ * Reduce a raw OS username to a safe ssh account, or undefined. Windows reports
+ * the login as `COMPUTER\user` / `DOMAIN\user`; the ssh account is the bare name
+ * after the backslash — without this strip the `\` fails the charset guard and
+ * Windows boxes never pin a user. Pure, so the platform-specific munging is
+ * unit-tested without reading the real OS user. */
+export declare function sanitizeLoginUser(raw: string | undefined): string | undefined;
 /**
  * Fill in a device's login user during sync WITHOUT ever clobbering an account
  * the user pinned. Precedence: an existing registered user wins; else the local

package/dist/lib/devices/sync.js

@@ -34,7 +34,19 @@ export function localLoginUser() {
     catch {
         u = process.env.USER || process.env.USERNAME || undefined;
     }
-    return u && /^[a-zA-Z0-9._-]+$/.test(u) ? u : undefined;
+    return sanitizeLoginUser(u);
+}
+/**
+ * Reduce a raw OS username to a safe ssh account, or undefined. Windows reports
+ * the login as `COMPUTER\user` / `DOMAIN\user`; the ssh account is the bare name
+ * after the backslash — without this strip the `\` fails the charset guard and
+ * Windows boxes never pin a user. Pure, so the platform-specific munging is
+ * unit-tested without reading the real OS user. */
+export function sanitizeLoginUser(raw) {
+    if (!raw)
+        return undefined;
+    const bare = raw.includes('\\') ? raw.slice(raw.lastIndexOf('\\') + 1) : raw;
+    return /^[a-zA-Z0-9._-]+$/.test(bare) ? bare : undefined;
 }
 /**
  * Fill in a device's login user during sync WITHOUT ever clobbering an account

package/dist/lib/exec.js

@@ -927,14 +927,16 @@ async function runInTmux(options, executable, args) {
         // When the AGENT pane dies, detach the client (don't kill) so the session
         // survives just long enough to read the dead pane's exit status below. The
         // `#{hook_pane}` guard scopes this to the agent pane only: if the user splits
-        // the window and exits one of THEIR panes, the else-branch `kill-pane` closes
-        // that split in place instead of detaching everyone (the pane-died hook runs
-        // in the dead pane's context, so bare `kill-pane` targets it). Without the
-        // guard, exiting any split kicked the user clean out of tmux.
-        await setSessionHook(name, 'pane-died', agentPaneDiedHook(name, pane), socket);
-        // Stamp the schema marker so the daemon reconcile (which retrofits older
-        // sessions) recognizes this one as already current and skips it.
-        await markSessionHookSchema(name, socket);
+        // the window and exits one of THEIR panes, the else-branch closes that split
+        // in place instead of detaching everyone (`run-shell -C` executes the
+        // targeted kill inside tmux's server command queue, avoiding a second
+        // client racing the same socket under load, #965). Without the guard,
+        // exiting any split kicked the user clean out of tmux.
+        const hookInstalled = await setSessionHook(name, 'pane-died', agentPaneDiedHook(name, pane), socket);
+        // Stamp the schema marker only after tmux accepted the hook. A failed
+        // install stays unmarked so daemon reconciliation retries it later.
+        if (hookInstalled)
+            await markSessionHookSchema(name, socket);
         // Record the agent's OS pid (the pane leaf, thanks to `exec`) WITH its tmux
         // pane so the active-scan attributes it exactly and shows the %pane.
         let panePid = 0;

package/dist/lib/hosts/passthrough.js

@@ -34,6 +34,7 @@ const REMOTE_PASSTHROUGH = {
     sync: { nonInteractive: ['--yes'] },
     teams: {},
     message: {},
+    routines: {},
 };
 /** `--no-tty` is stripped like the routing flags but carries no value. */
 const STRIP_SPECS = [...HOST_ROUTING_SPECS, { long: 'no-tty', takesValue: false }];
@@ -115,10 +116,13 @@ export async function maybeRunOnHost(command, allArgs) {
         process.exitCode = 1;
         return true;
     }
-    // `--devices` / `--hosts` fan out to every registered device locally; don't
-    // let a per-host passthrough turn it into a cascading remote fan-out.
-    const fleetFlag = allArgs.includes('--devices') || allArgs.includes('--hosts');
-    if (fleetFlag)
+    // `--hosts` is always a generic fleet flag — bail for every command so the
+    // local aggregator handles it. `--devices` is fan-out on most commands but
+    // a placement flag on `routines` (which devices may run the routine), so
+    // only exempt routines from the bail.
+    if (allArgs.includes('--hosts'))
+        return false;
+    if (allArgs.includes('--devices') && command !== 'routines')
         return false;
     const hostName = hostFlag ?? deviceFlag;
     if (!hostName)

package/dist/lib/migrate.d.ts

@@ -96,5 +96,14 @@ export declare function repairSelfReferentialBinShims(versionsRoot?: string, shi
  * the new name.
  */
 export declare function migrateExtrasExtrasToAgentsExtras(historyDir?: string): void;
+/**
+ * Rewrite every routine YAML that carries the legacy singular `device: <value>`
+ * field to the new plural `devices: [<value>]` format. Preserves all other
+ * fields. Idempotent: a routine that already has `devices:` (or neither field)
+ * is left untouched.
+ *
+ * Params default to the real routines dir; injectable for tests.
+ */
+export declare function migrateRoutineDeviceToDevices(routinesDir?: string): void;
 /** Run all idempotent migrations. Safe to call multiple times. */
 export declare function runMigration(): Promise<void>;

package/dist/lib/migrate.js

@@ -1885,6 +1885,52 @@ export function migrateExtrasExtrasToAgentsExtras(historyDir = HISTORY_DIR) {
         console.error(`Renamed extras-extras → agents-extras (dirs: ${renamedDirs}, known_marketplaces: ${rewroteKnown}, settings: ${rewroteSettings})`);
     }
 }
+/**
+ * Rewrite every routine YAML that carries the legacy singular `device: <value>`
+ * field to the new plural `devices: [<value>]` format. Preserves all other
+ * fields. Idempotent: a routine that already has `devices:` (or neither field)
+ * is left untouched.
+ *
+ * Params default to the real routines dir; injectable for tests.
+ */
+export function migrateRoutineDeviceToDevices(routinesDir) {
+    const dir = routinesDir ?? path.join(USER_DIR, 'routines');
+    if (!fs.existsSync(dir))
+        return;
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+    let migrated = 0;
+    for (const file of files) {
+        const filePath = path.join(dir, file);
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        let doc;
+        try {
+            doc = yaml.parse(raw);
+            if (!doc || typeof doc !== 'object')
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (!('device' in doc))
+            continue;
+        if ('devices' in doc) {
+            delete doc.device;
+            atomicWriteFileSync(filePath, yaml.stringify(doc));
+            continue;
+        }
+        const val = doc.device;
+        if (typeof val !== 'string' || !val.trim()) {
+            throw new Error(`${file}: legacy 'device' field is not a valid device name — repair the file and retry`);
+        }
+        delete doc.device;
+        doc.devices = [val.trim()];
+        atomicWriteFileSync(filePath, yaml.stringify(doc));
+        migrated++;
+    }
+    if (migrated > 0) {
+        console.error(`Migrated ${migrated} routine${migrated === 1 ? '' : 's'}: device → devices`);
+    }
+}
 /** Run all idempotent migrations. Safe to call multiple times. */
 export async function runMigration() {
     // MUST run first: every other migrator reads SYSTEM_DIR (the new path).
@@ -1937,6 +1983,8 @@ export async function runMigration() {
     // installed version-home. Runs after migrateRuntimeToHistory so the version
     // homes are at their canonical HISTORY_DIR location.
     migrateExtrasExtrasToAgentsExtras();
+    // Rewrite routine YAML files: singular `device:` -> plural `devices: []`.
+    migrateRoutineDeviceToDevices();
     // Symlink repair runs LAST so it can find the post-move version homes.
     repairAgentConfigSymlinks();
     // Repair self-referential node_modules/.bin/<cli> symlinks (the droid

package/dist/lib/overdue.js

@@ -14,7 +14,7 @@
 import { Cron } from 'croner';
 import * as os from 'os';
 import { spawn } from 'child_process';
-import { listJobs, getLatestRun } from './routines.js';
+import { listJobs, getLatestRun, jobRunsOnThisDevice } from './routines.js';
 // Tolerance between "expected fire" and "recorded run start" — accounts for
 // the small gap between the cron tick and when the runner writes meta.json.
 const GRACE_MS = 60_000;
@@ -47,6 +47,11 @@ export function detectOverdueJobs(now = new Date()) {
         // Trigger-only jobs (no cron schedule) never have an expected fire time.
         if (!job.schedule)
             continue;
+        // A job pinned to another device is that device's to run, notify, and
+        // catch up — flagging it here would make every machine in the fleet nag
+        // (and `catchup` fire) for a job that must not run locally.
+        if (!jobRunsOnThisDevice(job))
+            continue;
         let expected = null;
         try {
             const cronOptions = { paused: true };

package/dist/lib/profiles-presets.js

@@ -88,6 +88,58 @@ export const PRESETS = [
             ANTHROPIC_SMALL_FAST_MODEL: 'deepseek/deepseek-chat-v3-0324',
         },
     },
+    {
+        name: 'open-claude',
+        description: 'Open-weight coding via OpenRouter inside Claude Code (Qwen3 Coder Next, 256K ctx, $0.15/$0.80 per 1M). HEADLESS-SAFE — best general preset for open-claude usage with Claude Code harness.',
+        ...OPENROUTER_AUTH,
+        env: {
+            ANTHROPIC_BASE_URL: OPENROUTER_BASE,
+            ANTHROPIC_MODEL: 'qwen/qwen3-coder-next',
+            ANTHROPIC_SMALL_FAST_MODEL: 'qwen/qwen3-coder-next',
+        },
+    },
+    {
+        name: 'claude-spark',
+        description: 'Meta Claude Spark 1.1 via OpenRouter inside Claude Code (open alternative). Model: meta/claude-spark-1.1 — free via opencode, now usable in Claude Code UI. HEADLESS-SAFE. For open-claude spark usage.',
+        ...OPENROUTER_AUTH,
+        env: {
+            ANTHROPIC_BASE_URL: OPENROUTER_BASE,
+            ANTHROPIC_MODEL: 'meta/claude-spark-1.1',
+            ANTHROPIC_SMALL_FAST_MODEL: 'meta/claude-spark-1.1',
+        },
+    },
+    // ----- OpenCode CLI (open-claude harness) -----
+    {
+        name: 'opencode',
+        description: 'OpenCode default — uses your configured model via opencode auth. Run `opencode auth` to login, then `agents run opencode --model meta/claude-spark-1.1 "prompt"` for spark usage.',
+        provider: 'opencode',
+        host: 'opencode',
+        authEnvVar: 'OPENCODE_API_KEY',
+        authOptional: true,
+        env: {},
+    },
+    {
+        name: 'opencode-spark',
+        description: 'Meta Claude Spark 1.1 via OpenCode (free, headless-safe). Pinned to meta/claude-spark-1.1 — best for open-claude usage with opencode harness.',
+        provider: 'opencode',
+        host: 'opencode',
+        authEnvVar: 'OPENCODE_API_KEY',
+        authOptional: true,
+        env: {
+            OPENCODE_MODEL: 'meta/claude-spark-1.1',
+        },
+    },
+    {
+        name: 'opencode-qwen',
+        description: 'Qwen3 Coder Next via OpenCode (open-claude path). Use `agents run opencode-qwen "prompt"` — free via opencode provider.',
+        provider: 'opencode',
+        host: 'opencode',
+        authEnvVar: 'OPENCODE_API_KEY',
+        authOptional: true,
+        env: {
+            OPENCODE_MODEL: 'qwen/qwen3-coder-next',
+        },
+    },
     // ----- xAI Grok Build CLI (native host) -----
     {
         name: 'grok-fast',