@phnx-labs/agents-cli 1.20.82 → 1.20.83

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # Changelog
 
+## 1.20.83
+
+- **Routines now treat date-specific cron schedules as one-shot jobs (RUSH-2074).**
+  `agents routines add --schedule "0 14 29 7 *"` now warns, persists
+  `runOnce: true`, marks the routine as one-shot in `routines list`, and
+  `agents routines cleanup` removes completed expired one-shots that still have
+  user-layer YAML. Source: `apps/cli/src/lib/routines.ts`,
+  `apps/cli/src/lib/scheduler.ts`, `apps/cli/src/commands/routines.ts`.
+
+- **`agents routines list` groups terminal output by device and placement
+  (RUSH-2075).** The default table is bucketed under this machine, fleet-wide,
+  cloud, named devices, and named hosts with offline/unknown registry hints;
+  `--flat` keeps the legacy single table and `--json` remains a flat payload.
+  Source: `apps/cli/src/commands/routines.ts`.
+
+- **`agents.yaml` no longer churns on every meta write.** `writeMetaUnlocked` wrote
+  the central config with `yaml.stringify`, which strips all comments — so the
+  freshly-serialized bytes never matched the comment-annotated file on disk,
+  `writeIfChanged` rewrote it on every meta write, and the perpetually-dirty tree
+  wedged `agents sync` ("Blocked by local changes") across the fleet. It now
+  serializes via a `yaml.Document` round-trip (`serializeCentral`) that edits only
+  the keys that actually changed, so comments, key ordering, and untouched
+  top-level blocks (e.g. `hosts:`) are byte-stable — and a write that changes no
+  central field leaves `agents.yaml` untouched. Source: `apps/cli/src/lib/state.ts`.
+
+- **`agents run codex` can now reach the fleet from inside its sandbox.** Codex's
+  `workspace-write` sandbox blocks `$HOME` (verified against the live CLI and OpenAI's
+  sandbox docs), but the model routinely shells out to `agents ...`, whose runtime state
+  lives under `~/.agents` — the SSH askpass shim (`~/.agents/.cache/devices/askpass.sh`),
+  the device/stats cache, secrets, session writes, config tunings. Those inner writes hit
+  `EROFS` (`agents ssh` died before connecting, so a remote `agents run codex` could not
+  SSH or self-tune), and the fix was previously left to the caller (teams pass
+  `--add-dir ~/.agents` explicitly; a plain `agents run` never did). `buildExecCommand`
+  now grants `~/.agents` as an extra writable root whenever Codex runs `workspace-write`
+  (`--mode edit`/`auto`) — via `--add-dir` on fresh runs (deduped against user
+  `--add-dir`s) and via `-c sandbox_workspace_write.writable_roots` on resume forms (which
+  reject `--add-dir`). This is the officially-recommended way to widen scope "without
+  removing the sandbox entirely" — far narrower than `--mode skip` (danger-full-access).
+  `plan` (read-only) and `skip` (sandbox already dropped) are unaffected. Source:
+  `apps/cli/src/lib/exec.ts` (`buildExecCommand`, `codexWritableRootsConfig`).
+
+- **Fix headless release signing (`errSecInternalComponent`).** `headless-sign-context.sh` now runs `security set-key-partition-list` right after unlocking `rush-signing.keychain-db`, authorizing `codesign`/`apple-tool` to use the Developer ID key non-interactively. Without it, the key's ACL prompts for UI approval that a headless SSH release session can't answer, so `codesign` fails and the npm publish halts. Idempotent; runs every release. Source: `apps/cli/scripts/headless-sign-context.sh`.
+
+- **Cmd-Shift-V clip paste no longer breaks with an "sshd-keygen-wrapper would like
+  to control this computer" prompt.** A menu-bar helper started from an ssh session
+  registered the global chords but could never service them: macOS attributes its
+  Accessibility request to the responsible process, `/usr/libexec/sshd-keygen-wrapper`,
+  not to the helper's bundle, so the prompt named a process whose grant does nothing
+  for the paste (and, if granted, hands keystroke synthesis to everything any ssh
+  session spawns). `RegisterEventHotKey` is first-come, and the prompt naming
+  sshd-keygen-wrapper is itself the evidence that this copy — not the trusted
+  launchd-managed one — had registered Cmd-Shift-V and was servicing it. The
+  interactive mode now refuses to start over a remote shell, and refuses
+  unrecognized arguments: an unknown flag used to fall straight through to the
+  status-bar app, which is how a stray `MenubarHelper --self-test` from a verify run
+  became a permanent second helper. `launchctl bootstrap` (`agents menubar enable`)
+  is unaffected, including when run over ssh. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/Guards.swift`.
+
+- **`agents menubar status` now names a second helper process instead of reporting a
+  healthy `running: yes`.** The check was `pgrep -f MenubarHelper`, which matches any
+  process with that name, so a stray copy holding the global chords looked identical
+  to a working install. Status now identifies the helper by its resolved executable
+  (`ps -o comm=`), reports `running` only for the installed bundle, and lists every
+  other live copy with its pid under `foreignInstances` (also in `--json`). Source:
+  `apps/cli/src/lib/menubar/install-menubar.ts`.
+
+- **The menu bar now says so when a hotkey is unavailable or the paste is not
+  permitted.** A `RegisterEventHotKey` conflict only wrote a line to a launchd log,
+  and a missing Accessibility grant made `Clip.inject` return silently — both looked
+  exactly like a dead hotkey. A stolen chord now posts a notification naming it, and a
+  denied grant copies the `host:path` reference to the clipboard and says which
+  setting to grant, so the clip is never lost. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/Hotkey.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/Clip.swift`.
+
+- **Fix the release catch-up path aborting on an unbound variable.** When a release PR had already merged and only the tag + publish remained, `release.sh` re-validated CI and then aborted with `line 933: RELEASE_COMMIT: unbound variable`, so the retry never reached npm. The catch-up block that runs when `main` sits exactly at the release merge commit never set `HISTORICAL_CATCHUP`, so phase 4 took the normal-release branch and read `RELEASE_COMMIT`, which only the branch-creating path defines. It now sets the flag, and phase 4 resolves the release commit from the merged PR (`MERGED_RELEASE_SHA` + `CI_TESTED_HEAD`) as intended. This is why 1.20.79, 1.20.80, and 1.20.81 were tagged but never published. Source: `apps/cli/scripts/release.sh`.
+
+- **Removed `agents check` / `agents resources` now forward to their replacements
+  instead of erroring (RUSH-1234).** After the command consolidation, running the
+  removed names produced a bare `unknown command` (their edit-distance to `doctor`
+  was too far to even trigger a "did you mean"). They are now hidden tombstone
+  commands that print a one-line deprecation notice to stderr and re-run the
+  replacement, preserving flags and exit codes: `agents check …` runs
+  `agents doctor --check …` (so `--json` / `--quiet` / `--devices` and the CI
+  drift-gate exit code carry through), and `agents resources …` runs
+  `agents view --merged …` (with `agents inspect <target>` pointed to for
+  per-agent/per-repo detail). The notice goes to stderr so a `--json` consumer's
+  stdout stays clean. Source: `apps/cli/src/index.ts`.
+
+- **`agents sessions --host`/`--device <box>` now opens the interactive fleet
+  browser instead of a raw text dump.** A bare remote listing on a TTY folds the
+  named box into the same preview-rich, selectable picker as the local view (it
+  previously short-circuited to the legacy per-host stream — non-interactive, no
+  previews). A `--host` *query*, a render/filter flag, `--json`, or a
+  non-interactive caller keep the streamed output. Source:
+  `apps/cli/src/commands/sessions.ts`.
+
+- **`agents sessions` now shows which orchestrator spawned each team.** A teams
+  teammate row was keyed off its orchestrator's session id (captured from
+  `AGENTS_SESSION_ID` at spawn), which both hid the lineage and mislabeled the
+  teammate with the orchestrator's id/topic. The teammate now keys off its own
+  transcript, exposes the orchestrator as `orchestratorSessionId` (+ a resolved
+  `orchestratorLabel`) in `--active --json`, and the listing renders
+  `<team> · by <orchestrator>` so "which session spun up this team" is answerable
+  at a glance. Source: `apps/cli/src/lib/session/active.ts`,
+  `apps/cli/src/commands/sessions.ts`.
+
 ## 1.20.82
 
 - **Codex hook sync no longer leaves startup warnings after upgrades.** The Codex

