@phnx-labs/agents-cli 1.20.90 → 1.20.92

package/dist/lib/catchup.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Catch-up: run a routine whose scheduled fire this device missed.
+ *
+ * Fires are in-process croner timers, and croner only ever schedules forward
+ * from "now". A daemon that is down, asleep, or wedged when a routine comes due
+ * therefore loses that fire outright — `loadAll()` rebuilds every Cron looking
+ * only at the future (scheduler.ts), so nothing replays it. Detection has always
+ * existed (`detectOverdueJobs`), but it ran once at daemon startup and only
+ * logged plus popped a notification; the routine still never ran.
+ *
+ * This module closes that loop. A missed fire is:
+ *
+ *   1. CLAIMED — `claimMissedFire` writes a real run with status `missed`,
+ *      stamped at the time the fire was DUE, so `agents routines runs <name>`
+ *      shows the gap instead of the listing showing a weeks-old `completed` as
+ *      though it were current. The write is an atomic claim (see below), and
+ *      only the claimant proceeds to step 2.
+ *   2. RUN — unless the routine sets `catchup: false`, it is executed late via
+ *      the same `executeJobDetached` path `agents routines catchup` already used.
+ *
+ * The `missed` record is also what makes this idempotent, so there is no
+ * separate ledger to keep in sync. `detectOverdueJobs` compares the most recent
+ * expected fire against `getLatestRun(...).startedAt`; a `missed` record stamped
+ * at `expectedAt` advances that comparison, so the same missed fire is never
+ * reconsidered — across ticks, daemon restarts, or a restart storm. (A job that
+ * is overdue by definition has no run later than `expectedAt`, so the
+ * back-stamped record always sorts last in `listRuns`.)
+ *
+ * That comparison alone is not enough when two callers overlap, because both
+ * can read the same overdue set before either writes. The claim in
+ * `claimMissedFire` closes that: the record's directory is created with a
+ * non-recursive `mkdir`, an atomic test-and-set, and only the caller that wins
+ * it runs the routine. This holds across processes — the daemon's timer and a
+ * human running `agents routines catchup` — which neither an in-process flag
+ * nor `withFileLock` (synchronous; this pass awaits a spawn) can cover.
+ */
+import { type JobConfig, type RunMeta } from './routines.js';
+import { type OverdueJob } from './overdue.js';
+/** What happened to one overdue routine on a catch-up pass. */
+export interface CatchupOutcome {
+    name: string;
+    /** The fire that was missed. */
+    expectedAt: Date;
+    /**
+     * `ran` — re-run late. `recorded` — miss logged, not re-run (`catchup: false`
+     * or a dry run). `claimed-elsewhere` — a concurrent pass or process already
+     * owns this fire. `error` — could not start the late run.
+     */
+    result: 'ran' | 'recorded' | 'claimed-elsewhere' | 'error';
+    /** Run id of the late run, when one was started. */
+    runId?: string;
+    /** Why the late run could not be started. */
+    error?: string;
+}
+/**
+ * Is this routine allowed to run late? Default true — a routine you scheduled
+ * is one you expect to have run, so losing a fire silently is never the helpful
+ * default. `catchup: false` opts out a routine whose worth expires with its slot.
+ */
+export declare function shouldCatchUp(job: Pick<JobConfig, 'catchup'>): boolean;
+/** The run id a missed fire is recorded under — derived from when it was DUE. */
+export declare function missedRunId(expectedAt: Date): string;
+/**
+ * CLAIM a missed fire: atomically record that it never happened, and report
+ * whether this caller is the one that recorded it.
+ *
+ * Returns the run on a successful claim, or `null` when another caller already
+ * claimed the same (routine, expected-fire) pair. That return value is the
+ * concurrency control for the whole module — only the claimant runs the routine
+ * late, so a fire can never be spawned twice.
+ *
+ * The atomicity is the non-recursive `mkdir` of the run directory: on every
+ * POSIX filesystem that is a single test-and-set, failing with EEXIST if the
+ * directory is already there. It therefore holds between the daemon's timer and
+ * a human running `agents routines catchup` in a separate process — which an
+ * in-process re-entrancy flag cannot cover, and which a lock cannot cover either
+ * (`withFileLock` is synchronous and this pass awaits a spawn).
+ *
+ * The run id is derived from `expectedAt` rather than "now" so the same missed
+ * fire always maps to the same directory — that is what makes the claim
+ * meaningful — and so the record sorts into `listRuns` (lexical over ISO run
+ * ids) at the point the gap actually occurred.
+ *
+ * Deliberately at-most-once: a process that dies between claiming and spawning
+ * leaves the fire un-run. That is the right trade for something that starts
+ * agent processes — a double spawn costs real work and money, while the miss is
+ * still on the record for a human to see and re-run.
+ */
+export declare function claimMissedFire(job: JobConfig, expectedAt: Date): RunMeta | null;
+export interface CatchupOptions {
+    /** Record misses but start no late runs. Powers `catchup --dry-run`. */
+    dryRun?: boolean;
+    /** Clock injection seam for tests. */
+    now?: Date;
+    /** Overdue set to act on. Defaults to detecting it. Lets a caller reuse a scan. */
+    overdue?: OverdueJob[];
+}
+/**
+ * Record — and, unless opted out, re-run — every routine this device missed.
+ *
+ * Device scoping is already enforced upstream: `detectOverdueJobs` skips a job
+ * pinned elsewhere (overdue.ts), so a fleet of machines never all catch up the
+ * same routine.
+ */
+export declare function runCatchup(opts?: CatchupOptions): Promise<CatchupOutcome[]>;

