@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/budget/live-team.js

@@ -1,38 +1,7 @@
-/**
- * Live budget kill-switch for `agents teams` supervisor (issue #399).
- *
- * Follow-up to #346, which wired `makeLiveSpendWatcher` into local `agents run`
- * only. Teams spawns each teammate as its own `agents run --headless --json`
- * process, so per-teammate `per_run` caps already fire from those child
- * watchers. What was still missing was aggregate cross-teammate enforcement
- * (`per_project` / `per_day` / `per_agent` combined), because the ledger only
- * gets written on child close — a long-running teammate would blow the shared
- * cap without any single child watcher noticing.
- *
- * This module reuses `makeLiveSpendWatcher` verbatim: on each supervisor wave
- * we tail every running teammate's stdout.log through `extractUsageEvents`
- * (the same primitive the local run path uses in src/lib/exec.ts), feed the
- * usage events into ONE shared watcher, and expose `breached()` so the
- * supervisor can call `stopByTask` to terminate the whole team.
- *
- * Dormant (returns null) when no caps are configured — same zero-cost contract
- * as the local watcher.
- */
 import * as fs from 'fs';
 import { capsFromConfig, extractUsageEvents, makeLiveSpendWatcher, } from './enforce.js';
 import { resolveBudgetConfig, hasAnyCap } from './config.js';
 import { loadLedger, localDay, spendForDay, spendForProject } from './ledger.js';
