@phnx-labs/agents-cli 1.20.54 → 1.20.55

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 1.20.55
+
+- **Routine scheduler health is now observable and self-healing.** `agents routines status` distinguishes `running`, `wedged`, and `stopped`, and reports the daemon binary plus heartbeat age. Routine listing/status opportunistically finalize orphaned runs; PID reuse checks and a 24-hour wall-clock limit prevent stale `running` records; daemon startup rejects bun virtual paths and warns about worktree binaries that can disappear. Source: `apps/cli/src/lib/daemon.ts`, `apps/cli/src/lib/runner.ts`, `apps/cli/src/commands/routines.ts`.
+- **Built-in Open-Claude and OpenCode profiles.** `agents profiles` now ships `open-claude` and `claude-spark` for Claude Code through OpenRouter, plus `opencode`, `opencode-spark`, and `opencode-qwen` presets for the OpenCode harness. Source: `apps/cli/src/lib/profiles-presets.ts`, `apps/cli/docs/profiles.md`.
+- **Fix: exiting a user split inside an `agents run` tmux session reliably closes just that split (de-flakes CI #965).** The guarded `pane-died` hook's else-branch was a bare `kill-pane`, which relies on the hook context supplying an implicit "current pane" — nondeterministic on a loaded detached server, so the dead split intermittently survived as a husk (the same failure the flaky `session.test.ts` pane-died tests reproduced in CI). An intermediate external `tmux -S <socket>` self-client still raced the server under Linux load. The else-branch now runs `run-shell -C "kill-pane -t #{hook_pane}"`, which format-expands the event pane and executes the targeted command inside tmux's own server queue. Interactive tmux-backed runs now require tmux 3.2+, the release that introduced `run-shell -C`. `AGENT_HOOK_SCHEMA` bumps to 4; the daemon reconcile retrofits live sessions automatically and only stamps the marker after tmux accepts the hook, so a transient failure stays retryable. Source: `apps/cli/src/lib/tmux/session.ts` (`agentPaneDiedHook`, `AGENT_HOOK_SCHEMA`), `apps/cli/src/lib/tmux/binary.ts`, `apps/cli/src/lib/exec.ts`.
+- **`agents devices sync` pins the login user on Windows too.** `os.userInfo().username` returns `COMPUTER\user` / `DOMAIN\user` on Windows, which failed the safe-charset guard, so Windows boxes synced with no pinned user and `--host <device>` fell back to the wrong local account. `sanitizeLoginUser` now strips the domain prefix to the bare ssh account before the guard. Also folds the duplicate `user@host` splitter (`parseTarget` in `ssh.ts`) into the canonical `splitUserHost` so there is one parser. Source: `apps/cli/src/lib/devices/sync.ts`, `apps/cli/src/commands/ssh.ts`.
+- **Menu bar ACTIVE section now shows every local session, not just extension-registered terminals.** The dropdown's session source was `live-terminals.json`, which only carries terminals the Factory extension registers — a machine with 25 live sessions (tmux, ghostty, headless) rendered `ACTIVE · 1 running`. The helper now feeds triage + ACTIVE from `agents sessions --active --local --json` (the session engine's authoritative view, issue #741 contract) on the same warm-cache pattern as routines (30s TTL, refreshed off the click path; the cheap file still covers cold start and the 10s badge poll). Blocked sessions outside the extension's view now surface in NEEDS YOU too. Idle rows cap at 3 per repo group — the group header carries the true counts — so a big idle fleet can't wall the menu. Source: `apps/cli/menubar/Sources/MenubarHelper/{StatusItemController,LocalState,AgentsCLI,Models}.swift`.
+- **Daemon service manifests pin JavaScript installs to the current Node runtime.** launchd and systemd now invoke `process.execPath <entry> daemon _run`, matching the detached launcher, instead of executing the JS entrypoint through `#!/usr/bin/env node`. Linux user services therefore stop falling back to an obsolete system Node (observed as Node 18 failing on `node:util.styleText`) when the CLI was installed under Node 22/24. Native `agents` launchers remain direct executables. Source: `apps/cli/src/lib/daemon.ts`.
+- **Routines can be pinned to one machine with `device:` / `--device`.** Routine YAMLs sync fleet-wide via the user repo, so an enabled routine previously fired on every device running the scheduler. A `device: <name>` pin (matched against the local `machineId()`, normalized like `agents devices` names) makes the job inert everywhere else: the cron scheduler skips it, webhook triggers don't match it, overdue detection/`catchup`/daemon nags ignore it, and `routines run` refuses with an `agents ssh <device>` pointer. `routines list` grows a Device column and `--json` gains `device` + `runsHere`. Source: `apps/cli/src/lib/routines.ts`, `apps/cli/src/lib/scheduler.ts`, `apps/cli/src/lib/overdue.ts`, `apps/cli/src/lib/triggers/webhook.ts`, `apps/cli/src/commands/routines.ts`.
+- **Routines now default to `--mode auto` instead of `plan` (RUSH-1595).** A routine created without an explicit `mode` now runs under the smart classifier (`auto`) rather than read-only `plan`, so unattended jobs can create PRs, write files, and run tests end-to-end without every user opting in — `auto` maps to `--permission-mode auto` (claude), workspace-write + network (codex), `--auto high` (droid), and kimi's default headless run (which had no read-only mode and previously errored at `plan`). Opt down to `mode: plan` for read-only monitoring/reporting. `JOB_DEFAULTS.mode`, the `agents routines add --mode` flag default, and the file-add default all move to `auto`; `writeJob` now omits `mode` when it equals `auto`. Source: `apps/cli/src/lib/routines.ts`, `apps/cli/src/commands/routines.ts`.
+- **`agents publish` — a self-hosted, zero-infrastructure skill registry that round-trips with `agents search`/`agents install`.** Publish walks a git repo's `skills/` directory, records a sha256 of every `SKILL.md`, and writes a flat `skills-index.json` (`SkillIndexDocument` shape) at the repo root, then commits + pushes it and prints the `raw.githubusercontent.com` URL plus the exact `agents registry add skill <name> <url>` command to share. No hosted aggregator: the index is just a file in your GitHub repo, consumed directly by the existing `fetchSkillIndex`/`searchSkillRegistries` path. Targets your `~/.agents` repo by default or an extra repo via `--repo <alias>` (`--dry-run` previews without pushing). Each index entry carries `sha256`, threaded through `SkillEntry`/`normalizeSkillEntry`, and `agents install` now verifies the freshly cloned `SKILL.md` against it — a mismatch aborts with a clear error rather than trusting a tampered artifact. This is the self-hosted/git-index slice of #336; global no-URL discovery (a hosted aggregator) remains future work. Source: `apps/cli/src/commands/packages.ts` (`publish` subcommand + install-time verify), `apps/cli/src/lib/registry.ts` (`buildSkillIndex`, `verifySkillIntegrity`, `sha256OfFile`, `parseOwnerRepoFromRemote`, `SkillIndexEntry.sha256`), `apps/cli/src/lib/types.ts` (`SkillEntry.sha256`). (#336)
+
 ## 1.20.54
 
 - **Unified fleet target resolution for `agents ssh` + `sessions --host`.** `agents ssh` now accepts the full target grammar the fan-out already used — a registered `name`, a `user@device` (same device, login user overridden, still dialed via its Tailscale route rather than raw LAN DNS), and an ad-hoc `user@host`/`host` literal — instead of only an exact device name (`agents ssh muqsit@mac-mini` no longer errors "Unknown device"). A bare unregistered alias still reports "Unknown device". `sessions --host user@device` now resolves the host part through the registry too, so it stops silently diverging onto the non-Tailscale route. New `resolveDeviceTarget`; `resolveSshTarget` shares one host-part matcher. Source: `apps/cli/src/lib/devices/resolve-target.ts`, `apps/cli/src/commands/ssh.ts`.

package/README.md

@@ -642,6 +642,10 @@ agents routines add daily-digest \
 agents routines list                   # All jobs + next run times
 agents routines run daily-digest       # Test it now, ignore the schedule
 agents routines logs daily-digest      # Last execution — status + report (add --full for raw stdout)
+
+# Routines sync to every device; pin one to a single machine with --device
+agents routines add nightly-drain --schedule "0 3 * * *" --agent claude \
+  --device yosemite-s0 --prompt "Drain the work queue"
 ```
 
 Jobs run sandboxed -- agents only see directories and tools you explicitly allow.
@@ -895,6 +899,8 @@ macOS and Linux. Windows via WSL works but isn't first-class yet.
 
 **macOS-only features:** Keychain-based secrets (`agents secrets`, `agents profiles login`) require macOS. Default iCloud sync for bundles requires macOS + iCloud Keychain enabled; use `--no-icloud-sync` for device-local bundles. On Linux, use environment variables or `.env` files for API keys. Native Linux credential store support is planned.
 
+Interactive tmux-backed runs require tmux 3.2 or newer.
+
 ### Do I need Node.js?
 
 The installer tries Bun first (faster), falls back to npm. Node 22.5+ required at runtime.

package/dist/commands/packages.js

@@ -5,13 +5,16 @@
  * for discovering and installing MCP servers, skills, commands, and
  * hooks from configured registries or GitHub sources.
  */
+import * as fs from 'fs';
+import * as path from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
+import { getAgentsDir, getEnabledExtraRepos } from '../lib/state.js';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, agentLabel, } from '../lib/agents.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { DEFAULT_REGISTRIES } from '../lib/types.js';
-import { getRegistries, setRegistry, removeRegistry, search as searchRegistries, resolvePackage, validatedNpmSpec, validatedPyPISpec, } from '../lib/registry.js';
-import { cloneRepo } from '../lib/git.js';
+import { getRegistries, setRegistry, removeRegistry, search as searchRegistries, resolvePackage, validatedNpmSpec, validatedPyPISpec, buildSkillIndex, verifySkillIntegrity, parseOwnerRepoFromRemote, } from '../lib/registry.js';
+import { cloneRepo, commitAndPush, getRemoteUrl, isGitRepo } from '../lib/git.js';
 import { discoverCommands, resolveCommandSource, installCommand, installCommandCentrally, } from '../lib/commands.js';
 import { discoverSkillsFromRepo, installSkill, installSkillCentrally, } from '../lib/skills.js';
 import { discoverHooksFromRepo, installHooks, installHooksCentrally, } from '../lib/hooks.js';
@@ -325,6 +328,100 @@ When to use:
         }
     });
     // ==========================================================================
+    // PUBLISH COMMAND (self-hosted, git-index skill registry)
+    // ==========================================================================
+    program
+        .command('publish')
+        .description('Generate a skills-index.json for a git repo and push it, making its skills discoverable via agents search/install')
+        .option('--repo <alias>', 'Publish an extra repo added via `agents repo add` (default: your ~/.agents repo)')
+        .option('--name <name>', 'Registry name to suggest in the output (default: the repo name)')
+        .option('--branch <branch>', 'Branch the raw URL should reference', 'main')
+        .option('--dry-run', 'Write the index and print the URL without committing or pushing')
+        .addHelpText('after', `
+Publish walks a repo's skills/ directory, records a sha256 of every SKILL.md,
+and writes skills-index.json at the repo root — a flat index that 'agents search'
+and 'agents install' can consume directly from raw.githubusercontent.com. No
+hosted infrastructure: the index is just a file committed to your GitHub repo.
+
+Examples:
+  # Publish your ~/.agents repo's skills
+  agents publish
+
+  # Publish an extra repo added via 'agents repo add'
+  agents publish --repo team-skills
+
+  # Preview the index without pushing
+  agents publish --dry-run
+
+After publishing, share the printed 'agents registry add skill ...' command so
+others can search and install your skills. Installs verify each SKILL.md against
+the sha256 in the index and abort on mismatch.
+`)
+        .action(async (options) => {
+        // Resolve the target repo: an extra repo by alias, else the primary ~/.agents repo.
+        let repoDir;
+        if (options.repo) {
+            const extra = getEnabledExtraRepos().find((r) => r.alias === options.repo);
+            if (!extra) {
+                console.log(chalk.red(`No enabled extra repo aliased '${options.repo}'.`));
+                console.log(chalk.gray('Add one with: agents repo add <source> --as <alias>'));
+                process.exit(1);
+            }
+            repoDir = extra.dir;
+        }
+        else {
+            repoDir = getAgentsDir();
+        }
+        if (!isGitRepo(repoDir)) {
+            console.log(chalk.red(`${repoDir} is not a git repository.`));
+            console.log(chalk.gray('publish commits + pushes the index, so the repo needs a GitHub remote.'));
+            process.exit(1);
+        }
+        const remoteUrl = await getRemoteUrl(repoDir);
+        const repoSlug = remoteUrl ? parseOwnerRepoFromRemote(remoteUrl) : null;
+        if (!repoSlug) {
+            console.log(chalk.red(`Could not resolve an 'owner/repo' from the git remote of ${repoDir}.`));
+            console.log(chalk.gray(`  Remote: ${remoteUrl || '(none)'} — publish needs a GitHub origin.`));
+            process.exit(1);
+        }
+        const spinner = ora('Building skills index...').start();
+        const index = buildSkillIndex(repoDir, repoSlug, { generatedAt: new Date().toISOString() });
+        spinner.stop();
+        if (index.skills.length === 0) {
+            console.log(chalk.yellow(`No skills found under ${repoDir}/skills.`));
+            console.log(chalk.gray('Add a skill (a directory with a SKILL.md) and re-run publish.'));
+            process.exit(1);
+        }
+        const indexPath = path.join(repoDir, 'skills-index.json');
+        fs.writeFileSync(indexPath, JSON.stringify(index, null, 2) + '\n', 'utf-8');
+        console.log(chalk.bold(`\nIndexed ${index.skills.length} skill(s) into skills-index.json:`));
+        for (const s of index.skills) {
+            console.log(`  ${chalk.cyan(s.name)} ${chalk.gray(`sha256:${s.sha256?.slice(0, 12)}…`)}`);
+        }
+        if (options.dryRun) {
+            console.log(chalk.gray(`\nDry run — wrote ${indexPath} but did not commit or push.`));
+        }
+        else {
+            const pushSpinner = ora('Committing and pushing skills-index.json...').start();
+            const result = await commitAndPush(repoDir, 'chore: update skills-index.json (agents publish)');
+            if (!result.success) {
+                pushSpinner.fail(`Push failed: ${result.error}`);
+                console.log(chalk.gray('The index was written locally — commit and push it manually to publish.'));
+                process.exit(1);
+            }
+            pushSpinner.succeed('Pushed skills-index.json');
+        }
+        const rawUrl = `https://raw.githubusercontent.com/${repoSlug}/${options.branch}/skills-index.json`;
+        const registryName = options.name || repoSlug.split('/')[1] || 'my-skills';
+        console.log(chalk.bold('\nPublished. Share these with anyone who wants your skills:\n'));
+        console.log(chalk.gray('  Index URL:'));
+        console.log(`    ${rawUrl}`);
+        console.log(chalk.gray('\n  Register + search + install:'));
+        console.log(`    ${chalk.green(`agents registry add skill ${registryName} ${rawUrl}`)}`);
+        console.log(`    ${chalk.green(`agents search ${index.skills[0].name} --type skill`)}`);
+        console.log(`    ${chalk.green(`agents install skill:${index.skills[0].name} --agents claude,codex,gemini`)}`);
+    });
+    // ==========================================================================
     // INSTALL COMMAND (unified package installation)
     // ==========================================================================
     program
