@phnx-labs/agents-cli 1.22.54 → 1.22.56

package/dist/lib/daemon/session-state-service.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Live-session metadata publisher as a supervised periodic service.
+ *
+ * This is the single daemon-owned writer behind `sessions watch`: consumers
+ * announce reader presence, and the service publishes an incremental journal
+ * snapshot immediately on the idle->active edge and every 15 seconds while a
+ * reader remains. Callers consume the row; they do not run their own gather.
+ */
+import type { DaemonServiceId } from '../daemon-services.js';
+import { BasePeriodicService, type DaemonContext } from './service.js';
+export declare class SessionStateService extends BasePeriodicService {
+    private readonly wake;
+    readonly id: DaemonServiceId;
+    readonly intervalMs = 15000;
+    readonly deadlineMs = 30000;
+    private stopReaderWatch;
+    constructor(wake: () => void);
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(_ctx: DaemonContext): Promise<void>;
+}

package/dist/lib/daemon/session-state-service.js

@@ -0,0 +1,34 @@
+/**
+ * Live-session metadata publisher as a supervised periodic service.
+ *
+ * This is the single daemon-owned writer behind `sessions watch`: consumers
+ * announce reader presence, and the service publishes an incremental journal
+ * snapshot immediately on the idle->active edge and every 15 seconds while a
+ * reader remains. Callers consume the row; they do not run their own gather.
+ */
+import { runActiveSessionsWarmTick } from '../daemon-ticks.js';
+import { watchActiveSessionsReaderPresence } from '../session/session-cache.js';
+import { BasePeriodicService } from './service.js';
+const SESSION_STATE_TICK_MS = 15_000;
+const SESSION_STATE_DEADLINE_MS = 30_000;
+export class SessionStateService extends BasePeriodicService {
+    wake;
+    id = 'session-state';
+    intervalMs = SESSION_STATE_TICK_MS;
+    deadlineMs = SESSION_STATE_DEADLINE_MS;
+    stopReaderWatch = null;
+    constructor(wake) {
+        super();
+        this.wake = wake;
+    }
+    async onStart(_ctx) {
+        this.stopReaderWatch = watchActiveSessionsReaderPresence(this.wake);
+    }
+    async onStop() {
+        this.stopReaderWatch?.();
+        this.stopReaderWatch = null;
+    }
+    async onTick(_ctx) {
+        await runActiveSessionsWarmTick();
+    }
+}

package/dist/lib/daemon/supervisor.d.ts

@@ -12,9 +12,9 @@
  *  - A tick that hangs on an unbounded await (SSH, keychain) used to latch its
  *    local in-flight guard `true` forever, silently freezing that one service
  *    for the daemon's life (observed ~51h). Here, every tick races a
- *    `deadlineMs` timeout; when the deadline wins, the guard is released in
- *    `finally` regardless of whether the real tick promise ever settles, so
- *    the NEXT scheduled tick can still run.
+ *    `deadlineMs` timeout; when the deadline wins, that service is parked and
+ *    its in-flight guard stays held until the real promise settles. This keeps
+ *    a timed-out tick from overlapping another tick or lifecycle transition.
  *
  * Repeated failures (thrown or timed-out) open a circuit breaker: the service
  * is parked (its timer stopped) and retried on exponential backoff via its own
