@phnx-labs/agents-cli 1.20.93 → 1.21.1

package/dist/lib/menubar/install-menubar.js

@@ -25,6 +25,21 @@ import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../vers
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 const SERVICE_LABEL = 'com.phnx-labs.agents-menubar';
+/**
+ * Minimum seconds between launchd restarts of the helper (`ThrottleInterval`).
+ *
+ * The helper can crash at startup on a loaded machine: `NSApplication.shared`
+ * segfaults inside `SLSNewConnection` when WindowServer is too starved to hand
+ * out a connection. With `KeepAlive` and no throttle, launchd relaunches on its
+ * 10s default, and each attempt spawns a fresh `agents doctor --json` before
+ * dying — so a starved box gets hit harder the worse it gets. 30s bounds that
+ * respawn rate while staying well inside "the menu bar came back on its own".
+ *
+ * This only paces the restarts. What actually stops the pile-up is the helper
+ * bounding and group-killing its own children (menubar/Sources/MenubarHelper/
+ * ChildProcess.swift); the two are complementary, not alternatives.
+ */
+const MENUBAR_THROTTLE_SECONDS = 30;
 function onDarwin() {
     return process.platform === 'darwin';
 }
@@ -181,41 +196,15 @@ export function codesignVerifies(appPath) {
  * A Developer-ID-signed but un-notarized app is rejected by `spctl --assess`,
  * which macOS surfaces as "the app is damaged" and can crash AppKit during
  * launch. This is separate from `codesign --verify`: a signature can be valid
- * while Gatekeeper still refuses to run it.
+ * while Gatekeeper still refuses to run it. The release notarizes + staples the
+ * helper (menubar/scripts/build.sh, gated by verify-menubar-helper.sh), so a
+ * shipped bundle passes this; the launch guards use it to fail loud rather than
+ * bootstrap a helper macOS would reject.
  */
 export function gatekeeperAssesses(appPath) {
     const r = spawnSync('spctl', ['--assess', '--type', 'exec', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
     return r.status === 0;
 }
-/**
- * Guarantee the installed bundle has a signature Gatekeeper will accept on THIS
- * machine.
- *
- * npm's pack/extract strips the ad-hoc/linker signature the release baked into
- * the helper, leaving `code object is not signed at all`. On macOS 26+ the
- * kernel's code-signing monitor SIGKILLs an unsigned/invalid binary at launch
- * (`SIGKILL (Code Signature Invalid)`), so under the launchd `KeepAlive` service
- * an ad-hoc release helper crash-loops forever and its unstable identity makes
- * the Accessibility grant (needed for the clip→paste keystroke in Clip.swift)
- * re-prompt every time. A fresh ad-hoc re-sign gives the on-disk bytes a
- * matching cdhash, which the kernel accepts.
- *
- * A Developer-ID-signed helper survives npm untouched — its embedded signature
- * still verifies — but if the release was not notarized, Gatekeeper rejects it.
- * In that case we strip the quarantine xattr and re-sign ad-hoc so the helper
- * can launch locally. The stable fix is to notarize the release build; this
- * fallback just prevents a crash-loop while the user is on an un-notarized cut.
- */
-export function ensureValidSignature(appPath) {
-    if (codesignVerifies(appPath) && gatekeeperAssesses(appPath))
-        return true;
-    // Drop any quarantine/xattrs the tarball round-trip added (they can break
-    // both codesign and Gatekeeper), then re-sign ad-hoc under the helper's
-    // stable bundle identifier.
-    spawnSync('xattr', ['-cr', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
-    spawnSync('codesign', ['--force', '--sign', '-', '--identifier', SERVICE_LABEL, appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
-    return codesignVerifies(appPath);
-}
 /**
  * Copy the bundled `.app` to the stable user path (idempotent unless forced).
  * Returns the installed executable path, or null if no source bundle ships
@@ -229,13 +218,9 @@ export function ensureMenubarAppInstalled(opts = {}) {
         return null;
     const dest = installedAppPath();
     if (!opts.forceReinstall && fs.existsSync(dest)) {
-        // Self-heal an already-installed bundle whose signature npm stripped on a
-        // prior upgrade (macOS 26+ SIGKILLs it otherwise) without a forced recopy.
-        ensureValidSignature(dest);
         return installedExecutablePath();
     }
     copyAppBundle(src, dest);
-    ensureValidSignature(dest);
     // A fresh copy is exactly when the bundle's icon can be new (first install) or
     // superseded (upgrade) — register it so LaunchServices knows the bundle and can
     // resolve its AppIcon for the left-hand slot of daemon notifications.
@@ -245,7 +230,7 @@ export function ensureMenubarAppInstalled(opts = {}) {
 function xmlEscape(s) {
     return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
-function generateServicePlist(execPath) {
+export function generateServicePlist(execPath) {
     const home = os.homedir();
     const logPath = path.join(getHelpersDir(), 'menubar', 'menubar.log');
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
@@ -281,6 +266,8 @@ function generateServicePlist(execPath) {
   <true/>
   <key>KeepAlive</key>
   <true/>
+  <key>ThrottleInterval</key>
+  <integer>${MENUBAR_THROTTLE_SECONDS}</integer>
   <key>ProcessType</key>
   <string>Interactive</string>
   <key>StandardOutPath</key>
@@ -331,12 +318,15 @@ export function enableMenubarService(opts = { clearOptOut: true }) {
     const exec = ensureMenubarAppInstalled({ forceReinstall: true });
     if (!exec)
         return false;
-    // Never bootstrap a helper the kernel will kill on launch: an invalid
-    // signature under launchd KeepAlive is an infinite crash loop. If the bundle
-    // can't be made valid (re-sign already attempted in ensureMenubarAppInstalled),
-    // skip the service rather than spin the loop.
-    if (!codesignVerifies(installedAppPath())) {
-        process.stderr.write('agents: menu-bar helper has no valid code signature; skipping launch to avoid a crash loop.\n');
+    // Never bootstrap a helper macOS will reject at launch: an invalid signature
+    // under launchd KeepAlive crash-loops forever, and an un-notarized bundle is
+    // rejected by Gatekeeper as "damaged". A shipped helper is Developer-ID signed
+    // AND notarized (release build + the verify-menubar-helper.sh prepack gate), so
+    // this passes; if it ever doesn't, skip the service and point at the upgrade
+    // rather than re-signing over it (an ad-hoc re-sign never satisfies Gatekeeper).
+    if (!(codesignVerifies(installedAppPath()) && gatekeeperAssesses(installedAppPath()))) {
+        process.stderr.write('agents: menu-bar helper is not notarized/valid on this machine; skipping launch. ' +
+            'Upgrade to a notarized build (npm i -g @phnx-labs/agents-cli), then `agents menubar setup`.\n');
         return false;
     }
     if (opts.clearOptOut)
@@ -560,11 +550,12 @@ export function runMenubarSetup() {
         return { steps, configured: false, status: getMenubarStatus() };
     }
     step('bundle', before.installedVersion === getCliVersion() ? 'ok' : 'changed', `${installedAppPath()} (${getCliVersion()})`);
-    if (!codesignVerifies(installedAppPath())) {
-        step('signature', 'failed', 'no valid code signature — refusing to start it (launchd KeepAlive would crash-loop)');
+    if (!(codesignVerifies(installedAppPath()) && gatekeeperAssesses(installedAppPath()))) {
+        step('signature', 'failed', 'not notarized/valid on this machine — refusing to start it (Gatekeeper rejects an ' +
+            'un-notarized helper as "damaged"). Upgrade to a notarized build of agents-cli.');
         return { steps, configured: false, status: getMenubarStatus() };
     }
-    step('signature', 'ok', 'valid');
+    step('signature', 'ok', 'valid + notarized');
     // Clear the sticky opt-out: running `setup` is an explicit request for the
     // menu bar, so a stale `menubar disable` must not silently win.
     clearMenubarOptOut();

package/dist/lib/migrate.js

@@ -1708,7 +1708,7 @@ function migrateVersionResourcesToPatterns() {
         }
     }
     if (changed) {
-        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n\n';
+        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json\n\n';
         fs.writeFileSync(metaFile, META_HEADER + yaml.stringify(meta), 'utf-8');
         console.error('Migrated agents.yaml versions: entries to pattern format');
     }

package/dist/lib/models.js

@@ -20,7 +20,14 @@ const CACHE_PATH = getModelsCachePath();
  * Bump when the extractor logic changes shape in an incompatible way so cached
  * catalogs from older agents-cli builds are re-extracted.
  */
-const CACHE_SCHEMA_VERSION = 2;
+const CACHE_SCHEMA_VERSION = 3;
+/**
+ * How long a cached 0-model extraction is trusted before we retry it. Bounds
+ * the self-healing window for a transient failure (mid-install, a broken
+ * extractor regex fixed in a later agents-cli release) without falling back
+ * to re-extracting -- and re-scanning the whole binary -- on every call.
+ */
+const EMPTY_CATALOG_RETRY_MS = 24 * 60 * 60 * 1000;
 let memoryCache = null;
 function cacheKey(agent, version) {
     return `${agent}@${version}`;
@@ -884,7 +891,10 @@ export function getModelCatalog(agent, version) {
     const key = cacheKey(agent, version);
     const cached = cache.entries[key];
     if (cached && cached.sourcePath === src.path && cached.mtime === mtime) {
-        return cached.catalog;
+        const isFresh = cached.catalog.models.length > 0 ||
+            Date.now() - (cached.attemptedAt ?? 0) < EMPTY_CATALOG_RETRY_MS;
+        if (isFresh)
+            return cached.catalog;
     }
     let models = [];
     let aliases = {};
@@ -927,15 +937,15 @@ export function getModelCatalog(agent, version) {
         models,
         aliases,
     };
-    // Never cache an empty extraction, regardless of source kind. A 0-model
-    // result is always suspect: the CLI may have been mid-install, network-
-    // dependent, or transiently failing, and a js/bundle/binary extractor that
-    // regex-misses would otherwise pin an empty catalog forever (mtime won't
-    // change until the source file does). Only persist a non-empty catalog.
-    if (models.length > 0) {
-        cache.entries[key] = { sourcePath: src.path, mtime, catalog };
-        saveCache();
-    }
+    // Cache a 0-model extraction too, stamped with when it was attempted, so a
+    // broken/mid-install extractor doesn't force a full re-scan of the source
+    // binary (up to ~1.85s each for a 230-270MB Claude binary) on every call --
+    // `getModelCatalog` runs once per installed version per invocation of
+    // commands like `agents view`. It self-heals: the read site above re-tries
+    // extraction once EMPTY_CATALOG_RETRY_MS has elapsed, or immediately once
+    // the source file's mtime changes (an upgrade/reinstall).
+    cache.entries[key] = { sourcePath: src.path, mtime, catalog, attemptedAt: Date.now() };
+    saveCache();
     return catalog;
 }
 /**

package/dist/lib/monitors/config.d.ts

@@ -80,7 +80,7 @@ export interface ActionConfig {
     timeout?: string;
     /** routine: name of an existing routine to fire. */
     routine?: string;
-    /** notify: channel for the notification (default `telegram`). */
+    /** notify: override the owner channel (defaults to `notify.owner.channel`). */
     notifyChannel?: string;
     /** webhook-out: URL to POST the event to. */
     url?: string;

package/dist/lib/monitors/dispatch.d.ts

@@ -5,8 +5,12 @@
  * action goes through the *same* detached spawn cron and webhook fires use
  * (executeJobDetached, lib/runner.ts) — a monitor never duplicates spawn logic,
  * it synthesizes a JobConfig and hands it to the one dispatch seam. `notify`
- * reuses the openclaw Telegram path (lib/notify.ts); `webhook-out` POSTs the event.
+ * routes the owner through the one channel seam (sendToOwner → lookupTransport,
+ * lib/notify.ts) — recipient from notify.owner, no hardcoded chat id, and an
+ * unresolvable channel comes back as `ok: false` instead of exiting the daemon;
+ * `webhook-out` POSTs the event.
  */
+import type { Meta } from '../types.js';
 import type { ActionConfig, MonitorConfig, MonitorEvent } from './config.js';
 /** Outcome of a dispatched action. */
 export interface DispatchResult {
@@ -25,4 +29,4 @@ export declare function injectEvent(prompt: string, event: MonitorEvent): string
  * use. `routine` fires an existing routine with the event injected. `notify` and
  * `webhook-out` are terminal side-effects.
  */
-export declare function dispatchAction(monitor: MonitorConfig, event: MonitorEvent): Promise<DispatchResult>;
+export declare function dispatchAction(monitor: MonitorConfig, event: MonitorEvent, meta?: Meta): Promise<DispatchResult>;

package/dist/lib/monitors/dispatch.js

@@ -5,14 +5,14 @@
  * action goes through the *same* detached spawn cron and webhook fires use
  * (executeJobDetached, lib/runner.ts) — a monitor never duplicates spawn logic,
  * it synthesizes a JobConfig and hands it to the one dispatch seam. `notify`
- * reuses the openclaw Telegram path (lib/notify.ts); `webhook-out` POSTs the event.
+ * routes the owner through the one channel seam (sendToOwner → lookupTransport,
+ * lib/notify.ts) — recipient from notify.owner, no hardcoded chat id, and an
+ * unresolvable channel comes back as `ok: false` instead of exiting the daemon;
+ * `webhook-out` POSTs the event.
  */
-import { execFile } from 'child_process';
-import { promisify } from 'util';
 import { executeJobDetached } from '../runner.js';
 import { readJob } from '../routines.js';
-import { buildOpenClawNotifyArgs } from '../notify.js';
-const execFileAsync = promisify(execFile);
+import { sendToOwner } from '../notify.js';
 /** Replace `{event}` in a prompt with the fired event summary. */
 export function injectEvent(prompt, event) {
     return prompt.replace(/\{event\}/g, event.summary);
@@ -24,7 +24,7 @@ export function injectEvent(prompt, event) {
  * use. `routine` fires an existing routine with the event injected. `notify` and
  * `webhook-out` are terminal side-effects.
  */
-export async function dispatchAction(monitor, event) {
+export async function dispatchAction(monitor, event, meta) {
     const action = monitor.action;
     if (action.type === 'run') {
         const job = {
@@ -63,16 +63,11 @@ export async function dispatchAction(monitor, event) {
         }
     }
     if (action.type === 'notify') {
-        const args = buildOpenClawNotifyArgs(event.summary, {
-            channel: action.notifyChannel ?? 'telegram',
+        const result = await sendToOwner(event.summary, {
+            ...(meta ? { meta } : {}),
+            ...(action.notifyChannel ? { channel: action.notifyChannel } : {}),
         });
-        try {
-            await execFileAsync('openclaw', args);
-            return { kind: 'notify', ok: true };
-        }
-        catch (err) {
-            return { kind: 'notify', ok: false, error: err.message };
-        }
+        return { kind: 'notify', ok: result.ok, ...(result.ok ? {} : { error: result.error }) };
     }
     // webhook-out
     if (!action.url)

package/dist/lib/notify.d.ts

@@ -1,9 +1,29 @@
+/**
+ * Owner notifier — the one seam for "ping the human" messages.
+ *
+ * Every human-facing owner notification (feed urgent-block dispatch, monitor
+ * `notify` action, `agents notify`) funnels through the single channel seam:
+ * `lookupTransport(channel, meta).provider.send(text, opts)`. The recipient comes
+ * from `notify.owner` in agents.yaml — never a hardcoded chat id — so changing the
+ * owner is honoured by every path at once. `notify.transports` picks the actual
+ * provider per host (rush telegram on zion, openclaw-telegram on mac-mini).
+ * Best-effort: a delivery failure is returned to the caller, never thrown, so a
+ * notification hiccup never blocks the agent. That is why this module resolves
+ * with `lookupTransport` and not the `die()`-capable `resolveTransport` — the
+ * monitor daemon and the feed-dispatch loop call in here, and `process.exit()`
+ * would take them down on a typo'd channel name, bypassing their try/catch.
+ */
 import type { OpenBlock } from './feed.js';
-export interface NotifyOptions {
+import type { Meta } from './types.js';
+import type { SendResult } from './channels/registry.js';
+export interface OwnerNotifyOptions {
+    /** Config source (defaults to `readMeta()`); lets callers/tests inject it. */
+    meta?: Meta;
+    /** Override the owner channel from `notify.owner.channel`. */
     channel?: string;
-    account?: string;
-    /** OpenClaw destination (Telegram chat id). Defaults to Muqsit's chat. */
+    /** Override the owner target from `notify.owner.to`. */
     target?: string;
+    /** Resolve + build the delivery but do not actually send. */
     dryRun?: boolean;
 }
 export interface NotifyResult {
@@ -12,6 +32,22 @@ export interface NotifyResult {
     error?: string;
 }
 export declare function formatUrgentBlockMessage(block: OpenBlock): string;
-/** Build openclaw argv for urgent notify (exported for tests). */
-export declare function buildOpenClawNotifyArgs(text: string, options?: Pick<NotifyOptions, 'channel' | 'account' | 'target'>): string[];
-export declare function notifyUrgentBlock(block: OpenBlock, options?: NotifyOptions): Promise<NotifyResult>;
+/**
+ * Build openclaw argv for a Telegram send (used by the openclaw-telegram
+ * provider and its tests). `target` is required — the recipient is always
+ * resolved by the caller, never defaulted to a hardcoded number here.
+ */
+export declare function buildOpenClawNotifyArgs(text: string, opts: {
+    target: string;
+    channel?: string;
+    account?: string;
+}): string[];
+/**
+ * Deliver a message to the configured owner through the one channel seam.
+ * `channel`/`target` default to `notify.owner.{channel,to}`; `notify.transports`
+ * selects the provider per host. A missing owner config or a delivery failure
+ * (e.g. openclaw not on PATH) returns a clean `SendResult` error — never a raw
+ * ENOENT — so callers surface a consistent, best-effort failure.
+ */
+export declare function sendToOwner(text: string, options?: OwnerNotifyOptions): Promise<SendResult>;
+export declare function notifyUrgentBlock(block: OpenBlock, options?: OwnerNotifyOptions): Promise<NotifyResult>;

package/dist/lib/notify.js

@@ -1,14 +1,6 @@
-/**
- * Urgent-block phone notifier.
- *
- * Reuses the OpenClaw Telegram gateway on the local mac-mini (Jeff/`default` bot)
- * instead of raw bot tokens. Notifies once per block (tracked by `notifiedAt`).
- * Best-effort: any openclaw failure is surfaced as a warning, not a hard error,
- * so a notification hiccup never blocks the agent.
- */
-import { execFile } from 'child_process';
-import { promisify } from 'util';
-const execFileAsync = promisify(execFile);
+import { readMeta } from './state.js';
+import { registerBuiltinProviders } from './channels/providers/index.js';
+import { lookupTransport } from './channels/resolve.js';
 export function formatUrgentBlockMessage(block) {
     const q = block.questions[0];
     const header = q?.header ? `[${q.header}] ` : '';
@@ -18,11 +10,14 @@ export function formatUrgentBlockMessage(block) {
     const cost = block.costOfDelay ?? 'low';
     return `URGENT ${cls.toUpperCase()}${host}: ${header}${text} (cost: ${cost}, id: ${block.blockId})`;
 }
-/** Build openclaw argv for urgent notify (exported for tests). */
-export function buildOpenClawNotifyArgs(text, options = {}) {
-    const channel = options.channel ?? 'telegram';
-    const account = options.account ?? 'default';
-    const target = options.target ?? '6078999250';
+/**
+ * Build openclaw argv for a Telegram send (used by the openclaw-telegram
+ * provider and its tests). `target` is required — the recipient is always
+ * resolved by the caller, never defaulted to a hardcoded number here.
+ */
+export function buildOpenClawNotifyArgs(text, opts) {
+    const channel = opts.channel ?? 'telegram';
+    const account = opts.account ?? 'default';
     return [
         'message',
         'send',
@@ -31,11 +26,38 @@ export function buildOpenClawNotifyArgs(text, options = {}) {
         '--account',
         account,
         '--target',
-        target,
+        opts.target,
         '--message',
         text,
     ];
 }
+/**
+ * Deliver a message to the configured owner through the one channel seam.
+ * `channel`/`target` default to `notify.owner.{channel,to}`; `notify.transports`
+ * selects the provider per host. A missing owner config or a delivery failure
+ * (e.g. openclaw not on PATH) returns a clean `SendResult` error — never a raw
+ * ENOENT — so callers surface a consistent, best-effort failure.
+ */
+export async function sendToOwner(text, options = {}) {
+    const meta = options.meta ?? readMeta();
+    const owner = meta.notify?.owner;
+    const channel = options.channel ?? owner?.channel;
+    const target = options.target ?? owner?.to;
+    if (!channel || !target) {
+        return {
+            ok: false,
+            channel: channel ?? 'unknown',
+            id: target ?? '',
+            error: 'notify.owner.{channel,to} not set in agents.yaml',
+        };
+    }
+    registerBuiltinProviders();
+    const { provider, error } = lookupTransport(channel, meta);
+    if (!provider) {
+        return { ok: false, channel, id: target, error };
+    }
+    return provider.send(text, { target, dryRun: options.dryRun });
+}
 export async function notifyUrgentBlock(block, options = {}) {
     if (block.notifiedAt) {
         return { ok: true, skipped: true };
@@ -43,19 +65,6 @@ export async function notifyUrgentBlock(block, options = {}) {
     if (options.dryRun) {
         return { ok: true, skipped: true };
     }
-    // Check that openclaw is installed.
-    try {
-        await execFileAsync('which', ['openclaw']);
-    }
-    catch {
-        return { ok: false, error: 'openclaw CLI not found on PATH' };
-    }
-    const text = formatUrgentBlockMessage(block);
-    try {
-        await execFileAsync('openclaw', buildOpenClawNotifyArgs(text, options));
-        return { ok: true };
-    }
-    catch (err) {
-        return { ok: false, error: err.message };
-    }
+    const result = await sendToOwner(formatUrgentBlockMessage(block), options);
+    return result.ok ? { ok: true } : { ok: false, error: result.error };
 }

package/dist/lib/overdue.d.ts

@@ -31,7 +31,7 @@ export interface OverdueJob {
  * Returns null when neither is available, which leaves the routine unfloored
  * (previous behaviour) rather than silently skipping it.
  */
-export declare function routineEffectiveStart(job: JobConfig): Date | null;
+export declare function routineEffectiveStart(job: JobConfig, now?: Date): Date | null;
 /** Return every enabled, recurring job whose most recent expected fire was
  *  missed. One-shot jobs are excluded — they fire at most once. */
 export declare function detectOverdueJobs(now?: Date): OverdueJob[];

package/dist/lib/overdue.js

@@ -13,29 +13,48 @@
  */
 import * as fs from 'fs';
 import { Cron } from 'croner';
-import { listJobs, getLatestRun, getJobPath, jobRunsOnThisDevice } from './routines.js';
+import { listJobs, getLatestRun, resolveJobFilePath, isPastEndAt, isOneShotRoutine, jobRunsOnThisDevice } from './routines.js';
 import { notifyDesktop } from './menubar/notify-desktop.js';
 // Tolerance between "expected fire" and "recorded run start" — accounts for
 // the small gap between the cron tick and when the runner writes meta.json.
 const GRACE_MS = 60_000;
-const ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Lookback windows, narrowest first. A fixed one-week window silently blinded
+ * detection to any cron whose gap exceeds it: `0 9 1,13,25 * *` has 12-day gaps,
+ * so `nextRun(now - 7d)` jumped past `now`, the walk returned null, and the
+ * routine was never flagged overdue on any device — no missed record, no
+ * catch-up, permanently. Monthly, quarterly and annual routines were all in that
+ * class.
+ *
+ * A wider window is only tried when the narrower one found nothing, so a dense
+ * schedule (every minute, hourly, daily) never walks more than a week of
+ * occurrences. A sparse schedule has few occurrences to walk by definition.
+ */
+const LOOKBACK_WINDOWS_MS = [7 * DAY_MS, 32 * DAY_MS, 93 * DAY_MS, 400 * DAY_MS];
 /** Compute the most recent fire of `pattern` at or before `now`. Croner's
  *  `previousRun()` returns the cron instance's own last fire, which is null
  *  on a freshly-constructed instance — so we walk `nextRun(cursor)` forward
  *  from a week ago and keep the last fire still ≤ now. */
 function previousExpectedFire(cron, now) {
-    let cursor = new Date(now.getTime() - ONE_WEEK_MS);
-    let last = null;
-    // Cap iterations: even an every-minute schedule yields ≤ 10080 steps over a
-    // week; we cap at 20k as a paranoia bound against pathological patterns.
-    for (let i = 0; i < 20000; i++) {
-        const next = cron.nextRun(cursor);
-        if (!next || next.getTime() > now.getTime())
-            break;
-        last = next;
-        cursor = next;
+    for (const window of LOOKBACK_WINDOWS_MS) {
+        let cursor = new Date(now.getTime() - window);
+        let last = null;
+        // Cap iterations: an every-minute schedule yields ≤ 10080 steps over a week;
+        // 20k is a paranoia bound against pathological patterns. Only a schedule
+        // that found nothing in the narrower window reaches a wider one, and such a
+        // schedule is sparse, so the cap is never the binding constraint.
+        for (let i = 0; i < 20000; i++) {
+            const next = cron.nextRun(cursor);
+            if (!next || next.getTime() > now.getTime())
+                break;
+            last = next;
+            cursor = next;
+        }
+        if (last)
+            return last;
     }
-    return last;
+    return null;
 }
 /**
  * When a routine started existing, and therefore the earliest fire it can
@@ -49,13 +68,17 @@ function previousExpectedFire(cron, now) {
  * Returns null when neither is available, which leaves the routine unfloored
  * (previous behaviour) rather than silently skipping it.
  */
-export function routineEffectiveStart(job) {
+export function routineEffectiveStart(job, now = new Date()) {
     if (job.createdAt) {
         const stamped = new Date(job.createdAt);
-        if (!isNaN(stamped.getTime()))
-            return stamped;
+        // Clamp a future stamp (clock skew, a hand-edited year) to now. Left
+        // unclamped it sits after every possible expected fire, so the routine can
+        // never be flagged overdue until wall-clock time catches up.
+        if (!isNaN(stamped.getTime())) {
+            return stamped.getTime() > now.getTime() ? now : stamped;
+        }
     }
-    const path = getJobPath(job.name);
+    const path = resolveJobFilePath(job.name);
     if (!path)
         return null;
     try {
@@ -70,7 +93,19 @@ export function routineEffectiveStart(job) {
 export function detectOverdueJobs(now = new Date()) {
     const overdue = [];
     for (const job of listJobs()) {
-        if (!job.enabled || job.runOnce)
+        if (!job.enabled)
+            continue;
+        // One-shot: fires at most once, so a missed slot is not a backlog to replay.
+        // Use the same predicate the scheduler does — the raw `runOnce` flag alone
+        // missed a one-shot-LIKE schedule (a fixed minute/hour/day/month) that never
+        // carried the flag.
+        if (isOneShotRoutine(job))
+            continue;
+        // Past its configured end: catch-up must not resurrect a routine the author
+        // already retired. The scheduler only auto-disables lazily, inside a live
+        // cron tick, so a routine whose endAt elapsed while the daemon was down is
+        // still enabled on disk when the catch-up pass runs.
+        if (isPastEndAt(job, now))
             continue;
         // Trigger-only jobs (no cron schedule) never have an expected fire time.
         if (!job.schedule)
@@ -99,7 +134,7 @@ export function detectOverdueJobs(now = new Date()) {
         // a miss. Without this, any newly created routine on a daily/weekly cron is
         // instantly "overdue" for the previous occurrence — and with auto-catchup
         // that means `agents routines add` runs the routine once, immediately.
-        const start = routineEffectiveStart(job);
+        const start = routineEffectiveStart(job, now);
         if (start && expected.getTime() < start.getTime())
             continue;
         const latest = getLatestRun(job.name);