package/README.md

@@ -306,7 +306,7 @@ agents sessions detach a1b2c3d4     # go headless in the background, keep workin
 agents sessions attach a1b2c3d4     # resume it interactively, right here
 ```
 
-Both are agent-agnostic -- they route through the same `agents run --resume` path (native resume for Claude/Codex, `/continue` replay for the rest). `agents sessions --active` marks each session's `presence` -- `attached` (you're watching it), `background` (running headless), or `parked` (its background run finished) -- so the menu bar and Factory show where every agent is. In the Factory extension, **Agents: Detach** (`Cmd/Ctrl+K B`) and **Agents: Attach** (`Cmd/Ctrl+K A`) do the same over the focused terminal.
+Both are agent-agnostic -- they route through the same `agents run --resume` path (native resume for Claude/Codex, `/continue` replay for the rest). `agents sessions --active` shows each session's **owner** (the human who launched it, resolved from the tailnet identity, or `-` for an unresolved local run) and its `presence` -- `attached` (you're watching it), `background` (running headless), or `parked` (its background run finished) -- so the menu bar and Factory show who is running what, and where. In the Factory extension, **Agents: Detach** (`Cmd/Ctrl+K B`) and **Agents: Attach** (`Cmd/Ctrl+K A`) do the same over the focused terminal.
 
 ---
 

package/dist/commands/doctor.d.ts

@@ -24,6 +24,7 @@
 import type { Command } from 'commander';
 import { type FleetDivergenceReport } from '../lib/devices/fleet-divergence.js';
 import { type VersionResourceReport } from '../lib/doctor-diff.js';
+import { type DuplicateVersionHook } from '../lib/hooks.js';
 import { type SyncStatusRow, type OrphanRow } from '../lib/drift.js';
 import { type FetchStatusMarker } from '../lib/auto-pull.js';
 export declare function wrapLine(prefix: string, text: string, width?: number): string[];
@@ -106,5 +107,5 @@ export declare function healthBlockLines(verdict: DoctorVerdict, opts: {
  * and orphan resources into severity-tagged findings. Agent-agnostic: every
  * installed version is classified the same way. Pure, so it is unit-testable.
  */
-export declare function computeOverviewHealth(syncRows: SyncStatusRow[], orphanRows: OrphanRow[], repoBehindMarkers: FetchStatusMarker[]): DoctorVerdict;
+export declare function computeOverviewHealth(syncRows: SyncStatusRow[], orphanRows: OrphanRow[], repoBehindMarkers: FetchStatusMarker[], duplicateHooks?: DuplicateVersionHook[]): DoctorVerdict;
 export declare function registerDoctorCommand(program: Command): void;

package/dist/commands/doctor.js

@@ -18,7 +18,7 @@ import { formatSignInBadge } from '../lib/signin-badge.js';
 import { getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalledVersions, parseAgentSpec, } from '../lib/versions.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
-import { checkVersionHookWiring, registerHooksToSettings } from '../lib/hooks.js';
+import { checkVersionHookWiring, inspectDuplicateVersionHooks, registerHooksToSettings } from '../lib/hooks.js';
 import { isVersionIsolated } from '../lib/versions.js';
 import { computeDrift, checkSyncStatus, countOrphans, computeSourceBehind } from '../lib/drift.js';
 import { readAuthHealthCache, summarizeHostAuth } from '../lib/auth-health.js';
@@ -67,11 +67,11 @@ function printWrappedLine(prefix, text) {
     for (const line of wrapLine(prefix, text))
         console.log(chalk.gray(line));
 }
-function renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn, repoBehindMarkers) {
+function renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn, repoBehindMarkers, duplicateHooks) {
     // Triaged health banner FIRST, so a user running bare `agents doctor` sees what
     // is unhealthy, why it matters, and the exact fix before scrolling the detail
     // sections below. Same triage model as target mode, aggregated across versions.
-    const overviewHealth = computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers);
+    const overviewHealth = computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers, duplicateHooks);
     console.log(chalk.bold('Health'));
     renderHealthBlock(overviewHealth, {
         healthySummary: syncRows.length
@@ -827,9 +827,26 @@ function renderHealthBlock(verdict, opts) {
  * and orphan resources into severity-tagged findings. Agent-agnostic: every
  * installed version is classified the same way. Pure, so it is unit-testable.
  */
-export function computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers) {
+export function computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers, duplicateHooks = []) {
     const issues = [];
     const pretty = (agent, version) => `${AGENT_NAMES[agent] || agent}@${version}`;
+    // critical/warning: same hook resource materialized in several version homes.
+    // Different content is more severe because a stale copy can disagree with
+    // the active gate; byte-identical copies are noise and duplicate runtime cost.
+    for (const finding of duplicateHooks) {
+        const versions = finding.copies.map((copy) => copy.version).join(', ');
+        const active = finding.authoritative.version;
+        const drift = finding.kind === 'drift';
+        issues.push({
+            severity: drift ? 'critical' : 'warning',
+            category: drift ? 'duplicate-hook-drift' : 'duplicate-hook',
+            subject: `${finding.agent}/${finding.name}`,
+            impact: `${drift ? 'different content' : 'identical content'} across versions ${versions}; ${active} is authoritative`,
+            fix: `agents sync ${finding.agent}@${active} --yes`,
+            text: `${finding.name} ${drift ? 'drift' : 'duplicated'} across ${versions}`,
+            color: drift ? 'red' : 'yellow',
+        });
+    }
     // critical: unwired hooks / broken settings.json per version
     for (const row of syncRows) {
         const n = row.unwiredHooks ?? 0;
@@ -1406,6 +1423,7 @@ export function registerDoctorCommand(program) {
             const orphanRows = countOrphans();
             const hostClis = listCliStatus(cwd);
             const repoBehindMarkers = readRepoBehindMarkers();
+            const duplicateHooks = inspectDuplicateVersionHooks(cwd);
             // Advisory login state per installed agent (file-based getAccountInfo,
             // no home → the account-global/active credential). Best-effort: a probe
             // failure just leaves that agent's badge as "logged out".
@@ -1433,7 +1451,8 @@ export function registerDoctorCommand(program) {
                     // Triaged overview health — severity/category/subject/impact/fix per
                     // finding, aggregated across versions. Additive; existing consumers
                     // reading `sync`/`orphans`/`repos` are unaffected.
-                    health: computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers),
+                    health: computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers, duplicateHooks),
+                    duplicateHooks,
                     // This host's harness inventory — installed resources per kind,
                     // installed version ids per agent, and `.agents`/`.system` repo
                     // state — so `agents doctor --devices` can compare presence across
@@ -1461,7 +1480,7 @@ export function registerDoctorCommand(program) {
                 }, null, 2));
                 return;
             }
-            renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn, repoBehindMarkers);
+            renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn, repoBehindMarkers, duplicateHooks);
             // Point at the interactive reconcile when anything is out of sync — the
             // report shouldn't be a dead end. `agents status` runs the unified
             // home-reading engine and offers to sync (opt-in, never auto-fires here).

package/dist/commands/menubar.js

@@ -65,6 +65,18 @@ export function registerMenubarCommands(program) {
         console.log(`  current version    ${chalk.gray(s.currentVersion)}`);
         console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : chalk.red('missing (cannot enable)')}`);
         console.log(`  disabled by user   ${yn(s.disabledByUser)}`);
