patchwork-os 1.2.0-beta.2.canary.682 → 1.2.0-beta.2.canary.686

package/dist/recipes/cronClaim.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Cross-process claim on a scheduled fire (#1458).
+ *
+ * ## The bug
+ *
+ * `RecipeScheduler` guards double-fire with an in-memory `Set`, and its own
+ * comment states the assumption: *"The guard is scheduler-scoped (one process),
+ * which is enough because that's the only place a cron tick can originate."*
+ *
+ * That assumption does not hold. The recipe store is global — `patchworkPath
+ * ("recipes")` — so **every** running bridge schedules **every** enabled cron
+ * recipe, and an in-process `Set` cannot see a sibling process. N bridges ⇒ N
+ * fires. Observed live on 2026-08-19: one hourly recipe ran twice at the same
+ * instant from two pids, and again the next hour.
+ *
+ * Two bridges is a supported, documented shape, so "run one bridge" is not the
+ * answer.
+ *
+ * ## The claim is on the TICK, not on the recipe
+ *
+ * This is the whole design, and it is what keeps manual runs working.
+ *
+ * A tick is an externally generated event — the clock — that N processes each
+ * observe independently, and whose correct execution count is one. A manual
+ * `patchwork recipe run X` is an operator-generated event that exists exactly
+ * once already. Deduping the second against the first would be a category
+ * error, and the scheduler's existing comment says manual runs deliberately
+ * bypass the guard.
+ *
+ * So the key is `(recipeName, slotEpochMs)` and the claim is taken by the cron
+ * path and by nothing else. Manual runs, HTTP `POST /recipes/:name/run`,
+ * webhooks and the file-watch/git-hook paths neither read nor write it. That is
+ * structural, not a carve-out in the key.
+ *
+ * ## Why the slot must be threaded in, never re-read from the clock
+ *
+ * `fire()` runs an event-loop hop after the cron matcher matched. Re-deriving
+ * the slot from `Date.now()` there would let bridge A compute `:00` and bridge
+ * B `:01` for the same tick — two keys, and the duplicate is back, in a form
+ * that reproduces only when the hop straddles a second boundary.
+ *
+ * node-cron hands the callback the matched instant with milliseconds already
+ * zeroed, identically in every process running the same expression. That value
+ * is threaded in as `slotEpochMs`, and floored again here so that an upstream
+ * change reintroducing milliseconds cannot silently split the key.
+ *
+ * **No slot ⇒ no claim.** That covers the `@every` interval path (a bare
+ * `setInterval`, phase-anchored to each process's own start, with no canonical
+ * slot to agree on) and the `fireForTest` hook. Both then behave exactly as
+ * they do today. `@every` is deliberately out of scope here rather than
+ * quantised: zero installed recipes use it, and the quantised version has a
+ * bias worth deciding on its own evidence. `RecipeScheduler` logs the exclusion
+ * once per recipe, because a scheduling gap nobody is told about is how
+ * `audit-in-flight` spent its whole life passing.
+ *
+ * ## The claim is a tombstone, not a lock
+ *
+ * It is never released. If it were released on completion, a peer whose tick is
+ * delayed past the first bridge's completion — a 40 ms recipe and ticks 200 ms
+ * apart is entirely reachable — would find no claim and fire. That reintroduces
+ * the bug in a narrower window, which is worse, because it stops reproducing on
+ * demand.
+ *
+ * Consequence, stated as a property rather than left as an oversight: this
+ * guarantees **at-most-once per slot per `PATCHWORK_HOME`, not exactly-once.**
+ * A process that dies between claiming and dispatching consumes the slot and no
+ * peer picks it up. Exactly-once needs a claim a peer can safely steal, which
+ * needs liveness plus a rule for re-running a run that got most of the way
+ * through its side effects — that is crash recovery, a different feature, and
+ * its failure mode is a duplicate of a run that DID have external effects.
+ *
+ * ## Failure is OPEN, and never silent
+ *
+ * `EEXIST` is not failure — it is the mechanism working, and it skips.
+ * "Failure" means the store is unusable: `EACCES`, `EROFS`, `ENOSPC`, or an
+ * unexpected throw. On those the tick FIRES, and the caller is told why so it
+ * can log it and stamp the run.
+ *
+ * The reasoning, since this is the opposite of ADR-0016's fail-closed instinct:
+ * the conditions that break this store are machine-level, so they break it for
+ * every bridge at once, and failing closed would then yield ZERO executions of
+ * every scheduled recipe rather than one — silently, for as long as it lasts.
+ * Fail-open's worst case is exactly the bug we have today, which is known and
+ * bounded. And this store shares a disk with the run log, the effect ledger and
+ * the decision record: if `~/.patchwork` is unwritable the recipe is going to
+ * run ungoverned or fail on its own, so stopping here selects a stop condition
+ * on a *proxy* for "the disk is broken" instead of reporting the disk.
+ *
+ * ADR-0016 fails closed because its object is a tool call, whose safe default is
+ * "no". This decides whether a clock tick has already been consumed by a peer,
+ * and with no answer available the safe default is the status quo ante. That is
+ * the same reasoning that makes the identity roster fail SOFT.
+ *
+ * `PATCHWORK_CRON_CLAIM_REQUIRED=1` flips it to fail-closed for deployments
+ * whose scheduled recipes send email or post publicly, where the operator knows
+ * the trade and we do not.
+ */
+/** Directory under PATCHWORK_HOME holding day-sharded claim files. */
+export declare const CRON_CLAIM_DIRNAME = "cron-claims";
+/**
+ * How long claim day-directories are kept.
+ *
+ * This does not need to cover a schedule's period. It only needs to outlive the
+ * window in which a duplicate of the SAME slot can arrive, which is bounded by
+ * seconds. 48 h is five orders of magnitude of margin; the sweep exists solely
+ * to bound growth.
+ */
+export declare const CLAIM_RETENTION_MS: number;
+export type ClaimOutcome = 
+/** This process owns the slot. Fire. */
+{
+    kind: "claimed";
+}
+/** A peer owns the slot. Do not fire. */
+ | {
+    kind: "taken";
+}
+/**
+ * The store is unusable. The caller fires anyway (unless the operator set
+ * `PATCHWORK_CRON_CLAIM_REQUIRED`), logs, and stamps the run so a resulting
+ * duplicate is attributable rather than mysterious.
+ */
+ | {
+    kind: "unavailable";
+    reason: string;
+}
+/**
+ * The store is unusable AND the operator asked for fail-closed. Do not fire.
+ * Distinct from `taken` so the log can say which happened — "a peer has it"
+ * and "we could not tell" are different facts about the system.
+ */
+ | {
+    kind: "refused";
+    reason: string;
+};
+/**
+ * Key for one scheduled fire.
+ *
+ * JSON-array encoding rather than `${a}:${b}`, for the reason `deriveScopeKey`
+ * already documents: recipe `a:b` at slot `c` and recipe `a` at slot `b:c` must
+ * not collide. Hex-only, so a recipe name containing `/`, spaces or unicode is
+ * still a safe filename — the human-readable fields live inside the record.
+ *
+ * The schedule expression is deliberately NOT in the key. If a schedule is
+ * edited and two bridges hot-reload at different moments they compute different
+ * slots and both fire regardless; including the expression would not fix that
+ * and would make a same-slot collision less likely to dedupe.
+ */
+export declare function cronClaimKey(recipeName: string, slotEpochMs: number): string;
+export interface ClaimOptions {
+    /** Root override for tests. Defaults to `patchworkPath(CRON_CLAIM_DIRNAME)`. */
+    claimsDir?: string;
+    /**
+     * Fail-closed override. Defaults to reading
+     * `PATCHWORK_CRON_CLAIM_REQUIRED`. Injected so a test can drive both
+     * branches without mutating the environment.
+     */
+    required?: boolean;
+}
+/**
+ * Try to claim `(recipeName, slotEpochMs)` for this process.
+ *
+ * `openSync(path, "wx")` is one atomic syscall that is simultaneously the test
+ * and the set — no lock file, no shared append-only log, no read-modify-write,
+ * and no serialisation between unrelated recipes. `withFileLockSync` was
+ * considered and rejected for exactly those costs, plus a 30 s stale-lock TTL
+ * that would stall every recipe's scheduling if a process died holding it.
+ *
+ * The record body is written for a human to read afterwards and is NEVER read
+ * to make a decision — the kernel already made it at `open`.
+ */
+export declare function claimCronSlot(recipeName: string, slotEpochMs: number, opts?: ClaimOptions): ClaimOutcome;
+/**
+ * Delete claim day-directories older than the retention horizon.
+ *
+ * Best-effort and never throws: this is housekeeping, and a scheduler that
+ * cannot start because it could not tidy up would be a far worse bug than the
+ * disk usage it prevents.
+ *
+ * Returns the number of directories removed so a caller can log it — a sweep
+ * that silently does nothing looks identical to one that has nothing to do.
+ */
+export declare function sweepCronClaims(now?: number, opts?: ClaimOptions): number;

package/dist/recipes/cronClaim.js

@@ -0,0 +1,241 @@
+/**
+ * Cross-process claim on a scheduled fire (#1458).
+ *
+ * ## The bug
+ *
+ * `RecipeScheduler` guards double-fire with an in-memory `Set`, and its own
+ * comment states the assumption: *"The guard is scheduler-scoped (one process),
+ * which is enough because that's the only place a cron tick can originate."*
+ *
+ * That assumption does not hold. The recipe store is global — `patchworkPath
+ * ("recipes")` — so **every** running bridge schedules **every** enabled cron
+ * recipe, and an in-process `Set` cannot see a sibling process. N bridges ⇒ N
+ * fires. Observed live on 2026-08-19: one hourly recipe ran twice at the same
+ * instant from two pids, and again the next hour.
+ *
+ * Two bridges is a supported, documented shape, so "run one bridge" is not the
+ * answer.
+ *
+ * ## The claim is on the TICK, not on the recipe
+ *
+ * This is the whole design, and it is what keeps manual runs working.
+ *
+ * A tick is an externally generated event — the clock — that N processes each
+ * observe independently, and whose correct execution count is one. A manual
+ * `patchwork recipe run X` is an operator-generated event that exists exactly
+ * once already. Deduping the second against the first would be a category
+ * error, and the scheduler's existing comment says manual runs deliberately
+ * bypass the guard.
+ *
+ * So the key is `(recipeName, slotEpochMs)` and the claim is taken by the cron
+ * path and by nothing else. Manual runs, HTTP `POST /recipes/:name/run`,
+ * webhooks and the file-watch/git-hook paths neither read nor write it. That is
+ * structural, not a carve-out in the key.
+ *
+ * ## Why the slot must be threaded in, never re-read from the clock
+ *
+ * `fire()` runs an event-loop hop after the cron matcher matched. Re-deriving
+ * the slot from `Date.now()` there would let bridge A compute `:00` and bridge
+ * B `:01` for the same tick — two keys, and the duplicate is back, in a form
+ * that reproduces only when the hop straddles a second boundary.
+ *
+ * node-cron hands the callback the matched instant with milliseconds already
+ * zeroed, identically in every process running the same expression. That value
+ * is threaded in as `slotEpochMs`, and floored again here so that an upstream
+ * change reintroducing milliseconds cannot silently split the key.
+ *
+ * **No slot ⇒ no claim.** That covers the `@every` interval path (a bare
+ * `setInterval`, phase-anchored to each process's own start, with no canonical
+ * slot to agree on) and the `fireForTest` hook. Both then behave exactly as
+ * they do today. `@every` is deliberately out of scope here rather than
+ * quantised: zero installed recipes use it, and the quantised version has a
+ * bias worth deciding on its own evidence. `RecipeScheduler` logs the exclusion
+ * once per recipe, because a scheduling gap nobody is told about is how
+ * `audit-in-flight` spent its whole life passing.
+ *
+ * ## The claim is a tombstone, not a lock
+ *
+ * It is never released. If it were released on completion, a peer whose tick is
+ * delayed past the first bridge's completion — a 40 ms recipe and ticks 200 ms
+ * apart is entirely reachable — would find no claim and fire. That reintroduces
+ * the bug in a narrower window, which is worse, because it stops reproducing on
+ * demand.
+ *
+ * Consequence, stated as a property rather than left as an oversight: this
+ * guarantees **at-most-once per slot per `PATCHWORK_HOME`, not exactly-once.**
+ * A process that dies between claiming and dispatching consumes the slot and no
+ * peer picks it up. Exactly-once needs a claim a peer can safely steal, which
+ * needs liveness plus a rule for re-running a run that got most of the way
+ * through its side effects — that is crash recovery, a different feature, and
+ * its failure mode is a duplicate of a run that DID have external effects.
+ *
+ * ## Failure is OPEN, and never silent
+ *
+ * `EEXIST` is not failure — it is the mechanism working, and it skips.
+ * "Failure" means the store is unusable: `EACCES`, `EROFS`, `ENOSPC`, or an
+ * unexpected throw. On those the tick FIRES, and the caller is told why so it
+ * can log it and stamp the run.
+ *
+ * The reasoning, since this is the opposite of ADR-0016's fail-closed instinct:
+ * the conditions that break this store are machine-level, so they break it for
+ * every bridge at once, and failing closed would then yield ZERO executions of
+ * every scheduled recipe rather than one — silently, for as long as it lasts.
+ * Fail-open's worst case is exactly the bug we have today, which is known and
+ * bounded. And this store shares a disk with the run log, the effect ledger and
+ * the decision record: if `~/.patchwork` is unwritable the recipe is going to
+ * run ungoverned or fail on its own, so stopping here selects a stop condition
+ * on a *proxy* for "the disk is broken" instead of reporting the disk.
+ *
+ * ADR-0016 fails closed because its object is a tool call, whose safe default is
+ * "no". This decides whether a clock tick has already been consumed by a peer,
+ * and with no answer available the safe default is the status quo ante. That is
+ * the same reasoning that makes the identity roster fail SOFT.
+ *
+ * `PATCHWORK_CRON_CLAIM_REQUIRED=1` flips it to fail-closed for deployments
+ * whose scheduled recipes send email or post publicly, where the operator knows
+ * the trade and we do not.
+ */
+import { createHash } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readdirSync, rmSync, writeSync, } from "node:fs";
+import { join } from "node:path";
+import { patchworkPath } from "../patchworkHome.js";
+/** Directory under PATCHWORK_HOME holding day-sharded claim files. */
+export const CRON_CLAIM_DIRNAME = "cron-claims";
+/**
+ * How long claim day-directories are kept.
+ *
+ * This does not need to cover a schedule's period. It only needs to outlive the
+ * window in which a duplicate of the SAME slot can arrive, which is bounded by
+ * seconds. 48 h is five orders of magnitude of margin; the sweep exists solely
+ * to bound growth.
+ */
+export const CLAIM_RETENTION_MS = 48 * 60 * 60 * 1000;
+/**
+ * Key for one scheduled fire.
+ *
+ * JSON-array encoding rather than `${a}:${b}`, for the reason `deriveScopeKey`
+ * already documents: recipe `a:b` at slot `c` and recipe `a` at slot `b:c` must
+ * not collide. Hex-only, so a recipe name containing `/`, spaces or unicode is
+ * still a safe filename — the human-readable fields live inside the record.
+ *
+ * The schedule expression is deliberately NOT in the key. If a schedule is
+ * edited and two bridges hot-reload at different moments they compute different
+ * slots and both fire regardless; including the expression would not fix that
+ * and would make a same-slot collision less likely to dedupe.
+ */
+export function cronClaimKey(recipeName, slotEpochMs) {
+    return createHash("sha256")
+        .update(JSON.stringify(["cron", recipeName, slotEpochMs]))
+        .digest("hex")
+        .slice(0, 32);
+}
+/** `YYYY-MM-DD` in UTC. Day-sharded so the sweep deletes directories, not files. */
+function dayShard(slotEpochMs) {
+    return new Date(slotEpochMs).toISOString().slice(0, 10);
+}
+function claimsRoot(opts) {
+    return opts.claimsDir ?? patchworkPath(CRON_CLAIM_DIRNAME);
+}
+function failClosed(opts) {
+    if (opts.required !== undefined)
+        return opts.required;
+    const v = process.env.PATCHWORK_CRON_CLAIM_REQUIRED;
+    return v === "1" || v?.toLowerCase() === "true";
+}
+/**
+ * Try to claim `(recipeName, slotEpochMs)` for this process.
+ *
+ * `openSync(path, "wx")` is one atomic syscall that is simultaneously the test
+ * and the set — no lock file, no shared append-only log, no read-modify-write,
+ * and no serialisation between unrelated recipes. `withFileLockSync` was
+ * considered and rejected for exactly those costs, plus a 30 s stale-lock TTL
+ * that would stall every recipe's scheduling if a process died holding it.
+ *
+ * The record body is written for a human to read afterwards and is NEVER read
+ * to make a decision — the kernel already made it at `open`.
+ */
+export function claimCronSlot(recipeName, slotEpochMs, opts = {}) {
+    // Floor again. The caller threads in an already-zeroed value, but a key that
+    // silently splits on stray milliseconds fails in the one way that does not
+    // reproduce, so it is worth one multiplication.
+    const slot = Math.floor(slotEpochMs / 1000) * 1000;
+    const dir = join(claimsRoot(opts), dayShard(slot));
+    const file = join(dir, `${cronClaimKey(recipeName, slot)}.json`);
+    let fd;
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        fd = openSync(file, "wx", 0o600);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EEXIST")
+            return { kind: "taken" };
+        const reason = code ?? (err instanceof Error ? err.message : "unknown");
+        return failClosed(opts)
+            ? { kind: "refused", reason }
+            : { kind: "unavailable", reason };
+    }
+    try {
+        writeSync(fd, `${JSON.stringify({
+            v: 1,
+            recipeName,
+            slotEpochMs: slot,
+            slotIso: new Date(slot).toISOString(),
+            pid: process.pid,
+            claimedAt: Date.now(),
+        })}\n`);
+    }
+    catch {
+        // The claim is the file's EXISTENCE; the body is diagnostics. A failed body
+        // write must not surrender a slot we already own — that would hand it to a
+        // peer and fire twice.
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            /* already closed */
+        }
+    }
+    return { kind: "claimed" };
+}
+/**
+ * Delete claim day-directories older than the retention horizon.
+ *
+ * Best-effort and never throws: this is housekeeping, and a scheduler that
+ * cannot start because it could not tidy up would be a far worse bug than the
+ * disk usage it prevents.
+ *
+ * Returns the number of directories removed so a caller can log it — a sweep
+ * that silently does nothing looks identical to one that has nothing to do.
+ */
+export function sweepCronClaims(now = Date.now(), opts = {}) {
+    const root = claimsRoot(opts);
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return 0; // nothing claimed yet, or unreadable — both are non-events here
+    }
+    let removed = 0;
+    for (const name of entries) {
+        // Parse the shard name rather than stat()-ing it: the directory's own mtime
+        // moves every time a claim lands in it, so a busy day would never age out.
+        const t = Date.parse(`${name}T00:00:00.000Z`);
+        if (!Number.isFinite(t))
+            continue; // not one of ours; leave it alone
+        if (now - t <= CLAIM_RETENTION_MS + 24 * 60 * 60 * 1000)
+            continue;
+        try {
+            rmSync(join(root, name), { recursive: true, force: true });
+            removed++;
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=cronClaim.js.map

package/dist/recipes/cronClaim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cronClaim.js","sourceRoot":"","sources":["../../src/recipes/cronClaim.ts"],"names":[],"mappings":"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"}

package/dist/recipes/scheduler.d.ts

@@ -1,5 +1,6 @@
-import cron from "node-cron";
+import { type ScheduledTask } from "node-cron";
 import type { Logger } from "../logger.js";
+import { type ClaimOptions } from "./cronClaim.js";
 /**
  * RecipeScheduler — runs cron-triggered recipes on a simple interval or
  * standard 5-field cron expression.
@@ -22,7 +23,7 @@ export interface ScheduledRecipe {
     intervalMs: number;
     timer: ReturnType<typeof setInterval>;
     /** Present only for cron5-kind recipes. */
-    cronJob?: cron.ScheduledTask;
+    cronJob?: ScheduledTask;
 }
 export interface SchedulerOptions {
     recipesDir: string;
@@ -47,7 +48,36 @@ export interface SchedulerOptions {
      * this to avoid depending on the dev machine's config.
      */
     timezone?: string;
+    /**
+     * Cron-claim store override (#1458). Tests point it at a temp root; the two
+     * real bridges share the default under PATCHWORK_HOME, which is exactly the
+     * scope of the shared recipe store that causes the double-fire.
+     */
+    claim?: ClaimOptions;
 }
+/**
+ * The instant the cron matcher matched, as a second-aligned epoch value.
+ *
+ * node-cron hands the task callback a context whose `date` is the matched
+ * instant with milliseconds already zeroed, derived from the matcher rather
+ * than from the moment the callback happens to run. Two processes evaluating
+ * the same expression in the same timezone therefore produce the byte-identical
+ * value — which is the only reason a filesystem claim can dedupe them.
+ *
+ * `triggeredAt` on the same context is `new Date()` and must NEVER be used: it
+ * differs per process by exactly the amount that breaks the key.
+ *
+ * Returns `undefined` when there is no usable context, so an older or newer
+ * node-cron that does not pass one degrades to today's behaviour — no slot, no
+ * claim, both bridges fire — rather than throwing inside a timer callback.
+ *
+ * Exported for tests. The alternative is asserting it through a live cron tick,
+ * which means a real timer and a real second boundary in CI — and this repo has
+ * spent enough of its life on timing flakes.
+ */
+export declare function matchedSlotMs(ctx?: {
+    date?: Date;
+}): number | undefined;
 export declare class RecipeScheduler {
     private readonly opts;
     private scheduled;
@@ -66,8 +96,16 @@ export declare class RecipeScheduler {
      * replay; this guard stops cross-attempt double-fire.
      *
      * Manual CLI runs do NOT go through this Set — they take their own
-     * path. The guard is scheduler-scoped (one process), which is enough
-     * because that's the only place a cron tick can originate.
+     * path. The guard is scheduler-scoped (ONE PROCESS), and that is NOT
+     * enough: it used to say "which is enough because that's the only
+     * place a cron tick can originate", and #1458 disproved it live. The
+     * recipe store is global, so every running bridge schedules every
+     * enabled cron recipe and an in-process Set cannot see a sibling.
+     * N bridges fired N times.
+     *
+     * This Set still does its original job — a slow run overlapping the
+     * next tick WITHIN this process. The cross-process half is
+     * `claimCronSlot` (./cronClaim.ts), taken immediately before dispatch.
      */
     private readonly inflight;
     constructor(opts: SchedulerOptions);
@@ -75,8 +113,27 @@ export declare class RecipeScheduler {
     stop(): void;
     restart(): void;
     list(): ReadonlyArray<Omit<ScheduledRecipe, "timer" | "cronJob">>;
-    /** Test hook: dispatch a recipe immediately without waiting for the interval. */
-    fireForTest(name: string): void;
+    /**
+     * Test hook: dispatch a recipe immediately without waiting for the interval.
+     *
+     * Passes no slot BY DEFAULT, so it takes no cross-process claim. Deliberate:
+     * this hook has no cron match behind it, so there is no instant two processes
+     * could agree on, and inventing one from `Date.now()` would make repeated
+     * calls within the same second collide — which is precisely what the existing
+     * overlap tests do, and they must keep passing unchanged.
+     *
+     * A slot may be passed explicitly to drive the claim path without a live cron
+     * tick, i.e. without a real timer and a real second boundary in CI.
+     */
+    fireForTest(name: string, slotEpochMs?: number): void;
+    /**
+     * @param slotEpochMs The instant the cron matcher matched, threaded from the
+     *   cron callback. Its whole purpose is that two processes observing the same
+     *   tick derive the SAME value — so it must never be re-read from the clock
+     *   here, one event-loop hop later, where a second boundary would split it.
+     *   Absent for `@every` intervals and the test hook: no slot, no claim, and
+     *   behaviour identical to before #1458.
+     */
     private fire;
 }
 type ParsedSchedule = {