@@ -448,6 +545,20 @@ When to use:
                 // --names narrows which specific resources within those kinds.
                 console.log(chalk.bold(`\nInstalling from ${resolved.source}`));
                 const { localPath } = await cloneRepo(resolved.source);
+                // Integrity: a published skill entry carries the sha256 of its
+                // SKILL.md. Verify the freshly cloned file against it BEFORE
+                // installing anything — a mismatch aborts rather than trusting a
+                // tampered artifact.
+                if (resolved.type === 'skill' && resolved.skillEntry) {
+                    const check = verifySkillIntegrity(localPath, resolved.skillEntry);
+                    if (!check.ok) {
+                        console.log(chalk.red(`\n${check.error}`));
+                        process.exit(1);
+                    }
+                    if (resolved.skillEntry.sha256) {
+                        console.log(chalk.gray(`  Integrity verified (sha256) for ${resolved.skillEntry.name}`));
+                    }
+                }
                 const requestedTypes = new Set(parseCommaSeparatedList(options.types));
                 const includeType = (type) => requestedTypes.size === 0 || requestedTypes.has(type);
                 const requestedNames = new Set(parseCommaSeparatedList(options.names));

package/dist/commands/routines.js

@@ -10,14 +10,14 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonPid, readDaemonLog, } from '../lib/daemon.js';
+import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, } from '../lib/daemon.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
-import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, } from '../lib/routines.js';
+import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, jobRunsOnThisDevice, } from '../lib/routines.js';
 import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
 import { safeJoin } from '../lib/paths.js';