package/dist/lib/catchup.js

@@ -0,0 +1,160 @@
+/**
+ * Catch-up: run a routine whose scheduled fire this device missed.
+ *
+ * Fires are in-process croner timers, and croner only ever schedules forward
+ * from "now". A daemon that is down, asleep, or wedged when a routine comes due
+ * therefore loses that fire outright — `loadAll()` rebuilds every Cron looking
+ * only at the future (scheduler.ts), so nothing replays it. Detection has always
+ * existed (`detectOverdueJobs`), but it ran once at daemon startup and only
+ * logged plus popped a notification; the routine still never ran.
+ *
+ * This module closes that loop. A missed fire is:
+ *
+ *   1. CLAIMED — `claimMissedFire` writes a real run with status `missed`,
+ *      stamped at the time the fire was DUE, so `agents routines runs <name>`
+ *      shows the gap instead of the listing showing a weeks-old `completed` as
+ *      though it were current. The write is an atomic claim (see below), and
+ *      only the claimant proceeds to step 2.
+ *   2. RUN — unless the routine sets `catchup: false`, it is executed late via
+ *      the same `executeJobDetached` path `agents routines catchup` already used.
+ *
+ * The `missed` record is also what makes this idempotent, so there is no
+ * separate ledger to keep in sync. `detectOverdueJobs` compares the most recent
+ * expected fire against `getLatestRun(...).startedAt`; a `missed` record stamped
+ * at `expectedAt` advances that comparison, so the same missed fire is never
+ * reconsidered — across ticks, daemon restarts, or a restart storm. (A job that
+ * is overdue by definition has no run later than `expectedAt`, so the
+ * back-stamped record always sorts last in `listRuns`.)
+ *
+ * That comparison alone is not enough when two callers overlap, because both
+ * can read the same overdue set before either writes. The claim in
+ * `claimMissedFire` closes that: the record's directory is created with a
+ * non-recursive `mkdir`, an atomic test-and-set, and only the caller that wins
+ * it runs the routine. This holds across processes — the daemon's timer and a
+ * human running `agents routines catchup` — which neither an in-process flag
+ * nor `withFileLock` (synchronous; this pass awaits a spawn) can cover.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { readJob, writeRunMeta, getRunDir, } from './routines.js';
+import { detectOverdueJobs } from './overdue.js';
+import { executeJobDetached } from './runner.js';
+/**
+ * Is this routine allowed to run late? Default true — a routine you scheduled
+ * is one you expect to have run, so losing a fire silently is never the helpful
+ * default. `catchup: false` opts out a routine whose worth expires with its slot.
+ */
+export function shouldCatchUp(job) {
+    return job.catchup !== false;
+}
+/** The run id a missed fire is recorded under — derived from when it was DUE. */
+export function missedRunId(expectedAt) {
+    return expectedAt.toISOString().replace(/[:.]/g, '-');
+}
+/**
+ * CLAIM a missed fire: atomically record that it never happened, and report
+ * whether this caller is the one that recorded it.
+ *
+ * Returns the run on a successful claim, or `null` when another caller already
+ * claimed the same (routine, expected-fire) pair. That return value is the
+ * concurrency control for the whole module — only the claimant runs the routine
+ * late, so a fire can never be spawned twice.
+ *
+ * The atomicity is the non-recursive `mkdir` of the run directory: on every
+ * POSIX filesystem that is a single test-and-set, failing with EEXIST if the
+ * directory is already there. It therefore holds between the daemon's timer and
+ * a human running `agents routines catchup` in a separate process — which an
+ * in-process re-entrancy flag cannot cover, and which a lock cannot cover either
+ * (`withFileLock` is synchronous and this pass awaits a spawn).
+ *
+ * The run id is derived from `expectedAt` rather than "now" so the same missed
+ * fire always maps to the same directory — that is what makes the claim
+ * meaningful — and so the record sorts into `listRuns` (lexical over ISO run
+ * ids) at the point the gap actually occurred.
+ *
+ * Deliberately at-most-once: a process that dies between claiming and spawning
+ * leaves the fire un-run. That is the right trade for something that starts
+ * agent processes — a double spawn costs real work and money, while the miss is
+ * still on the record for a human to see and re-run.
+ */
+export function claimMissedFire(job, expectedAt) {
+    const runId = missedRunId(expectedAt);
+    const runDir = getRunDir(job.name, runId);
+    fs.mkdirSync(path.dirname(runDir), { recursive: true });
+    try {
+        fs.mkdirSync(runDir); // non-recursive: throws EEXIST if already claimed
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return null;
+        throw err;
+    }
+    const at = expectedAt.toISOString();
+    const meta = {
+        jobName: job.name,
+        runId,
+        agent: job.agent,
+        workflow: job.workflow,
+        command: job.command,
+        pid: null,
+        status: 'missed',
+        startedAt: at,
+        completedAt: at,
+        exitCode: null,
+        errorMessage: 'scheduled fire missed — the scheduler was not running when it came due',
+        actor: job.actor,
+    };
+    writeRunMeta(meta);
+    return meta;
+}
+/**
+ * Record — and, unless opted out, re-run — every routine this device missed.
+ *
+ * Device scoping is already enforced upstream: `detectOverdueJobs` skips a job
+ * pinned elsewhere (overdue.ts), so a fleet of machines never all catch up the
+ * same routine.
+ */
+export async function runCatchup(opts = {}) {
+    const overdue = opts.overdue ?? detectOverdueJobs(opts.now ?? new Date());
+    const outcomes = [];
+    for (const entry of overdue) {
+        const config = readJob(entry.name);
+        if (!config) {
+            outcomes.push({
+                name: entry.name,
+                expectedAt: entry.expectedAt,
+                result: 'error',
+                error: 'config not found',
+            });
+            continue;
+        }
+        // Claim first. Losing the claim means another pass (or another process)
+        // already owns this fire — say so rather than running it a second time.
+        if (claimMissedFire(config, entry.expectedAt) === null) {
+            outcomes.push({ name: entry.name, expectedAt: entry.expectedAt, result: 'claimed-elsewhere' });
+            continue;
+        }
+        if (!shouldCatchUp(config) || opts.dryRun) {
+            outcomes.push({ name: entry.name, expectedAt: entry.expectedAt, result: 'recorded' });
+            continue;
+        }
+        try {
+            const meta = await executeJobDetached(config);
+            outcomes.push({
+                name: entry.name,
+                expectedAt: entry.expectedAt,
+                result: 'ran',
+                runId: meta.runId,
+            });
+        }
+        catch (err) {
+            outcomes.push({
+                name: entry.name,
+                expectedAt: entry.expectedAt,
+                result: 'error',
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return outcomes;
+}

package/dist/lib/channels/providers/desktop.d.ts

@@ -0,0 +1,49 @@
+import type { ChannelProvider } from '../registry.js';
+/**
+ * Split one message into the notification's title and body.
+ *
+ * A broadcast sink hands us `composeBroadcastMessage`'s shape — `<project> · <text>`
+ * with any link on a second line — so honouring the newline puts the human
+ * sentence in the title and the URL underneath, which is how the existing
+ * daemon notifications already read.
+ *
+ * Notification banners show roughly two lines before an ellipsis, so a long
+ * single-line message is split at the title boundary rather than truncated away:
+ * the head becomes the title and the remainder still arrives in the body.
+ */
+export declare function splitDesktopMessage(text: string): {
+    title: string;
+    body: string;
+};
+/**
+ * Which native notifier this platform wires, or undefined when it wires none.
+ *
+ * macOS always ships `osascript`, and `notifyDesktop` prefers the branded
+ * MenubarHelper when installed and degrades to osascript otherwise — either way
+ * something delivers. Linux depends on `notify-send`, which is NOT guaranteed
+ * (a headless box typically lacks it), so the platform answer alone is not proof
+ * there — see `desktopDeliverable`. Every other platform has no wired notifier at
+ * all (`notifyDesktop` is a documented no-op), so sending there must fail loud.
+ *
+ * Pure and platform-injectable so the gate is testable without spawning.
+ */
+export declare function desktopNotifier(platform?: NodeJS.Platform): string | undefined;
+/**
+ * Whether a notification sent right now would actually arrive.
+ *
+ * On Linux the notifier is a separate binary that is frequently absent, and
+ * `notifyDesktop` spawns it detached — an ENOENT surfaces asynchronously and is
+ * swallowed. Reporting `ok` off the platform name alone would therefore mark an
+ * undelivered notification as delivered, which is the same silent failure this
+ * provider exists to remove, just relocated. So probe for the binary.
+ *
+ * macOS needs no probe: `osascript` is part of the OS, so the degrade path is
+ * always available even when MenubarHelper is not installed.
+ */
+export declare function desktopDeliverable(platform?: NodeJS.Platform): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare const desktopProvider: ChannelProvider;

package/dist/lib/channels/providers/desktop.js

@@ -0,0 +1,132 @@
+/**
+ * Desktop provider — the local machine's native notification centre.
+ *
+ * The only channel with no external dependency: no network, no login, no vendor
+ * CLI. On the Mac the operator is sitting at it works when every other channel is
+ * dead, which is exactly when a blocked agent most needs to reach them.
+ *
+ * Delivery reuses `notifyDesktop` (lib/menubar/notify-desktop.ts), so a message
+ * sent here is attributed to MenubarHelper.app and carries the agents-cli mark —
+ * the same path that produces the "agents-cli / <title> / <body>" entries already
+ * in Notification Center.
+ *
+ * WHY THIS ISN'T A THIN PASSTHROUGH: `notifyDesktop` is deliberately
+ * fire-and-forget — it spawns detached and swallows every failure so a hiccup can
+ * never take the daemon down. A channel provider cannot inherit that: a sink that
+ * always reports `ok: true` would make an undelivered notification look delivered,
+ * which is the precise class of silent failure this whole subsystem exists to
+ * kill. So the provider resolves *deliverability* up front — is there a notifier
+ * on this platform at all — and fails loud when there is not. It reports what it
+ * can actually know: on a platform with no notifier, nothing will arrive.
+ */
+import * as os from 'os';
+import { spawnSync } from 'child_process';
+import { notifyDesktop } from '../../menubar/notify-desktop.js';
+const NAME = 'desktop';
+/** Longest title before macOS truncates it in the banner. Keeps the ask readable. */
+const TITLE_MAX = 64;
+/**
+ * Split one message into the notification's title and body.
+ *
+ * A broadcast sink hands us `composeBroadcastMessage`'s shape — `<project> · <text>`
+ * with any link on a second line — so honouring the newline puts the human
+ * sentence in the title and the URL underneath, which is how the existing
+ * daemon notifications already read.
+ *
+ * Notification banners show roughly two lines before an ellipsis, so a long
+ * single-line message is split at the title boundary rather than truncated away:
+ * the head becomes the title and the remainder still arrives in the body.
+ */
+export function splitDesktopMessage(text) {
+    const trimmed = text.trim();
+    const newline = trimmed.indexOf('\n');
+    if (newline !== -1) {
+        return {
+            title: trimmed.slice(0, newline).trim().slice(0, TITLE_MAX),
+            body: trimmed.slice(newline + 1).trim(),
+        };
+    }
+    if (trimmed.length <= TITLE_MAX) {
+        return { title: trimmed, body: '' };
+    }
+    // Break on the last word boundary inside the limit so the title doesn't end
+    // mid-word; fall back to a hard cut when there is no space to break on.
+    const head = trimmed.slice(0, TITLE_MAX);
+    const cut = head.lastIndexOf(' ');
+    const at = cut > TITLE_MAX / 2 ? cut : TITLE_MAX;
+    return { title: trimmed.slice(0, at).trim(), body: trimmed.slice(at).trim() };
+}
+/**
+ * Which native notifier this platform wires, or undefined when it wires none.
+ *
+ * macOS always ships `osascript`, and `notifyDesktop` prefers the branded
+ * MenubarHelper when installed and degrades to osascript otherwise — either way
+ * something delivers. Linux depends on `notify-send`, which is NOT guaranteed
+ * (a headless box typically lacks it), so the platform answer alone is not proof
+ * there — see `desktopDeliverable`. Every other platform has no wired notifier at
+ * all (`notifyDesktop` is a documented no-op), so sending there must fail loud.
+ *
+ * Pure and platform-injectable so the gate is testable without spawning.
+ */
+export function desktopNotifier(platform = os.platform()) {
+    if (platform === 'darwin')
+        return 'menubar-or-osascript';
+    if (platform === 'linux')
+        return 'notify-send';
+    return undefined;
+}
+/**
+ * Whether a notification sent right now would actually arrive.
+ *
+ * On Linux the notifier is a separate binary that is frequently absent, and
+ * `notifyDesktop` spawns it detached — an ENOENT surfaces asynchronously and is
+ * swallowed. Reporting `ok` off the platform name alone would therefore mark an
+ * undelivered notification as delivered, which is the same silent failure this
+ * provider exists to remove, just relocated. So probe for the binary.
+ *
+ * macOS needs no probe: `osascript` is part of the OS, so the degrade path is
+ * always available even when MenubarHelper is not installed.
+ */
+export function desktopDeliverable(platform = os.platform()) {
+    const notifier = desktopNotifier(platform);
+    if (!notifier) {
+        return { ok: false, reason: `no desktop notifier on ${platform} — nothing would be delivered` };
+    }
+    if (platform === 'linux') {
+        const probe = spawnSync('which', ['notify-send'], { stdio: 'ignore' });
+        if (probe.status !== 0) {
+            return { ok: false, reason: 'notify-send not on PATH — nothing would be delivered' };
+        }
+    }
+    return { ok: true };
+}
+export const desktopProvider = {
+    name: NAME,
+    async send(text, opts) {
+        // `target` is meaningless for a local notification — the recipient is whoever
+        // is at this machine — but it is echoed for --json parity with every other
+        // provider, and `agents notify` still requires notify.owner.to to be set.
+        const id = opts.target || os.hostname();
+        // Order matters, and CI caught it: validate the CALLER first, then honour
+        // dry-run, and only then probe the platform.
+        //
+        // An empty message is a caller error on every platform, so it must not be
+        // masked by "this box has no notifier" — the specific, actionable error wins.
+        // And `--dry-run` means "resolve + build but do not send", so it must not
+        // depend on the ability to send; the sibling rush provider likewise returns
+        // ok for a dry run before its own `which rush` check (providers/rush.ts).
+        const { title, body } = splitDesktopMessage(text);
+        if (!title) {
+            return { ok: false, channel: NAME, id, error: 'refusing to send an empty notification' };
+        }
+        if (opts.dryRun) {
+            return { ok: true, channel: NAME, id };
+        }
+        const deliverable = desktopDeliverable();
+        if (!deliverable.ok) {
+            return { ok: false, channel: NAME, id, error: deliverable.reason };
+        }
+        notifyDesktop({ title, body });
+        return { ok: true, channel: NAME, id };
+    },
+};

package/dist/lib/channels/providers/index.js

@@ -7,6 +7,7 @@ import { registerChannelProvider } from '../registry.js';
 import { mailboxProvider } from './mailbox.js';
 import { rushProviders } from './rush.js';
 import { openclawTelegramProvider } from './openclaw-telegram.js';
+import { desktopProvider } from './desktop.js';
 let registered = false;
 /** Register all built-in providers once (idempotent). */
 export function registerBuiltinProviders() {
@@ -17,4 +18,5 @@ export function registerBuiltinProviders() {
     for (const p of rushProviders)
         registerChannelProvider(p);
     registerChannelProvider(openclawTelegramProvider);
+    registerChannelProvider(desktopProvider);
 }

package/dist/lib/daemon.js

@@ -18,6 +18,7 @@ import { JobScheduler } from './scheduler.js';
 import { MonitorEngine } from './monitors/engine.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
 import { detectOverdueJobs, notifyOverdue } from './overdue.js';
+import { runCatchup } from './catchup.js';
 import { notifyRoutineStart, notifyRoutineFinish, notifyRoutineStartFailed } from './routine-notify.js';
 import { BrowserService } from './browser/service.js';
 import { BrowserIPCServer } from './browser/ipc.js';
@@ -32,6 +33,14 @@ 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;
+/**
+ * How often to re-scan for missed fires. Deliberately slower than the monitor
+ * tick: detection walks a week of cron occurrences per routine
+ * (`previousExpectedFire`), and a fire that was already missed is not urgent to
+ * the second — five minutes bounds the cost while still recovering from a
+ * wedge or an OS suspend the process survived.
+ */
+const CATCHUP_TICK_MS = 5 * 60_000;
 const WEDGE_THRESHOLD_TICKS = 3;
 /**
  * RUSH-1817: decide whether the daemon should (re)take over hosting the secrets
@@ -477,25 +486,76 @@ export async function runDaemon() {
     catch (err) {
         log('ERROR', `Monitor engine failed to start: ${err.message}`);
     }
-    // Backlog detection: any enabled recurring job whose most-recent expected
-    // fire is older than its most-recent recorded run is overdue. Happens when
-    // the laptop was off or the daemon crashed through a scheduled fire.
-    // We log it and pop a native notification — the user can review with
-    // `agents routines list` and run them with `agents routines catchup`.
-    try {
-        const overdue = detectOverdueJobs();
-        if (overdue.length > 0) {
-            log('WARN', `${overdue.length} routine(s) overdue:`);
+    // Backlog recovery: any enabled recurring job whose most-recent expected fire
+    // is older than its most-recent recorded run was missed — the laptop slept,
+    // the machine was off, or the daemon crashed through the fire. croner only
+    // schedules forward from "now", so nothing replays it on its own.
+    //
+    // Every miss is RECORDED as a `missed` run and, unless the routine sets
+    // `catchup: false`, RUN late. Runs on a timer as well as at startup: a startup
+    // pass alone misses a fire lost while the daemon stayed up but its event loop
+    // was wedged, or one lost across an OS suspend that the process survived.
+    // Overlap guard, same shape as runSessionSync/runHealCheck below. A pass
+    // awaits executeJobDetached per job and an off-box (host/cloud) dispatch can
+    // block for a while, so a slow pass could still be working when the next tick
+    // fires. Both passes would then see a job the first has not yet reached as
+    // overdue — the miss is recorded before the await, but only for jobs already
+    // processed — and spawn it twice. The idempotency of the `missed` record
+    // guards across passes, not within one that is mid-flight.
+    let catchingUp = false;
+    const catchupPass = async () => {
+        if (catchingUp)
+            return;
+        catchingUp = true;
+        try {
+            const overdue = detectOverdueJobs();
+            if (overdue.length === 0)
+                return;
+            log('WARN', `${overdue.length} routine(s) missed their fire:`);
             for (const job of overdue) {
                 const last = job.lastRanAt ? job.lastRanAt.toISOString() : 'never';
                 log('WARN', `  ${job.name} -- expected ${job.expectedAt.toISOString()}, last ran ${last}`);
             }
             notifyOverdue(overdue);
+            const outcomes = await runCatchup({ overdue });
+            for (const o of outcomes) {
+                // Every variant handled explicitly: a catch-all else would log the
+                // benign 'claimed-elsewhere' (another process legitimately won the
+                // claim) as an ERROR with an undefined reason.
+                switch (o.result) {
+                    case 'ran':
+                        log('INFO', `Caught up '${o.name}' (run: ${o.runId})`);
+                        break;
+                    case 'recorded':
+                        log('INFO', `Recorded missed fire for '${o.name}' (catchup disabled)`);
+                        break;
+                    case 'claimed-elsewhere':
+                        log('INFO', `Missed fire for '${o.name}' already claimed by another catchup`);
+                        break;
+                    case 'error':
+                        log('ERROR', `Catchup for '${o.name}' failed: ${o.error}`);
+                        break;
+                    default: {
+                        // Compile-time exhaustiveness: a new CatchupOutcome variant fails
+                        // typecheck here rather than silently landing in the wrong log level,
+                        // which is exactly how 'claimed-elsewhere' was first missed.
+                        const unhandled = o.result;
+                        log('ERROR', `Catchup for '${o.name}' returned an unhandled result: ${String(unhandled)}`);
+                    }
+                }
+            }
         }
-    }
-    catch (err) {
-        log('ERROR', `Overdue detection failed: ${err.message}`);
-    }
+        catch (err) {
+            log('ERROR', `Catchup pass failed: ${err.message}`);
+        }
+        finally {
+            // finally, not a tail assignment: the no-overdue path returns early, and a
+            // throw must not leave the guard latched shut for the daemon's lifetime.
+            catchingUp = false;
+        }
+    };
+    await catchupPass();
+    const catchupInterval = setInterval(() => { void catchupPass(); }, CATCHUP_TICK_MS);
     // Before the BrowserService comes up, reap browser + tunnel processes
     // spawned by previous daemons that are no longer alive. Without this,
     // a daemon hard-crash (SIGKILL, OOM) would leak every browser and SSH
@@ -834,6 +894,7 @@ export async function runDaemon() {
         monitorEngine.stop();
         await browserIPC.stop();
         clearInterval(monitorInterval);
+        clearInterval(catchupInterval);
         clearInterval(syncInterval);
         clearInterval(healInterval);
         clearTimeout(healKickoff);

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

@@ -80,6 +80,20 @@ export interface DeviceProfile {
 export declare function deviceRole(d: DeviceProfile): DeviceRole;
 /** True for a control-only device (a cockpit) that must never be dialed/scheduled. */
 export declare function isControlDevice(d: DeviceProfile): boolean;
+/**
+ * Whether a fan-out should dial this device, honouring the preference stated on
+ * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
+ * {@link DeviceTailscale.online} snapshot.
+ *
+ * Reading only `tailscale.online` is wrong in both directions, and both were
+ * live on a real fleet. A `via:"manual"` device never gets a tailscale peer
+ * entry at all, so its `online` is permanently `undefined` and a strict
+ * `=== true` test skipped it forever — every session on that box was invisible
+ * to the cross-fleet sweep. Conversely a box that has since gone to sleep keeps
+ * a stale `online:true` and gets dialed, burning a full ConnectTimeout and
+ * reporting a false "unreachable" that callers treat as doubt.
+ */
+export declare function isDialableDevice(d: DeviceProfile): boolean;
 /** Map of device name to profile. */
 export type DeviceRegistry = Record<string, DeviceProfile>;
 /** Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.). */

package/dist/lib/devices/registry.js

@@ -27,6 +27,43 @@ export function deviceRole(d) {
 export function isControlDevice(d) {
     return deviceRole(d) === 'control';
 }
+/**
+ * Whether a fan-out should dial this device, honouring the preference stated on
+ * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
+ * {@link DeviceTailscale.online} snapshot.
+ *
+ * Reading only `tailscale.online` is wrong in both directions, and both were
+ * live on a real fleet. A `via:"manual"` device never gets a tailscale peer
+ * entry at all, so its `online` is permanently `undefined` and a strict
+ * `=== true` test skipped it forever — every session on that box was invisible
+ * to the cross-fleet sweep. Conversely a box that has since gone to sleep keeps
+ * a stale `online:true` and gets dialed, burning a full ConnectTimeout and
+ * reporting a false "unreachable" that callers treat as doubt.
+ */
+export function isDialableDevice(d) {
+    // Union, deliberately: either signal saying "go" is enough. A probe may only
+    // ADD a peer to the sweep, never remove one.
+    //
+    // The probe is not trustworthy enough to exclude on. It runs with a short SSH
+    // budget, so on a congested tailnet it returns false negatives — observed
+    // marking the LOCAL machine unreachable, and flipping a live worker box from
+    // reachable to unreachable nine minutes apart. Letting that shrink the sweep
+    // would hide sessions on healthy boxes, a worse failure than the one below.
+    //
+    // The snapshot alone is not enough either: a device registered with
+    // `address.via: "manual"` never gets a tailscale peer entry, so `online`
+    // stays undefined and a strict `=== true` test skipped it forever, making
+    // every session on that box unresolvable from any other machine.
+    //
+    // So: no tailscale block at all is unknown-not-offline (the rule `ssh.ts`
+    // renderDeviceTable and Factory's `isDeviceOnline` already use, so the picker
+    // and the sweep agree on who exists), and a positive probe rescues a device
+    // whose snapshot says offline. The cost of dialing a box that is actually
+    // asleep is one ConnectTimeout — the pre-existing behaviour, not a regression.
+    if (d.reachability?.reachable)
+        return true;
+    return !d.tailscale || d.tailscale.online === true;
+}
 function registryPath() {
     return getDevicesRegistryPath();
 }