-/**
- * Build a team-scoped budget watcher for the given team. Returns null when the
- * effective budget config has no caps — matching the local watcher's dormant
- * contract so callers pay nothing when the feature is off.
- *
- * The watcher is seeded with prior-day and prior-project spend from the ledger
- * so a partway-through day counts today's earlier runs against `per_day`.
- * Each `poll()` reads new bytes from every running teammate's stdout.log and
- * feeds parsed usage events into the shared watcher — `onBreach` fires exactly
- * once, mirroring `makeLiveSpendWatcher`.
- */
 export function createTeamBudgetWatcher(args) {
     const cfg = resolveBudgetConfig(args.cwd);
     if (!hasAnyCap(cfg))
@@ -59,9 +28,6 @@ export function createTeamBudgetWatcher(args) {
                 return;
             const teammates = await args.manager.listByTask(args.team);
             for (const agent of teammates) {
-                // Only tap running local teammates: PENDING has no output yet, cloud
-                // teammates emit through a different channel (their own SSE stream),
-                // and terminal states produce no new bytes.
                 if (agent.status !== 'running')
                     continue;
                 if (agent.cloudProvider)
@@ -72,7 +38,7 @@ export function createTeamBudgetWatcher(args) {
                     stat = fs.statSync(stdoutPath);
                 }
                 catch {
-                    continue; // File not yet created — nothing to read.
+                    continue;
                 }
                 const cursor = cursors.get(agent.agentId) ?? { offset: 0, pending: '' };
                 if (stat.size <= cursor.offset) {

package/dist/lib/budget/preflight.d.ts

@@ -1,36 +1,12 @@
-/**
- * Pre-flight cost estimate + gate (issue #346).
- *
- * Before a run spawns we estimate its cost and decide whether to allow it. The
- * estimate's token basis comes from recent ledger averages for the same agent
- * (the most accurate signal we have), falling back to a prompt-character
- * heuristic when there's no history. Cost is computed via the canonical pricing
- * module — never reimplemented here.
- *
- * `enforcePreflight` is the decision: with `on_exceed: block`, if launching
- * this run would push any cap (per_run / per_day / per_agent / per_project)
- * over the line, it denies. With `on_exceed: warn` it always allows but reports
- * the projected overrun.
- */
 import type { BudgetConfig } from '../types.js';
 import type { SpendEntry } from './ledger.js';
-/** A pre-flight cost estimate for one run. */
 interface RunEstimate {
-    /** Estimated USD for this run. 0 when the model is unpriced. */
     estUsd: number;
-    /** How the token count was derived. */
     basis: 'ledger-average' | 'prompt-heuristic' | 'none';
-    /** True when the model resolved to a priced entry. */
     priced: boolean;
     estInputTokens: number;
     estOutputTokens: number;
 }
-/**
- * Estimate the cost of a run. When the ledger has prior runs for this agent we
- * use their average input/output tokens; otherwise we fall back to a
- * prompt-character heuristic. `recentAvgTokens` lets callers inject a
- * precomputed average (e.g. from a scoped ledger) for testability.
- */
 export declare function estimateRunCost(args: {
     agent: string;
     model: string;
@@ -42,60 +18,33 @@ export declare function estimateRunCost(args: {
     };
     ledger?: SpendEntry[];
 }): RunEstimate;
-/** Average input/output tokens per RUN for an agent, from the ledger. Null when no history. */
 export declare function ledgerAverageTokens(agent: string, ledger: SpendEntry[]): {
     input: number;
     output: number;
 } | null;
-/** Decision returned by the pre-flight gate. */
 interface PreflightDecision {
-    /** Whether the run may proceed. */
     allow: boolean;
-    /** Whether the caller must interactively confirm (estimate >= require_confirm_over). */
     needsConfirm: boolean;
-    /** Human reason when blocked or confirming. */
     reason?: string;
-    /** Which cap blocked, if any. */
     blockedCap?: 'per_run' | 'per_day' | 'per_agent' | 'per_project';
-    /** Projected day spend if this run lands at its estimate. */
     projectedDaySpend: number;
-    /** Projected project spend if this run lands at its estimate. */
     projectedProjectSpend: number;
 }
-/** Current spend snapshot the gate compares the estimate against. */
 export interface LedgerState {
-    /** Agent this snapshot is for (used to pick the matching per_agent cap). */
     agent: string;
     daySpend: number;
     projectSpend: number;
     agentDaySpend: number;
 }
-/** Read the ledger snapshot the gate needs for `agent` / `project` / today. */
 export declare function ledgerStateFor(agent: string, project: string, ledger?: SpendEntry[]): LedgerState;
-/**
- * The pre-flight gate. Projects this run's estimate on top of current spend and
- * decides allow/deny. `on_exceed: warn` never blocks (allow:true) but still
- * reports the projected overrun via `reason`. A hard block sets allow:false —
- * `--yes` MUST NOT override it (the caller enforces that; this function only
- * reports the truth).
- */
 export declare function enforcePreflight(cfg: BudgetConfig, state: LedgerState, est: RunEstimate): PreflightDecision;
-/** Result of the high-level run gate consumed by `agents run` / teams / cloud. */
 interface PreflightGateResult {
-    /** True when no caps are configured — budget feature dormant, nothing to do. */
     dormant: boolean;
     cfg: BudgetConfig;
     estimate: RunEstimate;
     decision: PreflightDecision;
     banner: string;
 }
-/**
- * High-level pre-flight gate: resolve the effective budget for `cwd`, estimate
- * the run, and evaluate every cap. Returns `dormant:true` (and skips all work)
- * when no caps are set, so the gate is zero-cost for users who never configure
- * a budget. The CLI layer decides how to act on `decision` (print banner,
- * confirm, or block + exit non-zero).
- */
 export declare function runPreflightGate(args: {
     agent: string;
     model: string;

package/dist/lib/budget/preflight.js

@@ -1,21 +1,8 @@
 import { estimateCost, formatUsd } from '../pricing/index.js';
 import { loadLedger, spendForDay, spendForAgentDay, spendForProject, localDay } from './ledger.js';
 import { resolveBudgetConfig, hasAnyCap } from './config.js';
-/** Roughly 4 characters per token — the standard coarse heuristic for English text. */
 const CHARS_PER_TOKEN = 4;
-/**
- * Output is typically a multiple of the visible prompt for an agentic run
- * (tool calls, file reads, reasoning). 6x is a deliberately conservative
- * lower bound so the estimate doesn't wildly under-report and wave through a
- * run that then blows the cap on its first turn.
- */
 const HEURISTIC_OUTPUT_MULTIPLIER = 6;
-/**
- * Estimate the cost of a run. When the ledger has prior runs for this agent we
- * use their average input/output tokens; otherwise we fall back to a
- * prompt-character heuristic. `recentAvgTokens` lets callers inject a
- * precomputed average (e.g. from a scoped ledger) for testability.
- */
 export function estimateRunCost(args) {
     const ledger = args.ledger ?? loadLedger();
     let estInputTokens = 0;
@@ -44,7 +31,6 @@ export function estimateRunCost(args) {
         estOutputTokens,
     };
 }
-/** Average input/output tokens per RUN for an agent, from the ledger. Null when no history. */
 export function ledgerAverageTokens(agent, ledger) {
     const runs = new Map();
     for (const e of ledger) {
@@ -65,7 +51,6 @@ export function ledgerAverageTokens(agent, ledger) {
     }
     return { input: Math.round(input / runs.size), output: Math.round(output / runs.size) };
 }
-/** Read the ledger snapshot the gate needs for `agent` / `project` / today. */
 export function ledgerStateFor(agent, project, ledger) {
     const entries = ledger ?? loadLedger();
     const today = localDay();
@@ -76,13 +61,6 @@ export function ledgerStateFor(agent, project, ledger) {
         agentDaySpend: spendForAgentDay(agent, today, entries),
     };
 }
-/**
- * The pre-flight gate. Projects this run's estimate on top of current spend and
- * decides allow/deny. `on_exceed: warn` never blocks (allow:true) but still
- * reports the projected overrun via `reason`. A hard block sets allow:false —
- * `--yes` MUST NOT override it (the caller enforces that; this function only
- * reports the truth).
- */
 export function enforcePreflight(cfg, state, est) {
     const projectedDaySpend = state.daySpend + est.estUsd;
     const projectedProjectSpend = state.projectSpend + est.estUsd;
@@ -114,13 +92,7 @@ export function enforcePreflight(cfg, state, est) {
             reason: `projected agent day spend ${formatUsd(projectedAgentDaySpend)} exceeds per_agent cap ${formatUsd(agentCap)}`,
         });
     }
-    // require_confirm_over only governs interactive confirm, not a hard block.
     let needsConfirm = cfg.require_confirm_over !== undefined && est.estUsd >= cfg.require_confirm_over;
-    // Unpriced model + active caps: the estimate is $0 because we have no price
-    // for this model, so NONE of the per_run/per_day caps above can ever trip and
-    // we'd silently wave the run through. Never $0-wave-through (#346): when caps
-    // are set but the model is unpriced, require confirmation so the user is told
-    // the cap cannot be enforced for this model rather than getting a false pass.
     if (!est.priced && hasAnyCap(cfg) && breaches.length === 0) {
         needsConfirm = true;
         return {
@@ -152,7 +124,6 @@ export function enforcePreflight(cfg, state, est) {
         projectedProjectSpend,
     };
 }
-/** Build a one-line human estimate banner for `agents run` preamble. */
 function formatEstimateBanner(agent, model, est) {
     const cost = est.priced ? formatUsd(est.estUsd) : 'unpriced';
     const basisLabel = est.basis === 'ledger-average'
@@ -162,13 +133,6 @@ function formatEstimateBanner(agent, model, est) {
             : 'no basis';
     return `[budget] est. ${cost} for this ${agent} run (${model}, ${basisLabel})`;
 }
-/**
- * High-level pre-flight gate: resolve the effective budget for `cwd`, estimate
- * the run, and evaluate every cap. Returns `dormant:true` (and skips all work)
- * when no caps are set, so the gate is zero-cost for users who never configure
- * a budget. The CLI layer decides how to act on `decision` (print banner,
- * confirm, or block + exit non-zero).
- */
 export function runPreflightGate(args) {
     const cfg = resolveBudgetConfig(args.cwd);
     const ledger = args.ledger ?? loadLedger();

package/dist/lib/byok-usage.d.ts

@@ -1,12 +1,3 @@
-/**
- * BYOK (Bring Your Own Key) budget fetcher.
- *
- * For custom harnesses that use a provider's API key stored in the keychain
- * (e.g. OpenRouter), this module fetches the account's credit/usage data so
- * `agents view` can show a budget bar alongside the harness detail row — the
- * same bar style the native usage system uses, just sourced from the provider
- * API rather than the CLI's own usage tracking.
- */
 import type { Profile } from './profiles.js';
 export interface ByokBudgetInfo {
     limitUsd: number | null;
@@ -25,20 +16,9 @@ export declare function setByokCachePathForTest(value: string | null): string |
 export declare function resetByokCacheForTest(): void;
 export declare function hasByokProvider(provider: string): boolean;
 export declare function renderByokBar(result: ByokUsageResult): string;
-/**
- * Fetch the BYOK budget for a harness.
- *
- * Returns `null` when the harness has no registered BYOK provider or no auth.
- * Returns a `ByokUsageResult` with `budget: null` when the token is absent
- * from the keychain (so the caller can skip rendering a bar without error).
- *
- * Ordinary reads are cache-only. Explicit refreshes are serialized per provider
- * credential across every agents-cli process on the device.
- */
 export declare function getByokUsageForHarness(profile: Profile, opts?: {
     forceRefresh?: boolean;
 }): Promise<ByokUsageResult | null>;
-/** Refresh each configured BYOK credential when its daemon-owned snapshot is due. */
 export declare function refreshDueByokUsage(profiles: Profile[], now?: number): Promise<{
     refreshed: number;
     skipped: number;

package/dist/lib/byok-usage.js

@@ -1,12 +1,3 @@
-/**
- * BYOK (Bring Your Own Key) budget fetcher.
- *
- * For custom harnesses that use a provider's API key stored in the keychain
- * (e.g. OpenRouter), this module fetches the account's credit/usage data so
- * `agents view` can show a budget bar alongside the harness detail row — the
- * same bar style the native usage system uses, just sourced from the provider
- * API rather than the CLI's own usage tracking.
- */
 import { getKeychainTokenSync, hasKeychainTokenSync } from './secrets-client.js';
 import { renderBar, getUsageColor } from './accounting/usage.js';
 import * as fs from 'node:fs';
@@ -17,7 +8,6 @@ import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic
 import { withRefreshLease } from './refresh-coordinator.js';
 import { findAccount, resolveCredentialAccount } from './account-registry.js';
 import { getAccountProvider } from './account-provider-registry.js';
-// ─── Injectable fetch seam (tests only) ──────────────────────────────────────
 let _fetch = globalThis.fetch;
 export function setByokFetchForTest(fn) {
     _fetch = fn;
@@ -55,7 +45,7 @@ export function resetByokCacheForTest() {
     try {
         fs.unlinkSync(cachePath());
     }
-    catch { /* absent */ }
+    catch { }
 }
 function resolveByokToken(profile) {
     if (profile.account) {
@@ -144,7 +134,6 @@ const BYOK_REGISTRY = {
 export function hasByokProvider(provider) {
     return Object.prototype.hasOwnProperty.call(BYOK_REGISTRY, provider);
 }
-// ─── Bar renderer ─────────────────────────────────────────────────────────────
 export function renderByokBar(result) {
     if (!result.budget)
         return '';
@@ -161,17 +150,6 @@ export function renderByokBar(result) {
     const limit = `$${budget.limitUsd.toFixed(2)}`;
     return `$: ${bar} ${color(`${Math.round(pct)}%`)} (${remaining} left of ${limit})`;
 }
-// ─── Public API ───────────────────────────────────────────────────────────────
-/**
- * Fetch the BYOK budget for a harness.
- *
- * Returns `null` when the harness has no registered BYOK provider or no auth.
- * Returns a `ByokUsageResult` with `budget: null` when the token is absent
- * from the keychain (so the caller can skip rendering a bar without error).
- *
- * Ordinary reads are cache-only. Explicit refreshes are serialized per provider
- * credential across every agents-cli process on the device.
- */
 export async function getByokUsageForHarness(profile, opts) {
     if (!profile.provider || !hasByokProvider(profile.provider) || (!profile.auth && !profile.account))
         return null;
@@ -195,7 +173,6 @@ export async function getByokUsageForHarness(profile, opts) {
         },
     }).then((entry) => entry.result);
 }
-/** Refresh each configured BYOK credential when its daemon-owned snapshot is due. */
 export async function refreshDueByokUsage(profiles, now = Date.now()) {
     const due = new Map();
     for (const profile of profiles) {

package/dist/lib/capabilities.d.ts

@@ -1,29 +1,5 @@
-/**
- * Capability gate for agent features.
- *
- * Every install path that touches an agent-version (hooks, plugins, MCP,
- * skills, commands) calls `supports(agent, cap, version?)` before writing to
- * the version's config dir. When the capability is unsupported or the version
- * is below `since`, the install path skips the write and surfaces a clear
- * reason instead of silently corrupting an older binary's settings file.
- */
 import type { AgentId, CapabilityName, CapabilityResult } from './types.js';
-/**
- * True when the agent supports the capability on at least some version.
- * Useful for filtering UI lists; does not check installed version.
- */
 export declare function isCapable(agent: AgentId, cap: CapabilityName): boolean;
-/**
- * Check whether the given agent (optionally pinned to a specific installed
- * version) supports `cap`. Pass `version` whenever you know it -- omitting it
- * only checks the agent-level flag, which is fine for "is this agent ever
- * capable" filters but NOT for install-time gating.
- */
 export declare function supports(agent: AgentId, cap: CapabilityName, version?: string): CapabilityResult;
-/**
- * Human-readable explanation for skipping an install. Stable shape so callers
- * can either log it or push it onto an `errors[]` collector.
- */
 export declare function explainSkip(agent: AgentId, cap: CapabilityName, result: CapabilityResult, version?: string): string;
-/** All agents whose `capabilities[cap]` is anything other than `false`. */
 export declare function capableAgents(cap: CapabilityName): AgentId[];

package/dist/lib/capabilities.js

@@ -1,42 +1,18 @@
-/**
- * Capability gate for agent features.
- *
- * Every install path that touches an agent-version (hooks, plugins, MCP,
- * skills, commands) calls `supports(agent, cap, version?)` before writing to
- * the version's config dir. When the capability is unsupported or the version
- * is below `since`, the install path skips the write and surfaces a clear
- * reason instead of silently corrupting an older binary's settings file.
- */
 import { AGENTS, MANAGED_AGENT_IDS } from './agents.js';
-// agent-spec/primitives is a leaf module — importing it creates no cycle, and it
-// is the only compareVersions that honors OpenClaw's `-N` rebuild suffix.
 import { compareVersions } from './agent-spec/primitives.js';
 import { installedReleaseFor } from './installations/store.js';
 function getCapability(agent, cap) {
-    // Guard against unknown agent ids (e.g. a caller passing "claude@2.1.168"
-    // instead of "claude"). Without this, AGENTS[agent] is undefined and the
-    // property access throws an opaque TypeError instead of reporting false.
     const def = AGENTS[agent];
     if (!def)
         return false;
     return def.capabilities[cap];
 }
-/**
- * True when the agent supports the capability on at least some version.
- * Useful for filtering UI lists; does not check installed version.
- */
 export function isCapable(agent, cap) {
     if (AGENTS[agent]?.deprecated?.hard)
         return false;
     const c = getCapability(agent, cap);
     return c !== false;
 }
-/**
- * Check whether the given agent (optionally pinned to a specific installed
- * version) supports `cap`. Pass `version` whenever you know it -- omitting it
- * only checks the agent-level flag, which is fine for "is this agent ever
- * capable" filters but NOT for install-time gating.
- */
 export function supports(agent, cap, version) {
     if (AGENTS[agent]?.deprecated?.hard)
         return { ok: false, reason: 'unsupported' };
@@ -58,10 +34,6 @@ export function supports(agent, cap, version) {
     }
     return { ok: true };
 }
-/**
- * Human-readable explanation for skipping an install. Stable shape so callers
- * can either log it or push it onto an `errors[]` collector.
- */
 export function explainSkip(agent, cap, result, version) {
     if (result.ok)
         return '';
@@ -70,7 +42,6 @@ export function explainSkip(agent, cap, result, version) {
         return `${tag}: ${cap} not supported`;
     return `${tag}: ${cap} requires ${result.need}`;
 }
-/** All agents whose `capabilities[cap]` is anything other than `false`. */
 export function capableAgents(cap) {
     return MANAGED_AGENT_IDS.filter((id) => isCapable(id, cap));
 }

package/dist/lib/catchup.d.ts

@@ -1,106 +1,19 @@
-/**
- * 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 './scheduling/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;
 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[]>;
 export {};

package/dist/lib/catchup.js

@@ -1,88 +1,20 @@
-/**
- * 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 './scheduling/routines.js';
 import { detectOverdueJobs } from './overdue.js';
 import { executeJobDetached } from './daemon/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
+        fs.mkdirSync(runDir);
     }
     catch (err) {
         if (err.code === 'EEXIST')
@@ -107,13 +39,6 @@ export function claimMissedFire(job, expectedAt) {
     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 = [];
@@ -128,8 +53,6 @@ export async function runCatchup(opts = {}) {
             });
             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;
@@ -139,9 +62,6 @@ export async function runCatchup(opts = {}) {
             continue;
         }
         try {
-            // No `scheduledFor` here on purpose: the missed slot is already claimed by
-            // `claimMissedFire` above (its atomic mkdir IS the catch-up single-fire), so
-            // the late run gets a fresh id rather than colliding with the missed record.
             const meta = await executeJobDetached(config, undefined, { kind: 'catchup' });
             outcomes.push({
                 name: entry.name,