@@ -24,7 +24,7 @@
 import type { DaemonServiceId } from '../daemon-services.js';
 import type { DaemonContext, DaemonService, ServiceHealth } from './service.js';
 export interface ServiceSupervisorOptions {
-    /** Consecutive tick failures (throw or deadline breach) before a service is parked. Default 3. */
+    /** Consecutive thrown tick failures before a service is parked. Deadline breaches park immediately. Default 3. */
     parkAfterFailures?: number;
     /** First restart backoff delay, doubled on each further failed restart attempt. Default 5s. */
     backoffBaseMs?: number;
@@ -57,6 +57,12 @@ export declare class ServiceSupervisor {
     isRegistered(id: DaemonServiceId): boolean;
     /** Every currently registered service id. */
     registeredIds(): DaemonServiceId[];
+    /**
+     * Resolve when the service's current tick has really settled. Daemon control
+     * edges use this to queue a requested live transition without polling or
+     * treating a deadline race as cancellation.
+     */
+    awaitIdle(id: DaemonServiceId): Promise<void>;
     /**
      * Start one registered service live — drives `agents daemon services enable
      * <id>` (RUSH-3193 P4). Only affects a service already registered on this
@@ -67,6 +73,8 @@ export declare class ServiceSupervisor {
     start(id: DaemonServiceId): Promise<void>;
     /** Stop one registered service live — drives `agents daemon services disable <id>` (RUSH-3193 P4). */
     stop(id: DaemonServiceId): Promise<void>;
+    /** Request an immediate supervised tick, used by event edges that cannot wait for the regular cadence. */
+    runNow(id: DaemonServiceId): void;
     /** Health for every registered service, keyed by service id. */
     health(): Record<string, ServiceHealth>;
     private startOne;
@@ -75,13 +83,15 @@ export declare class ServiceSupervisor {
     /**
      * Run one tick under a hard deadline. The deadline is enforced with
      * `Promise.race`, not true cancellation — JS cannot abort an arbitrary
-     * in-flight await. What matters for the freeze this replaces is that
-     * `inFlight` is released in `finally` as soon as the race settles, so an
-     * abandoned tick can never block the next scheduled one again.
+     * in-flight await. A timeout parks the service immediately but deliberately
+     * keeps `inFlight` set until the REAL promise settles. Starting another tick
+     * or tearing resources down underneath the abandoned one would trade a
+     * visible parked service for duplicated side effects and lifecycle races.
      */
     private runTick;
     private park;
     private scheduleRestart;
     private attemptRestart;
     private recordFailure;
+    private finishTick;
 }

package/dist/lib/daemon/supervisor.js

@@ -12,9 +12,9 @@
  *  - A tick that hangs on an unbounded await (SSH, keychain) used to latch its
  *    local in-flight guard `true` forever, silently freezing that one service
  *    for the daemon's life (observed ~51h). Here, every tick races a
- *    `deadlineMs` timeout; when the deadline wins, the guard is released in
- *    `finally` regardless of whether the real tick promise ever settles, so
- *    the NEXT scheduled tick can still run.
+ *    `deadlineMs` timeout; when the deadline wins, that service is parked and
+ *    its in-flight guard stays held until the real promise settles. This keeps
+ *    a timed-out tick from overlapping another tick or lifecycle transition.
  *
  * Repeated failures (thrown or timed-out) open a circuit breaker: the service
  * is parked (its timer stopped) and retried on exponential backoff via its own
@@ -67,17 +67,35 @@ export class ServiceSupervisor {
     /** Stop every registered service and clear all timers. */
     async stopAll() {
         for (const id of this.registry.keys())
-            await this.stopOne(id);
+            await this.stopOne(id, true);
     }
     /** Force one service to restart right now, outside its normal backoff schedule. Drives `agents daemon services restart <id>` (RUSH-3193 P4). */
     async restartOne(id) {
         const entry = this.registry.get(id);
         if (!entry)
             throw new Error(`service '${id}' is not registered`);
+        if (entry.inFlight) {
+            throw new Error(`service '${id}' cannot restart while a tick is still in flight`);
+        }
+        // A live periodic service already owns an interval. attemptRestart() installs
+        // a fresh one after restart, so leaving the existing handles alive would
+        // multiply the tick rate on every operator-requested restart.
+        if (entry.timer) {
+            clearInterval(entry.timer);
+            entry.timer = undefined;
+        }
+        if (entry.startupTimer) {
+            clearTimeout(entry.startupTimer);
+            entry.startupTimer = undefined;
+        }
         if (entry.restartTimer) {
             clearTimeout(entry.restartTimer);
             entry.restartTimer = undefined;
         }
+        // Block a timer callback already queued in this event-loop turn while the
+        // service tears down and starts again.
+        entry.state = 'parked';
+        recordSubsystemState(id, 'parked');
         await this.attemptRestart(id);
     }
     /** Whether `id` is registered on this supervisor. A service disabled at daemon boot is never registered — see {@link start}. */
@@ -88,6 +106,20 @@ export class ServiceSupervisor {
     registeredIds() {
         return Array.from(this.registry.keys());
     }
+    /**
+     * Resolve when the service's current tick has really settled. Daemon control
+     * edges use this to queue a requested live transition without polling or
+     * treating a deadline race as cancellation.
+     */
+    async awaitIdle(id) {
+        const entry = this.registry.get(id);
+        if (!entry)
+            throw new Error(`service '${id}' is not registered`);
+        const activeTick = entry.activeTick;
+        if (!activeTick)
+            return;
+        await activeTick.catch(() => undefined);
+    }
     /**
      * Start one registered service live — drives `agents daemon services enable
      * <id>` (RUSH-3193 P4). Only affects a service already registered on this
@@ -101,6 +133,9 @@ export class ServiceSupervisor {
             throw new Error(`service '${id}' is not registered`);
         if (entry.state === 'running')
             return;
+        if (entry.inFlight) {
+            throw new Error(`service '${id}' cannot start while a tick is still in flight`);
+        }
         await this.startOne(id);
     }
     /** Stop one registered service live — drives `agents daemon services disable <id>` (RUSH-3193 P4). */
@@ -110,7 +145,13 @@ export class ServiceSupervisor {
             throw new Error(`service '${id}' is not registered`);
         if (entry.state === 'stopped')
             return;
-        await this.stopOne(id);
+        await this.stopOne(id, false);
+    }
+    /** Request an immediate supervised tick, used by event edges that cannot wait for the regular cadence. */
+    runNow(id) {
+        if (!this.registry.has(id))
+            throw new Error(`service '${id}' is not registered`);
+        void this.runTick(id);
     }
     /** Health for every registered service, keyed by service id. */
     health() {
@@ -164,10 +205,13 @@ export class ServiceSupervisor {
             recordSubsystemOk(id);
         }
     }
-    async stopOne(id) {
+    async stopOne(id, force) {
         const entry = this.registry.get(id);
         if (!entry)
             return;
+        if (entry.inFlight && !force) {
+            throw new Error(`service '${id}' cannot stop while a tick is still in flight`);
+        }
         if (entry.timer) {
             clearInterval(entry.timer);
             entry.timer = undefined;
@@ -182,6 +226,11 @@ export class ServiceSupervisor {
         }
         entry.state = 'stopped';
         recordSubsystemState(id, 'stopped');
+        // Whole-daemon shutdown must not hang forever on an unresolved tick, but it
+        // also must not tear down resources the tick may still be using. Stop its
+        // timers and mark it stopped; process exit owns final cleanup in this case.
+        if (entry.inFlight && force)
+            return;
         if (!entry.everStarted)
             return; // start() never succeeded — nothing to stop.
         try {
@@ -200,9 +249,10 @@ export class ServiceSupervisor {
     /**
      * Run one tick under a hard deadline. The deadline is enforced with
      * `Promise.race`, not true cancellation — JS cannot abort an arbitrary
-     * in-flight await. What matters for the freeze this replaces is that
-     * `inFlight` is released in `finally` as soon as the race settles, so an
-     * abandoned tick can never block the next scheduled one again.
+     * in-flight await. A timeout parks the service immediately but deliberately
+     * keeps `inFlight` set until the REAL promise settles. Starting another tick
+     * or tearing resources down underneath the abandoned one would trade a
+     * visible parked service for duplicated side effects and lifecycle races.
      */
     async runTick(id) {
         const entry = this.registry.get(id);
@@ -216,11 +266,17 @@ export class ServiceSupervisor {
         const periodicService = entry.service;
         entry.inFlight = true;
         let deadlineTimer;
+        let timedOut = false;
+        const tickPromise = periodicService.tick(ctx);
+        entry.activeTick = tickPromise;
         try {
             const deadline = new Promise((_, reject) => {
-                deadlineTimer = setTimeout(() => reject(new Error(`tick exceeded deadline of ${periodicService.deadlineMs}ms`)), periodicService.deadlineMs);
+                deadlineTimer = setTimeout(() => {
+                    timedOut = true;
+                    reject(new Error(`tick exceeded deadline of ${periodicService.deadlineMs}ms`));
+                }, periodicService.deadlineMs);
             });
-            await Promise.race([periodicService.tick(ctx), deadline]);
+            await Promise.race([tickPromise, deadline]);
             entry.consecutiveFailures = 0;
             entry.lastError = undefined;
             entry.lastRunMs = Date.now();
@@ -228,13 +284,20 @@ export class ServiceSupervisor {
         }
         catch (err) {
             this.recordFailure(entry, id, err);
-            if (entry.consecutiveFailures >= this.parkAfterFailures)
+            if (timedOut || entry.consecutiveFailures >= this.parkAfterFailures)
                 this.park(id);
         }
         finally {
             if (deadlineTimer)
                 clearTimeout(deadlineTimer);
-            entry.inFlight = false;
+            if (timedOut) {
+                // Promise.race cannot cancel arbitrary work. Keep the service parked and
+                // in-flight until the REAL tick settles; only then may backoff restart it.
+                void tickPromise.then(() => this.finishTick(id, tickPromise), () => this.finishTick(id, tickPromise));
+            }
+            else {
+                this.finishTick(id, tickPromise);
+            }
         }
     }
     park(id) {
@@ -248,7 +311,8 @@ export class ServiceSupervisor {
             entry.timer = undefined;
         }
         this.ctx?.log('WARN', `service '${id}' parked after ${entry.consecutiveFailures} consecutive failure(s)`);
-        this.scheduleRestart(id);
+        if (!entry.inFlight)
+            this.scheduleRestart(id);
     }
     scheduleRestart(id) {
         const entry = this.registry.get(id);
@@ -295,4 +359,13 @@ export class ServiceSupervisor {
         recordSubsystemError(id, message);
         this.ctx?.log('WARN', `service '${id}' failed: ${message}`);
     }
+    finishTick(id, tickPromise) {
+        const entry = this.registry.get(id);
+        if (!entry || entry.activeTick !== tickPromise)
+            return;
+        entry.activeTick = undefined;
+        entry.inFlight = false;
+        if (entry.state === 'parked' && !entry.restartTimer)
+            this.scheduleRestart(id);
+    }
 }

package/dist/lib/daemon/tmux-reap-service.d.ts

@@ -0,0 +1,11 @@
+/** Dead managed tmux session and orphan-helper cleanup under supervision. */
+import type { DaemonServiceId } from '../daemon-services.js';
+import { BasePeriodicService, type DaemonContext } from './service.js';
+export declare class TmuxReapService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs: number;
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+}

package/dist/lib/daemon/tmux-reap-service.js

@@ -0,0 +1,28 @@
+/** Dead managed tmux session and orphan-helper cleanup under supervision. */
+import { getDefaultSocketPath } from '../tmux/paths.js';
+import { reapDeadTmuxPanes } from '../tmux/session.js';
+import { BasePeriodicService } from './service.js';
+const TMUX_REAP_TICK_MS = 5 * 60_000;
+const TMUX_REAP_DEADLINE_MS = 2 * 60_000;
+export class TmuxReapService extends BasePeriodicService {
+    id = 'tmux-reap';
+    intervalMs = TMUX_REAP_TICK_MS;
+    deadlineMs = TMUX_REAP_DEADLINE_MS;
+    async onStart(_ctx) { }
+    async onStop() { }
+    async onTick(ctx) {
+        const result = await reapDeadTmuxPanes(getDefaultSocketPath());
+        for (const warning of result.warnings)
+            ctx.log('WARN', `Dead-pane reaper: ${warning}`);
+        if (result.processes > 0) {
+            ctx.log('INFO', `Dead-pane reaper: terminated ${result.processes} orphaned helper process(es)`);
+            for (const detail of result.processDetails)
+                ctx.log('INFO', `  ${detail}`);
+        }
+        if (result.reaped > 0) {
+            ctx.log('INFO', `Dead-pane reaper: reaped ${result.reaped} session(s)`);
+            for (const detail of result.details)
+                ctx.log('INFO', `  killed ${detail}`);
+        }
+    }
+}

package/dist/lib/daemon/webhook-receiver-service.d.ts

@@ -0,0 +1,9 @@
+/** Signed webhook receiver lifecycle under the daemon service supervisor. */
+import type { DaemonServiceId } from '../daemon-services.js';
+import { BaseDaemonService, type DaemonContext } from './service.js';
+export declare class WebhookReceiverService extends BaseDaemonService {
+    readonly id: DaemonServiceId;
+    private receivers;
+    protected onStart(ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+}

package/dist/lib/daemon/webhook-receiver-service.js

@@ -0,0 +1,17 @@
+/** Signed webhook receiver lifecycle under the daemon service supervisor. */
+import { startHostedWebhookReceivers } from '../daemon-webhooks.js';
+import { BaseDaemonService } from './service.js';
+export class WebhookReceiverService extends BaseDaemonService {
+    id = 'webhook-receiver';
+    receivers = null;
+    async onStart(ctx) {
+        this.receivers = await startHostedWebhookReceivers({ log: ctx.log });
+        ctx.log('INFO', this.receivers.count > 0
+            ? `Webhook receiver hosting ${this.receivers.count} receiver(s)`
+            : 'Webhook receiver service enabled; no receivers declared in daemon/webhooks.yaml');
+    }
+    async onStop() {
+        await this.receivers?.close();
+        this.receivers = null;
+    }
+}

package/dist/lib/daemon-services.d.ts

@@ -7,7 +7,7 @@
  * enabled without pulling in the whole daemon lifecycle.
  */
 /** Every service the daemon can host. IDs are kebab-case and stable. */
-export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'keychain-reap' | 'account-state' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync';
+export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'keychain-reap' | 'account-state' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state';
 /** Human-readable metadata for each service. */
 export interface DaemonServiceDef {
     id: DaemonServiceId;

package/dist/lib/daemon-services.js

@@ -67,6 +67,26 @@ export const DAEMON_SERVICES = [
         title: 'State-dir self-check',
         description: 'Self-terminates the daemon if its state directory is removed.',
     },
+    {
+        id: 'daemon-heartbeat',
+        title: 'Daemon heartbeat',
+        description: 'Publishes daemon liveness and reconciles routine process state.',
+    },
+    {
+        id: 'tmux-reap',
+        title: 'Tmux reap',
+        description: 'Reaps dead managed tmux sessions and their orphaned helper processes.',
+    },
+    {
+        id: 'browser-task-reap',
+        title: 'Browser task reap',
+        description: 'Closes abandoned browser-task tabs whose owner exited or idle lease expired.',
+    },
+    {
+        id: 'session-state',
+        title: 'Live session state',
+        description: 'Publishes this host\'s active session metadata for sessions watch and fleet consumers.',
+    },
     {
         id: 'session-index',
         title: 'Session-index warm',

package/dist/lib/devices/harness-inventory.js

@@ -15,7 +15,7 @@
  */
 import chalk from 'chalk';
 import { ALL_AGENT_IDS, accountDisplayLabel, getAccountInfo, } from '../agents.js';
-import { deriveUsageStatusFromSnapshot, getUsageInfoByIdentity, getUsageLookupKey, } from '../accounting/usage.js';
+import { deriveUsageStatusFromSnapshot, getUsageInfoByIdentity, getUsageLookupKey, usageErrorForDisplay, } from '../accounting/usage.js';
 import { getVersionHomePath, listInstalledVersions } from '../installations/store.js';
 import { readMeta } from '../state.js';
 import { listNativeAccounts } from '../account-registry.js';
@@ -123,7 +123,10 @@ export async function collectLocalHarnessInventory(opts) {
         const key = getUsageLookupKey(info);
         const usage = key ? usageByKey.get(key) : undefined;
         const snapshot = usage?.snapshot ?? null;
-        const quota = summarizeQuota(snapshot, usage?.error ?? null, info?.usageStatus ?? null);
+        // Normalize the internal 'stale' not-collected sentinel out before it reaches
+        // the JSON `quota.unavailableReason` — same leak PHNX-3348 fixed for
+        // `agents view --json`, here for `agents devices harnesses/accounts --json`.
+        const quota = summarizeQuota(snapshot, usageErrorForDisplay(usage?.error), info?.usageStatus ?? null);
         const signedIn = !!info?.signedIn;
         const { ready, reason } = computeReady(signedIn, quota);
         const display = info ? accountDisplayLabel(info) || null : null;

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

@@ -13,6 +13,8 @@
  */
 import { type MonitorConfig, type MonitorEvent } from './config.js';
 import { type Observation } from './sources/index.js';
+/** How often the engine wakes to check which monitors are due. */
+export declare const MONITOR_ENGINE_TICK_MS = 5000;
 /** Poll-model source types the engine actually evaluates on a cadence; ws/webhook are push-only and inert here. */
 export declare const POLL_SOURCE_TYPES: Set<string>;
 /**
@@ -58,7 +60,9 @@ export declare class MonitorEngine {
     private ticking;
     constructor(logFn?: LogFn);
     /** Load owned+enabled monitors and start the tick loop. */
-    start(): void;
+    start(options?: {
+        externalScheduler?: boolean;
+    }): void;
     /** Reload monitor configs (SIGHUP). */
     reload(): void;
     /** Stop the tick loop. */

package/dist/lib/monitors/engine.js

@@ -18,7 +18,7 @@ import { dispatchAction, injectEvent } from './dispatch.js';
 import { sendToOwner } from '../notify.js';
 import { readRunMeta } from '../scheduling/routines.js';
 /** How often the engine wakes to check which monitors are due. */
-const TICK_MS = 5_000;
+export const MONITOR_ENGINE_TICK_MS = 5_000;
 /** Default evaluation cadence for sources that carry no explicit interval. */
 const DEFAULT_INTERVAL_MS = 60_000;
 /**
@@ -126,10 +126,12 @@ export class MonitorEngine {
         this.logFn = logFn;
     }
     /** Load owned+enabled monitors and start the tick loop. */
-    start() {
+    start(options = {}) {
         this.loadAll();
         this.logFn('INFO', `Monitor engine started (${this.monitors.length} monitor(s) on this device)`);
-        this.timer = setInterval(() => void this.tick(), TICK_MS);
+        if (!options.externalScheduler) {
+            this.timer = setInterval(() => void this.tick(), MONITOR_ENGINE_TICK_MS);
+        }
     }
     /** Reload monitor configs (SIGHUP). */
     reload() {

package/dist/lib/overdue.js

@@ -13,48 +13,18 @@
  */
 import * as fs from 'fs';
 import { Cron } from 'croner';
-import { listJobs, getLatestRun, resolveJobFilePath, isPastEndAt, isOneShotRoutine, jobRunsOnThisDevice } from './scheduling/routines.js';
+import { alignedSlotForFire, listJobs, getLatestRun, resolveJobFilePath, isPastEndAt, isOneShotRoutine, jobRunsOnThisDevice } from './scheduling/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 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. */
+/** Compute the most recent fire of `pattern` at or before `now`. Delegates to
+ *  {@link alignedSlotForFire} so overdue detection (`missedRunId`) and the live
+ *  forward-timer dispatch (`slotRunId`) key on the SAME occurrence identity — a
+ *  missed fire and its live twin for one UTC slot then collide by construction
+ *  (SING-15). */
 function previousExpectedFire(cron, now) {
-    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 null;
+    return alignedSlotForFire(cron, now);
 }
 /**
  * When a routine started existing, and therefore the earliest fire it can

package/dist/lib/scheduler.d.ts

@@ -5,13 +5,32 @@
  * process creates a single JobScheduler instance that loads enabled jobs
  * on startup and reloads them on SIGHUP.
  */
+import { Cron } from 'croner';
 import type { JobConfig } from './scheduling/routines.js';
 /** How a fire was triggered, carrying the scheduler's intended UTC slot time. */
 export interface TriggerContext {
-    /** The cron slot this callback fires for (croner `currentRun()`), for the
-     *  single-fire claim keyed on (routine, scheduledFor). */
+    /** The ALIGNED cron slot this callback fires for, for the single-fire claim
+     *  keyed on (routine, scheduledFor). Derived by {@link fireSlot} — NOT croner's
+     *  raw `currentRun()`, which carries wall-clock jitter. */
     scheduledFor?: Date;
 }
+/**
+ * The aligned occurrence boundary a fire callback belongs to — the value the
+ * single-fire `(routine, scheduledFor)` claim keys on.
+ *
+ * croner's `currentRun()` inside a fire callback is the JITTERED wall-clock
+ * trigger instant (it carries milliseconds — verified against croner 10.x), not
+ * the aligned schedule boundary. Keying `slotRunId` on it directly minted a
+ * distinct run id per delivery, so two callbacks for one occurrence each claimed
+ * a different run dir and both launched, and a live fire never collided with its
+ * catch-up twin (`missedRunId`, which keys on the aligned boundary). Flooring the
+ * fire to its schedule boundary via {@link alignedSlotForFire} makes the claim a
+ * structural claim on the occurrence identity (SING-15). Always returns a
+ * concrete Date — `currentRun()` falls back to now, and an unresolvable boundary
+ * falls back to the fire instant — so the forward path never dispatches without a
+ * durable slot key.
+ */
+export declare function fireSlot(cron: Cron): Date;
 /** In-memory cron scheduler that triggers a callback when jobs fire. */
 export declare class JobScheduler {
     private jobs;

package/dist/lib/scheduler.js

@@ -6,7 +6,27 @@
  * on startup and reloads them on SIGHUP.
  */
 import { Cron } from 'croner';
-import { listJobs, deleteJob, isPastEndAt, isPastOneShotRoutine, isOneShotRoutine, setJobEnabled, shouldPurgeCompletedOneShotRoutine, jobRunsOnThisDevice, hasAmbiguousDevicePin, routineOwnerDevice, } from './scheduling/routines.js';
+import { alignedSlotForFire, listJobs, deleteJob, isPastEndAt, isPastOneShotRoutine, isOneShotRoutine, setJobEnabled, shouldPurgeCompletedOneShotRoutine, jobRunsOnThisDevice, hasAmbiguousDevicePin, routineOwnerDevice, } from './scheduling/routines.js';
+/**
+ * The aligned occurrence boundary a fire callback belongs to — the value the
+ * single-fire `(routine, scheduledFor)` claim keys on.
+ *
+ * croner's `currentRun()` inside a fire callback is the JITTERED wall-clock
+ * trigger instant (it carries milliseconds — verified against croner 10.x), not
+ * the aligned schedule boundary. Keying `slotRunId` on it directly minted a
+ * distinct run id per delivery, so two callbacks for one occurrence each claimed
+ * a different run dir and both launched, and a live fire never collided with its
+ * catch-up twin (`missedRunId`, which keys on the aligned boundary). Flooring the
+ * fire to its schedule boundary via {@link alignedSlotForFire} makes the claim a
+ * structural claim on the occurrence identity (SING-15). Always returns a
+ * concrete Date — `currentRun()` falls back to now, and an unresolvable boundary
+ * falls back to the fire instant — so the forward path never dispatches without a
+ * durable slot key.
+ */
+export function fireSlot(cron) {
+    const fire = cron.currentRun() ?? new Date();
+    return alignedSlotForFire(cron, fire) ?? fire;
+}
 /** In-memory cron scheduler that triggers a callback when jobs fire. */
 export class JobScheduler {
     jobs = new Map();
@@ -75,10 +95,13 @@ export class JobScheduler {
                 return;
             }
             try {
-                // croner hands the callback its own Cron instance; `currentRun()` is the
-                // UTC time THIS invocation was scheduled for — the single-fire slot key.
-                // A duplicate delivery for the same slot resolves to one run downstream.
-                await this.onTrigger(config, { scheduledFor: self.currentRun() ?? undefined });
+                // scheduledFor is the ALIGNED occurrence boundary (fireSlot), not croner's
+                // jittered currentRun(): the single-fire claim keys on (routine,
+                // scheduledFor), so the key must be the occurrence identity or a live fire
+                // and its catch-up twin (missedRunId) won't collide and two deliveries of
+                // one slot each mint a distinct id. fireSlot always returns a Date, so the
+                // forward path always carries a durable claim (SING-15).
+                await this.onTrigger(config, { scheduledFor: fireSlot(self) });
             }
             catch (err) {
                 console.error(`Job '${config.name}' failed:`, err.message);