+        if (s.foreignInstances.length > 0) {
+            // RegisterEventHotKey is first-come, so the helper that registered the
+            // chord first owns Cmd-Shift-V/O. A process list cannot say which that
+            // was — only that a rival exists — so report the conflict, not a
+            // winner. The loser
+            // has no other symptom: its chords simply never fire.
+            const n = s.foreignInstances.length;
+            console.log(chalk.yellow(`\n  ${n} other helper process${n === 1 ? '' : 'es'} running — ${n === 1 ? 'it' : 'they'} may hold Cmd-Shift-V/O instead of the installed one:`));
+            for (const p of s.foreignInstances)
+                console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
+            console.log(chalk.gray('  End it, then `agents menubar enable` to restart the installed helper.'));
+        }
         if (s.stale) {
             console.log(chalk.yellow('\n  Installed helper is stale — runs on next `agents` startup, or `agents menubar enable` now.'));
         }

package/dist/commands/routines.d.ts

@@ -6,13 +6,20 @@
  * Also exposes scheduler lifecycle controls (start/stop/status/logs).
  */
 import type { Command } from 'commander';
-import type { RunMeta } from '../lib/routines.js';
+import type { JobConfig, RunMeta } from '../lib/routines.js';
+import type { DeviceRegistry } from '../lib/devices/registry.js';
 /**
  * Human-friendly wall-clock a run took (e.g. "  · 3 min", "  · 45 sec"), or ""
  * when it hasn't completed or timestamps are unparseable. Leading separator lets
  * callers drop it straight into a status line.
  */
 export declare function formatRunDuration(startedAt: string, completedAt: string | null): string;