-import { executeJob, executeJobDetached } from '../lib/runner.js';
+import { executeJob, executeJobDetached, monitorRunningJobs } from '../lib/runner.js';
 import { JobScheduler } from '../lib/scheduler.js';
 import { detectOverdueJobs } from '../lib/overdue.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
@@ -175,6 +175,10 @@ export function registerRoutinesCommands(program) {
         .description('See all scheduled jobs, when they run next, and their last execution status')
         .option('--json', 'Emit machine-readable JSON instead of the table (used by the menu bar helper)')
         .action((options) => {
+        try {
+            monitorRunningJobs();
+        }
+        catch { /* best-effort orphan reap */ }
         const jobs = listAllJobs(process.cwd());
         if (jobs.length === 0) {
             if (options.json) {
@@ -212,6 +216,8 @@ export function registerRoutinesCommands(program) {
                     scheduleHuman: fireConditionLabel(job),
                     trigger: job.trigger ?? null,
                     timezone: job.timezone ?? null,
+                    device: job.device ?? null,
+                    runsHere: jobRunsOnThisDevice(job),
                     enabled: job.enabled,
                     overdue: overdueSet.has(job.name),
                     nextRun: nextRun ? nextRun.toISOString() : null,
@@ -234,12 +240,13 @@ export function registerRoutinesCommands(program) {
         const NAME_W = 24;
         const AGENT_W = 10;
         const REPO_W = REPO_DISPLAY_MAX;
+        const DEVICE_W = 13;
         const SCHED_W = 22;
         const ENABLED_W = 10;
         const NEXT_W = 22;
-        const header = `  ${'Name'.padEnd(NAME_W)} ${'Agent'.padEnd(AGENT_W)} ${'Repo'.padEnd(REPO_W)} ${'Schedule'.padEnd(SCHED_W)} ${'Enabled'.padEnd(ENABLED_W)} ${'Next Run'.padEnd(NEXT_W)} Last Status`;
+        const header = `  ${'Name'.padEnd(NAME_W)} ${'Agent'.padEnd(AGENT_W)} ${'Repo'.padEnd(REPO_W)} ${'Device'.padEnd(DEVICE_W)} ${'Schedule'.padEnd(SCHED_W)} ${'Enabled'.padEnd(ENABLED_W)} ${'Next Run'.padEnd(NEXT_W)} Last Status`;
         console.log(chalk.gray(header));
-        console.log(chalk.gray('  ' + '-'.repeat(NAME_W + AGENT_W + REPO_W + SCHED_W + ENABLED_W + NEXT_W + 20)));
+        console.log(chalk.gray('  ' + '-'.repeat(NAME_W + AGENT_W + REPO_W + DEVICE_W + SCHED_W + ENABLED_W + NEXT_W + 20)));
         for (const job of jobs) {
             const nextRun = scheduler.getNextRun(job.name);
             const nextStr = humanizeNextRun(nextRun ?? null, now, job.timezone);
@@ -261,6 +268,15 @@ export function registerRoutinesCommands(program) {
             // chalk adds escape codes; pad the raw word and let chalk wrap it.
             const enabledWord = job.enabled ? 'yes' : 'no';
             const enabledPad = Math.max(0, ENABLED_W - enabledWord.length);
+            // Unpinned jobs run everywhere; a pin that names another machine is
+            // grayed — this machine never fires it.
+            const deviceWord = job.device || '-';
+            const deviceCell = !job.device
+                ? chalk.gray('-')
+                : jobRunsOnThisDevice(job)
+                    ? deviceWord
+                    : chalk.gray(deviceWord);
+            const devicePad = Math.max(0, DEVICE_W - deviceWord.length);
             const statusColor = lastStatus === 'completed' ? chalk.green
                 : lastStatus === 'failed' ? chalk.red
                     : lastStatus === 'timeout' ? chalk.yellow
@@ -269,7 +285,7 @@ export function registerRoutinesCommands(program) {
             const agentLabelPadded = job.workflow
                 ? chalk.magenta(`wf:${job.workflow}`.padEnd(10))
                 : (job.agent || '').padEnd(10);
-            console.log(`  ${chalk.cyan(job.name.padEnd(NAME_W))} ${agentLabelPadded} ${repoCell}${' '.repeat(repoPadding)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}`);
+            console.log(`  ${chalk.cyan(job.name.padEnd(NAME_W))} ${agentLabelPadded} ${repoCell}${' '.repeat(repoPadding)} ${deviceCell}${' '.repeat(devicePad)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}`);
         }
         if (overdueSet.size > 0) {
             console.log();
@@ -285,10 +301,11 @@ export function registerRoutinesCommands(program) {
         .option('-a, --agent <agent>', 'Which agent runs this routine: claude, codex, gemini, cursor, or opencode')
         .option('--workflow <name>', 'Run an installed workflow (~/.agents/workflows/<name>) via `agents run`. Mutually exclusive with --agent.')
         .option('-p, --prompt <prompt>', 'Task instruction for the agent')
-        .option('-m, --mode <mode>', "Execution mode: plan (read-only), edit (can write files), auto (smart classifier), or skip (bypass all permission prompts). 'full' accepted as alias for skip.", 'plan')
+        .option('-m, --mode <mode>', "Execution mode: plan (read-only), edit (can write files), auto (smart classifier, the default), or skip (bypass all permission prompts). 'full' accepted as alias for skip.", 'auto')
         .option('-e, --effort <effort>', 'Reasoning effort: low | medium | high | xhigh | max | auto', 'auto')
         .option('-t, --timeout <timeout>', 'Kill the agent if it runs longer than this (e.g., 10m, 2h, 3d, 1w; max 1w)', '10m')
         .option('--timezone <tz>', 'Interpret schedule in this timezone (e.g., America/Los_Angeles)')
+        .option('--device <name>', 'Pin to one machine (routines are fleet-synced): only the device with this name schedules and fires the job')
         .option('--at <time>', 'One-shot mode: run once at this time (e.g., "14:30" or "2026-02-24 09:00"), then disable')
         .option('--end-at <iso>', 'Stop firing on or after this ISO 8601 timestamp (e.g., "2026-12-31T23:59:00Z"); routine auto-disables.')
         .option('--disabled', 'Create the routine but keep it paused (enable later with resume)')
@@ -343,6 +360,7 @@ export function registerRoutinesCommands(program) {
                 enabled: !options.disabled,
                 prompt: options.prompt,
                 timezone: options.timezone,
+                ...(options.device ? { device: options.device } : {}),
                 ...(runOnce ? { runOnce: true } : {}),
                 ...(options.endAt ? { endAt: options.endAt } : {}),
             };
@@ -394,7 +412,7 @@ export function registerRoutinesCommands(program) {
                 process.exit(1);
             }
             const config = {
-                mode: 'plan',
+                mode: 'auto',
                 effort: 'auto',
                 timeout: '10m',
                 enabled: true,
@@ -544,6 +562,11 @@ export function registerRoutinesCommands(program) {
             console.log(chalk.red(`Job '${name}' not found`));
             process.exit(1);
         }
+        if (!jobRunsOnThisDevice(job)) {
+            console.log(chalk.red(`Job '${name}' is pinned to device '${job.device}' and never runs here.`));
+            console.log(chalk.gray(`  Run it there: agents ssh ${job.device} 'agents routines run ${name}'`));
+            process.exit(1);
+        }
         const runLabel = job.workflow ? `workflow: ${job.workflow}` : `agent: ${job.agent}`;
         console.log(chalk.bold(`Running job '${name}' (${runLabel}, mode: ${job.mode})\n`));
         const spinner = ora('Executing...').start();
@@ -860,16 +883,33 @@ export function registerRoutinesCommands(program) {
         .command('status')
         .description('Show scheduler status, enabled routines, and when each one fires next.')
         .action(() => {
-        const running = isDaemonRunning();
-        const pid = readDaemonPid();
+        try {
+            monitorRunningJobs();
+        }
+        catch { /* best-effort orphan reap */ }
+        const status = getDaemonStatus();
         console.log(chalk.bold('Scheduler\n'));
-        console.log(`  Status:    ${running ? chalk.green('running') : chalk.gray('stopped')}`);
-        if (pid)
-            console.log(`  PID:       ${pid}`);
+        const stateLabel = status.state === 'running'
+            ? chalk.green('running')
+            : status.state === 'wedged'
+                ? chalk.red('wedged')
+                : chalk.gray('stopped');
+        console.log(`  Status:    ${stateLabel}`);
+        if (status.pid)
+            console.log(`  PID:       ${status.pid}`);
+        if (status.binaryPath)
+            console.log(`  Binary:    ${chalk.gray(status.binaryPath)}`);
+        if (status.heartbeat) {
+            const ago = Math.round((Date.now() - Date.parse(status.heartbeat.lastTick)) / 1000);
+            console.log(`  Heartbeat: ${chalk.gray(`${ago} sec ago`)}`);
+        }
         const jobs = listAllJobs();
         const enabled = jobs.filter((j) => j.enabled);
         console.log(`  Routines:  ${enabled.length} enabled / ${jobs.length} total`);
-        if (running && enabled.length > 0) {
+        if (status.state === 'wedged') {
+            console.log(chalk.red('\n  The daemon is wedged (heartbeat stale). Restart with: agents routines stop && agents routines start'));
+        }
+        if (status.running && enabled.length > 0) {
             const scheduler = new JobScheduler(async () => { });
             scheduler.loadAll();
             const scheduled = scheduler.listScheduled();
@@ -880,7 +920,7 @@ export function registerRoutinesCommands(program) {
             }
             scheduler.stopAll();
         }
-        else if (!running && jobs.length > 0) {
+        else if (!status.running && jobs.length > 0) {
             console.log(chalk.gray('\n  Start the scheduler to begin firing routines: agents routines start'));
         }
     });

package/dist/commands/ssh.js

@@ -20,18 +20,11 @@ import { machineId } from '../lib/session/sync/config.js';
 import { addIgnored, getDevice, loadDevices, loadIgnored, removeDevice, removeIgnored, upsertDevice, } from '../lib/devices/registry.js';
 import { nodeToDeviceInput, parseTailscaleStatus, tailscaleStatusJson, } from '../lib/devices/tailscale.js';
 import { localLoginUser, planDeviceReconciliation, runDeviceSync, withDefaultUser } from '../lib/devices/sync.js';
-import { resolveDeviceTarget } from '../lib/devices/resolve-target.js';
+import { resolveDeviceTarget, splitUserHost } from '../lib/devices/resolve-target.js';
 import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
 import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, writeAskpassShim, } from '../lib/devices/connect.js';
-/** Parse `user@host` or `host` into pieces. */
-function parseTarget(target) {
-    const at = target.indexOf('@');
-    if (at === -1)
-        return { host: target };
-    return { user: target.slice(0, at), host: target.slice(at + 1) };
-}
 /** 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) {
@@ -240,7 +233,7 @@ Typical workflow:
         .option('--platform <platform>', 'windows | linux | macos')
         .action(async (name, target, opts) => {
         try {
-            const { host, user } = parseTarget(target);
+            const { host, user } = splitUserHost(target);
             const isIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
             const d = await upsertDevice(name, {
                 platform: opts.platform ?? undefined,

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/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;
 /**
@@ -128,6 +136,9 @@ export declare function getDaemonLaunch(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 +155,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}
@@ -842,11 +895,29 @@ 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'] };
 }
+export function validateDaemonBinary(binPath) {
+    const warnings = [];
+    if (/\/\$bunfs\/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 +1019,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) {