+export interface RoutineListGroup {
+    key: string;
+    title: string;
+    jobs: JobConfig[];
+}
+export declare function groupRoutineJobsByDevice(jobs: JobConfig[], registry: DeviceRegistry, self?: string): RoutineListGroup[];
 export declare function buildRunsJson(runs: RunMeta[]): Record<string, unknown>[];
 /** Register the `agents routines` command tree. */
 export declare function registerRoutinesCommands(program: Command): void;

package/dist/commands/routines.js

@@ -13,7 +13,7 @@ import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, } from '../lib/daemon.js';
 import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.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, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, placementRequiresFiringPin, HOST_STRATEGIES, } from '../lib/routines.js';
+import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, placementRequiresFiringPin, HOST_STRATEGIES, } from '../lib/routines.js';
 import { discoverProjectRoutinesAt, enableProjectRoutines, disableProjectRoutines, syncProjectRoutines, syncAllProjectRoutines, listEnabledProjectRoots, resolveProjectRoot, displayProjectPath, listProjectRoutineFiles, } from '../lib/routines-project.js';
 import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
@@ -24,7 +24,7 @@ import { JobScheduler } from '../lib/scheduler.js';
 import { detectOverdueJobs } from '../lib/overdue.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
-import { loadDevices } from '../lib/devices/registry.js';
+import { loadDevices, loadDevicesSync } from '../lib/devices/registry.js';
 import { machineId, normalizeHost } from '../lib/machine-id.js';
 import { addHostOption } from '../lib/hosts/option.js';
 /**
@@ -75,6 +75,164 @@ function fireConditionLabel(job) {
     }
     return '-';
 }
+function scheduleLabel(job) {
+    let label = fireConditionLabel(job);
+    if (isOneShotRoutine(job))
+        label = `${label} (one-shot)`;
+    if (job.endAt) {
+        const end = new Date(job.endAt);
+        const endLabel = Number.isFinite(end.getTime())
+            ? end.toLocaleDateString()
+            : job.endAt;
+        label = `${label} (until ${endLabel})`;
+    }
+    return label;
+}
+function nextRunForDisplay(job, scheduler) {
+    if (isPastOneShotRoutine(job))
+        return null;
+    return scheduler.getNextRun(job.name);
+}
+function nextRunLabel(job, scheduler, now) {
+    if (isPastOneShotRoutine(job))
+        return 'expired';
+    return humanizeNextRun(scheduler.getNextRun(job.name) ?? null, now, job.timezone);
+}
+function deviceStateLabel(name, registry) {
+    const profile = registry[normalizeHost(name)] ?? registry[name];
+    if (!profile)
+        return 'unknown';
+    if (profile.reachability?.reachable === false)
+        return 'offline';
+    if (profile.reachability?.reachable === true)
+        return 'online';
+    if (profile.tailscale?.online === false)
+        return 'offline';
+    if (profile.tailscale?.online === true)
+        return 'online';
+    return 'unknown';
+}
+function titleWithDeviceState(title, name, registry) {
+    const state = deviceStateLabel(name, registry);
+    return state && state !== 'online' ? `${title} (${state})` : title;
+}
+function placementTag(job) {
+    const strategy = resolveHostStrategy(job);
+    if (strategy === 'local')
+        return job.host ? `->${job.host}` : '';
+    if (strategy === 'host')
+        return `->${job.host ?? '?'}`;
+    if (strategy === 'fleet')
+        return '->fleet';
+    return '->cloud';
+}
+function deviceLabel(job, width) {
+    const full = [job.devices?.join(',') ?? '', placementTag(job)]
+        .filter(Boolean)
+        .join(' ');
+    const raw = full.length === 0 ? 'all' : full;
+    const display = width && raw.length > width
+        ? raw.slice(0, width - 1) + '…'
+        : raw;
+    return { raw, display, dim: full.length === 0 || !jobRunsOnThisDevice(job) };
+}
+export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
+    const groups = new Map();
+    const add = (key, title, job) => {
+        const existing = groups.get(key);
+        if (existing) {
+            existing.jobs.push(job);
+            return;
+        }
+        groups.set(key, { key, title, jobs: [job] });
+    };
+    for (const job of jobs) {
+        const strategy = resolveHostStrategy(job);
+        if (strategy === 'cloud') {
+            add('cloud', 'Cloud', job);
+            continue;
+        }
+        if (strategy === 'fleet') {
+            add('fleet', 'Fleet-wide', job);
+            continue;
+        }
+        if (strategy === 'host') {
+            const host = job.host ?? 'unknown-host';
+            add(`host:${normalizeHost(host)}`, titleWithDeviceState(`Host: ${host}`, host, registry), job);
+            continue;
+        }
+        const devices = job.devices ?? [];
+        if (devices.length === 0) {
+            add('fleet', 'Fleet-wide', job);
+            continue;
+        }
+        for (const device of devices) {
+            const normalized = normalizeHost(device);
+            if (normalized === self) {
+                add('this-machine', `This machine (${self})`, job);
+            }
+            else {
+                add(`device:${normalized}`, titleWithDeviceState(`Device: ${normalized}`, normalized, registry), job);
+            }
+        }
+    }
+    const order = (group) => {
+        if (group.key === 'this-machine')
+            return 0;
+        if (group.key === 'fleet')
+            return 1;
+        if (group.key === 'cloud')
+            return 2;
+        if (group.key.startsWith('device:'))
+            return 3;
+        if (group.key.startsWith('host:'))
+            return 4;
+        return 5;
+    };
+    return [...groups.values()].sort((a, b) => order(a) - order(b) || a.title.localeCompare(b.title));
+}
+function renderRoutineRows({ jobs, scheduler, overdueSet, link, now }) {
+    const NAME_W = 24;
+    const AGENT_W = 10;
+    const REPO_W = REPO_DISPLAY_MAX;
+    const DEVICE_W = 22;
+    const SCHED_W = 34;
+    const ENABLED_W = 10;
+    const NEXT_W = 22;
+    const header = `  ${'Name'.padEnd(NAME_W)} ${'Agent'.padEnd(AGENT_W)} ${'Repo'.padEnd(REPO_W)} ${'Devices'.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 + DEVICE_W + SCHED_W + ENABLED_W + NEXT_W + 20)));
+    for (const job of jobs) {
+        const nextStr = nextRunLabel(job, scheduler, now);
+        const schedStr = scheduleLabel(job);
+        const latestRun = getLatestRun(job.name);
+        const lastStatus = latestRun?.status || '-';
+        const sourceRepo = job.source?.repo ?? job.repo;
+        const sourceLabel = sourceRepo
+            ? (job.source?.branch ? `${sourceRepo}@${job.source.branch}` : sourceRepo)
+            : null;
+        const repoInfo = formatRepoLink(sourceLabel ?? job.repo);
+        const repoCell = link(repoInfo.display, repoInfo.href);
+        const repoPadding = Math.max(0, REPO_W - repoInfo.display.length);
+        const enabledStr = job.enabled ? chalk.green('yes') : chalk.gray('no');
+        const enabledWord = job.enabled ? 'yes' : 'no';
+        const enabledPad = Math.max(0, ENABLED_W - enabledWord.length);
+        const device = deviceLabel(job, DEVICE_W);
+        const deviceCell = device.dim ? chalk.gray(device.display) : device.display;
+        const devicePad = Math.max(0, DEVICE_W - device.display.length);
+        const statusColor = lastStatus === 'completed' ? chalk.green
+            : lastStatus === 'failed' ? chalk.red
+                : lastStatus === 'timeout' ? chalk.yellow
+                    : chalk.gray;
+        const overdueTag = overdueSet.has(job.name) ? chalk.yellow(' (overdue)') : '';
+        const agentLabelPadded = job.command
+            ? chalk.magenta('command'.padEnd(10))
+            : 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)} ${deviceCell}${' '.repeat(devicePad)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}`);
+    }
+}
 function parseRoutineTrigger(options) {
     const raw = typeof options.on === 'string' ? options.on : undefined;
     if (!raw)
@@ -308,7 +466,13 @@ export function registerRoutinesCommands(program) {
         .command('list')
         .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)')
+        .option('--group-by <field>', 'Group table output by device (default for terminal output)')
+        .option('--flat', 'Print the legacy flat table instead of grouped sections')
         .action((options) => {
+        if (options.groupBy && options.groupBy !== 'device') {
+            console.error(chalk.red(`Unsupported --group-by '${options.groupBy}'. Use: device`));
+            process.exit(1);
+        }
         try {
             monitorRunningJobs();
         }
@@ -339,7 +503,6 @@ export function registerRoutinesCommands(program) {
         if (options.json) {
             const nowJson = new Date();
             const payload = jobs.map((job) => {
-                const nextRun = scheduler.getNextRun(job.name);
                 const latestRun = getLatestRun(job.name);
                 return {
                     name: job.name,
@@ -357,11 +520,14 @@ export function registerRoutinesCommands(program) {
                     source: job.source ?? null,
                     sourceRepo: job.source?.repo ?? job.repo ?? null,
                     sourceBranch: job.source?.branch ?? null,
+                    runOnce: Boolean(job.runOnce),
+                    oneShot: isOneShotRoutine(job),
+                    expired: isPastOneShotRoutine(job, nowJson),
                     runsHere: jobRunsOnThisDevice(job),
                     enabled: job.enabled,
                     overdue: overdueSet.has(job.name),
-                    nextRun: nextRun ? nextRun.toISOString() : null,
-                    nextRunHuman: humanizeNextRun(nextRun ?? null, nowJson, job.timezone),
+                    nextRun: nextRunForDisplay(job, scheduler)?.toISOString() ?? null,
+                    nextRunHuman: nextRunLabel(job, scheduler, nowJson),
                     lastStatus: latestRun?.status ?? null,
                     exitCode: latestRun?.exitCode ?? null,
                     failureReason: latestRun?.errorMessage ?? null,
@@ -379,76 +545,21 @@ export function registerRoutinesCommands(program) {
         // contains raw ESC ] 8 ;; ... BEL escape sequences.
         const link = (label, url) => url && process.stdout.isTTY ? `\x1b]8;;${url}\x07${label}\x1b]8;;\x07` : label;
         const now = new Date();
-        const NAME_W = 24;
-        const AGENT_W = 10;
-        const REPO_W = REPO_DISPLAY_MAX;
-        const DEVICE_W = 22;
-        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)} ${'Devices'.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 + 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);
-            let schedStr = fireConditionLabel(job);
-            if (job.endAt) {
-                const end = new Date(job.endAt);
-                const endLabel = Number.isFinite(end.getTime())
-                    ? end.toLocaleDateString()
-                    : job.endAt;
-                schedStr = `${schedStr} (until ${endLabel})`;
-            }
-            const latestRun = getLatestRun(job.name);
-            const lastStatus = latestRun?.status || '-';
-            // Prefer project-source repo (with optional @branch) over bare job.repo.
-            const sourceRepo = job.source?.repo ?? job.repo;
-            const sourceLabel = sourceRepo
-                ? (job.source?.branch ? `${sourceRepo}@${job.source.branch}` : sourceRepo)
-                : null;
-            const repoInfo = formatRepoLink(sourceLabel ?? job.repo);
-            const repoCell = link(repoInfo.display, repoInfo.href);
-            // Pad based on the display string, not the raw cell (which may include escape codes).
-            const repoPadding = Math.max(0, REPO_W - repoInfo.display.length);
-            const enabledStr = job.enabled ? chalk.green('yes') : chalk.gray('no');
-            // 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);
-            // Placement rides in the Devices cell: eligibility →execution strategy.
-            const strategy = resolveHostStrategy(job);
-            const placementTag = strategy === 'local'
-                ? (job.host ? `→${job.host}` : '')
-                : strategy === 'host'
-                    ? `→${job.host ?? '?'}`
-                    : strategy === 'fleet'
-                        ? '→fleet'
-                        : '→cloud';
-            const deviceFull = [job.devices?.join(',') ?? '', placementTag]
-                .filter(Boolean)
-                .join(' ');
-            const deviceWord = deviceFull.length === 0
-                ? 'all'
-                : deviceFull.length > DEVICE_W
-                    ? deviceFull.slice(0, DEVICE_W - 1) + '…'
-                    : deviceFull;
-            const deviceCell = deviceFull.length === 0
-                ? chalk.gray('all')
-                : 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
-                        : chalk.gray;
-            const overdueTag = overdueSet.has(job.name) ? chalk.yellow(' (overdue)') : '';
-            const agentLabelPadded = job.command
-                ? chalk.magenta('command'.padEnd(10))
-                : 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)} ${deviceCell}${' '.repeat(devicePad)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}`);
+        if (options.flat) {
+            renderRoutineRows({ jobs, scheduler, overdueSet, link, now });
+        }
+        else {
+            let registry = {};
+            try {
+                registry = loadDevicesSync();
+            }
+            catch (err) {
+                console.error(chalk.yellow(`Could not read device registry: ${err.message}`));
+            }
+            for (const group of groupRoutineJobsByDevice(jobs, registry)) {
+                console.log(chalk.bold(`\n${group.title}`));
+                renderRoutineRows({ jobs: group.jobs, scheduler, overdueSet, link, now });
+            }
         }
         if (overdueSet.size > 0) {
             console.log();
@@ -520,6 +631,10 @@ export function registerRoutinesCommands(program) {
                 schedule = parsed.schedule;
                 runOnce = parsed.runOnce;
             }
+            if (!options.at && isOneShotLikeSchedule(schedule)) {
+                runOnce = true;
+                console.error(chalk.yellow(`Schedule "${schedule}" pins minute, hour, day, and month; treating it as one-shot. Prefer --at for one-time routines.`));
+            }
             if (!schedule && !trigger) {
                 console.error(chalk.red('Schedule or trigger is required (use --schedule, --at, or --on)'));
                 process.exit(1);
@@ -661,6 +776,10 @@ export function registerRoutinesCommands(program) {
                 enabled: true,
                 ...parsed,
             };
+            if (isOneShotLikeSchedule(config.schedule)) {
+                config.runOnce = true;
+                console.error(chalk.yellow(`Schedule "${config.schedule}" pins minute, hour, day, and month; treating it as one-shot. Prefer --at for one-time routines.`));
+            }
             // Same duplicate-fire guard as --placement/--run-on: off-box placement
             // with no eligibility pin would fire from every daemon in the fleet.
             const fileStrategy = resolveHostStrategy(config);
@@ -688,6 +807,41 @@ export function registerRoutinesCommands(program) {
             ensureSchedulerRunning();
         }
     });
+    routinesCmd
+        .command('cleanup')
+        .description('Remove expired one-shot routines that already fired and still have a user-layer YAML file.')
+        .option('--dry-run', 'Show routines that would be removed without deleting files')
+        .action((options) => {
+        const jobs = listAllJobs()
+            .filter((job) => getJobPath(job.name) !== null)
+            .filter((job) => hasCompletedOneShotRun(job));
+        if (jobs.length === 0) {
+            console.log(chalk.gray('No completed expired one-shot routines to clean up.'));
+            return;
+        }
+        if (options.dryRun) {
+            console.log(chalk.bold('Expired one-shot routines eligible for cleanup\n'));
+            for (const job of jobs) {
+                console.log(`  ${chalk.cyan(job.name)} ${chalk.gray(scheduleLabel(job))}`);
+            }
+            console.log(chalk.gray(`\nDry run. Remove with: agents routines cleanup`));
+            return;
+        }
+        let removed = 0;
+        for (const job of jobs) {
+            if (deleteJob(job.name)) {
+                removed++;
+                console.log(chalk.green(`Removed ${job.name}`));
+            }
+        }
+        console.log(chalk.gray(`Cleaned up ${removed} expired one-shot routine(s).`));
+        try {
+            signalDaemonReload();
+        }
+        catch {
+            // The daemon may not be running; the next start will read the cleaned directory.
+        }
+    });
     routinesCmd
         .command('remove [name]')
         .description('Delete a routine. Stops scheduling future runs; past execution logs remain on disk.')