agent-accelerator 0.5.7 → 0.5.8

package/src/providers/openai-compat.ts

@@ -406,7 +406,7 @@ function resultToOutput(result: unknown): string {
  * resent — except echoed Gemini thought signatures, which strict
  * OpenAI-compatible endpoints require on tool calls they generated.
  *
- * Q-18: signatures are namespaced — only echo when the stored provider is
+ * Signatures are namespaced — only echo when the stored provider is
  * `google` (or untagged legacy). Signatures minted by other providers never
  * leak onto this transport.
  */
@@ -468,7 +468,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
           // Echo provider-issued thought signatures verbatim so endpoints
           // that minted them (Gemini behind a compat proxy) keep working.
           // Only present when a previous turn captured one — other endpoints
-          // never see this field. Q-18: echo only google/untagged signatures.
+          // never see this field. Echo only google/untagged signatures.
           const storedProvider = (part as { thoughtSignatureProvider?: unknown }).thoughtSignatureProvider;
           if (part.thoughtSignature && shouldEchoSignature(storedProvider, "google")) {
             call.extra_content = { google: { thought_signature: part.thoughtSignature } };
@@ -540,7 +540,7 @@ function extractSignature(rawTc: {
   return typeof sig === "string" && sig ? sig : undefined;
 }
 
-/** Tags a captured compat signature with its issuing provider (`google`, Q-18). */
+/** Tags a captured compat signature with its issuing provider (`google`). */
 function withCompatSignature(sig: string | undefined): { thoughtSignature?: string; thoughtSignatureProvider?: string } {
   if (!sig) return {};
   return { thoughtSignature: sig, thoughtSignatureProvider: "google" };
@@ -575,7 +575,7 @@ function parseResponse(
 
   const choice = response.choices?.[0];
   const message = choice?.message;
-  // Q-23: refusal content surfaces as text with a `refusal` finish reason.
+  // Refusal content surfaces as text with a `refusal` finish reason.
   const refusal = typeof message?.refusal === "string" && message.refusal ? message.refusal : "";
   const text = typeof message?.content === "string" && message.content ? message.content : refusal;
   // Thinking tolerance: plain `reasoning` plus per-block texts (deepseek-style
@@ -789,7 +789,7 @@ export class OpenAICompatibleChatProvider implements Provider {
         // why: invalid output shapes fail fast at Agent construction/loop validation.
       }
     }
-    // Q-38: request usage on streams where supported so terminal accounting
+    // Request usage on streams where supported so terminal accounting
     // arrives on the final chunk. Strict servers that reject unknown fields
     // opt out via `COMPAT_NO_STREAM_OPTIONS=1`; an explicit per-call
     // `(options as any).streamOptions === false` also skips it.
@@ -1068,7 +1068,7 @@ export class OpenAICompatibleChatProvider implements Provider {
           const choice = (Array.isArray(msg["choices"]) ? (msg["choices"] as Record<string, unknown>[])[0] : undefined) ?? {};
           const delta = (choice["delta"] as Record<string, unknown>) ?? {};
           // Text delta (content-free accounting frames carry "" — ignored).
-          // Q-23: refusal deltas surface as text with a `refusal` finish.
+          // Refusal deltas surface as text with a `refusal` finish.
           const deltaRefusal = delta["refusal"];
           if (typeof deltaRefusal === "string" && deltaRefusal) {
             text += deltaRefusal;
@@ -1187,7 +1187,7 @@ export class OpenAICompatibleChatProvider implements Provider {
           sawFinishReason = true;
         }
 
-        // Q-23: terminal-state guard — fail `incomplete_stream` (retryable)
+        // Terminal-state guard — fail `incomplete_stream` (retryable)
         // instead of resolving empty success. Skipped for non-SSE payloads
         // (JSON mocks) where no SSE frames were ever seen.
         const cleanThinking = thinking.replace(/\n{3,}/g, "\n\n").trim();

package/src/providers/openai.ts

@@ -472,7 +472,7 @@ function parseResponse(
     }
   }
 
-  // Q-23: `incomplete` -> length (content-filter truncations surface as
+  // `incomplete` -> length (content-filter truncations surface as
   // refusal when refusal text is present).
   const incompleteReason = (response as { incomplete_details?: { reason?: string } }).incomplete_details?.reason;
   const finishReason =
@@ -828,7 +828,7 @@ export class OpenAIResponsesProvider implements Provider {
           body,
         };
 
-        // Q-17: optional per-call timeout races the linked abort signal.
+        // Optional per-call timeout races the linked abort signal.
         const streamTimeoutMs = timeoutFor(options as { timeoutMs?: number } | undefined);
         // Transient failures (429/5xx/network) are retried here, before the
         // first byte; once the stream is live it is never retried.
@@ -895,7 +895,7 @@ export class OpenAIResponsesProvider implements Provider {
             type === "response.refusal.delta" ||
             type === "response.output_refusal.delta"
           ) {
-            // Q-23: refusal deltas carry the filter text; surface as text and
+            // Refusal deltas carry the filter text; surface as text and
             // remember for a `refusal` finish reason.
             if (typeof msg["delta"] === "string" && msg["delta"]) {
               text += msg["delta"] as string;
@@ -955,7 +955,7 @@ export class OpenAIResponsesProvider implements Provider {
             }
             // Non-streaming maps `incomplete` → `length` (max tokens). Streaming
             // must do the same — otherwise truncated turns misreport `stop`.
-            // Q-23: content-filter incompletes surface as `refusal`.
+            // Content-filter incompletes surface as `refusal`.
             const incompleteReason = (response as { incomplete_details?: { reason?: string } }).incomplete_details?.reason;
             if (response.status === "incomplete") {
               finishReason = incompleteReason === "content_filter" ? "refusal" : "length";
@@ -1039,7 +1039,7 @@ export class OpenAIResponsesProvider implements Provider {
           sawFinishReason = true;
         }
 
-        // Q-23: terminal-state guard. Loops ending with no completed body, no
+        // Terminal-state guard. Loops ending with no completed body, no
         // finish_reason, and no usage while carrying no content must fail as
         // `incomplete_stream` (retryable) instead of resolving empty success.
         // Skipped for non-SSE payloads (e.g. JSON mocks in delegation tests)

package/src/providers/openrouter.ts

@@ -741,7 +741,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           const choice = (Array.isArray(msg["choices"]) ? (msg["choices"] as Record<string, unknown>[])[0] : undefined) ?? {};
           const delta = (choice["delta"] as Record<string, unknown>) ?? {};
           // Text delta (content-free accounting frames carry "" — ignored).
-          // Q-23: refusal deltas surface as text with a `refusal` finish.
+          // Refusal deltas surface as text with a `refusal` finish.
           const deltaRefusal = delta["refusal"];
           if (typeof deltaRefusal === "string" && deltaRefusal) {
             text += deltaRefusal;
@@ -854,7 +854,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           sawFinishReason = true;
         }
 
-        // Q-23: terminal-state guard — fail `incomplete_stream` (retryable)
+        // Terminal-state guard — fail `incomplete_stream` (retryable)
         // instead of resolving empty success. Skipped for non-SSE payloads
         // (JSON mocks) where no SSE frames were ever seen.
         const cleanThinking = thinking.replace(/\n{3,}/g, "\n\n").trim();

package/src/providers/shared.ts

@@ -1,5 +1,5 @@
 /**
- * Shared provider helpers (Q-45-partial).
+ * Shared provider helpers.
  *
  * Single home for the `redactedHeaders` / `readErrorPayload` /
  * `parseArguments` / `normalizeThinkingParts` helpers previously duplicated
@@ -78,7 +78,7 @@ export function readErrorPayload(
   }
 }
 
-/** Retryable incomplete-stream error for truncated SSE (Q-23). */
+/** Retryable incomplete-stream error for truncated SSE. */
 export function incompleteStreamError(provider: string, modelId: string): Error {
   const err = toConciseProviderError(
     Object.assign(new Error("Stream ended without terminal event"), {
@@ -118,7 +118,7 @@ export function isNotFoundChainError(error: unknown): boolean {
   return code === "not_found";
 }
 
-/** Per-request timeout ms from provider options (Q-22). */
+/** Per-request timeout ms from provider options. */
 export function timeoutFor(options: { timeoutMs?: number } | undefined): number | undefined {
   const t = (options as { timeoutMs?: unknown } | undefined)?.timeoutMs;
   return typeof t === "number" && Number.isFinite(t) && t > 0 ? Math.floor(t) : undefined;
@@ -149,7 +149,7 @@ export function combinedSignal(signal?: AbortSignal, timeoutMs?: number): { sign
   return { signal: ctrl.signal, cleanup };
 }
 
-/** Q-34: crypto-backed tool-call id, no Math.random primary. */
+/** Crypto-backed tool-call id, no Math.random primary. */
 export function newToolCallId(prefix = "call"): string {
   try {
     const c = (globalThis as any)?.crypto;

package/src/scheduler/architecture.md

@@ -5,15 +5,18 @@ Scheduled actions: a worker that runs later (once or repeating) and saves its an
 | File | What it is |
 | :-- | :-- |
 | `scheduler.ts` | One `Scheduler` per home folder: a 1 s unref'd clock that runs only while something is pending, startup sweep, cook/deliver state machine, and the public functions (`createScheduledAction`, `list/update/run/skip/deleteScheduledAction`). |
-| `store.ts` | Disk layer under `<home>/scheduled_actions/`: `tasks.json`, `deliveries.json`, run files; validation of records. |
+| `store.ts` | Disk layer under `<home>/scheduled/`: `<id>/task.json`, `<id>/delivery.json`, run files, one short mutex per action; validation of records. |
 | `time.ts` | Pure `DD:HH:MM` and local-clock maths. No timezone, DST or `Intl`; `now` is always passed in. |
 | `tool.ts` + `scheduled-actions.md` | The model-facing `scheduled_actions` tool and `get_datetime`; the `.md` is the tool description. |
 
 ## Invariants
 - The files are the truth: every write re-reads first and goes through the durable writer. The file format is a stable public contract: see `docs/scheduled-action-files.md` and add a changelog row for any change.
-- Write order when a run ends: run file, then `deliveries.json`, then `tasks.json`. The startup sweep repairs a crash in between.
+- Write order when a run ends: run file, then `<id>/delivery.json`, then `<id>/task.json`. The startup sweep repairs a crash in between.
 - `startCook` advances the next times BEFORE the run starts; a run still cooking when the next is due is skipped, never stacked.
 - Runs are fresh stateless workers built by `buildDynamicWorkerConfig`; their spending guardrail is `workerBudget` only.
 - The Agent registry holds `WeakRef`s by name: keep every Agent that owns actions referenced, or its runs become `missed`.
+- Several processes may share a home (the file store is safe for it; the home lock is lifted in a later change of this release). Ownership: a process only starts, delivers or recovers actions whose Agent it registered. An action nobody here owns is left alone until its delivery time passed with no run started, then marked `missed` (`no_agent`).
+- Exactly once: a scheduled start re-checks under the action's mutex that it is still `waiting` and due; `markMissed` only changes the state the caller saw; a delivery is emitted only by the process that removed its entry from `delivery.json`.
+- A run in flight keeps `<id>/.heartbeat` (pid, host, token; mtime refreshed every 5 s, stale after 60 s), written before the record shows `cooking`. A cooking action whose owner is dead (pid gone, stale, or none) is recovered by a live process that owns its Agent, at start and every 15 s. `delete` of a run another live process is cooking is refused, even with `force`.
 - Times come from `Date`, local clock only. Tests inject `scheduler.now` / `tickMs` and call `tick()`.
 - Events: `scheduled_action.{created,updated,started,ready,failed,delivered,missed,skipped,deleted,invalid,store_corrupt,error}`.

package/src/scheduler/scheduler.ts

@@ -4,7 +4,7 @@
  *
  * One clock per home folder, ticking once a second against the machine's own
  * time. Each tick only asks "what is overdue?", so drift, sleep or a clock
- * change cannot skip a run. The files under `<home>/scheduled_actions/` are the
+ * change cannot skip a run. The files under `<home>/scheduled/` are the
  * source of truth (see `store.ts`); nothing waits in memory, and the timer is
  * unref'd and runs only while something is pending.
  *
@@ -12,12 +12,13 @@
  *                                         |                                     |
  *                                         +--> failed (recorded, moves on)      +--> waiting (repeat) | done
  */
+import * as os from "node:os";
 import type { Agent } from "../agent/agent.ts";
 import { createChildSessionId } from "../agent/delegation.ts";
 import { buildDynamicWorkerConfig, grantWorkerTools, scheduledRunTimeoutMs } from "../agent/worker.ts";
 import { telemetryBus } from "../telemetry.ts";
 import { readUsage, usageLine, type UsageTotals } from "../session/usage.ts";
-import { lockFolder } from "../utils/durable.ts";
+import { processAlive } from "../utils/durable.ts";
 import { ConfigError, ValidationError } from "../types/errors.ts";
 import type { ToolDefinition } from "../types/tool.ts";
 import type { AgentResponse } from "../types/response.ts";
@@ -31,18 +32,24 @@ import type {
 } from "../types/scheduler.ts";
 import {
   TASK_ID_PATTERN,
+  clearHeartbeat,
+  createTask,
+  deleteTask,
   findRunFile,
-  migrateLegacyFolder,
   readDeliveries,
+  readHeartbeat,
   readRun,
+  readTask,
   readTasks,
   removeTaskFolder,
   resolveHome,
   runPath,
+  touchHeartbeat,
   updateDeliveries,
-  updateTasks,
+  updateTask,
   validateDelivery,
   validateRecord,
+  writeHeartbeat,
   writeRunFile,
   type PendingDelivery,
   type RunHeader,
@@ -61,6 +68,11 @@ import {
 /** Default lead time (10 minutes) when the developer API omits `startCookingInAdvance`. */
 const DEFAULT_COOK_LEAD = "00:00:10";
 const SLUG_MAX = 48;
+/** A heartbeat older than this means its owner is gone (it is refreshed every 5 s). */
+const HEARTBEAT_STALE_MS = 60_000;
+const HEARTBEAT_EVERY_MS = 5_000;
+/** How often a live process looks for runs whose owner process died. */
+const DEAD_SWEEP_EVERY_MS = 15_000;
 const ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
 
 /** Optional `{ home }` accepted by every public function except `createScheduledAction` (the agent knows its home). */
@@ -240,6 +252,10 @@ export class Scheduler {
   tickMs = 1000;
   private timer: ReturnType<typeof setInterval> | undefined;
   private swept = false;
+  /** Names this scheduler instance in the heartbeat files of the runs it owns. */
+  private readonly token = Math.random().toString(36).slice(2, 10);
+  private lastDeadSweep = 0;
+  private lastBeat = 0;
   private readonly warned = new Set<string>();
 
   constructor(readonly home: string) {}
@@ -268,6 +284,8 @@ export class Scheduler {
         this.swept = true;
         this.startupSweep(now);
       }
+      this.keepHeartbeats(now);
+      this.sweepDeadRuns(now);
       this.deliverDue(now);
       this.startDue(now);
       if (!this.hasPending()) this.stop();
@@ -277,7 +295,7 @@ export class Scheduler {
   }
 
   // Reports an invalid record or delivery once per file/id/problem and leaves the file untouched; in: snapshot/startCook, out: a scheduled_action.invalid warning.
-  private warnInvalid(id: string, problem: string, file = "tasks.json"): void {
+  private warnInvalid(id: string, problem: string, file = "task.json"): void {
     const key = `${file}:${id}:${problem}`;
     if (this.warned.has(key)) return;
     this.warned.add(key);
@@ -297,7 +315,7 @@ export class Scheduler {
     });
     const pending = readDeliveries(this.home).filter((p) => {
       const problem = validateDelivery(p);
-      if (problem) this.warnInvalid(String((p as { id?: unknown }).id), problem, "deliveries.json");
+      if (problem) this.warnInvalid(String((p as { id?: unknown }).id), problem, "delivery.json");
       return !problem;
     });
     return { live, pending };
@@ -318,23 +336,54 @@ export class Scheduler {
    */
   private startupSweep(now: Date): void {
     for (const t of this.snapshot().live) {
-      if (t.state === "cooking") this.recoverCooking(t);
-      else if (t.state === "waiting" && t.nextDeliverAt && parseLocalIso(t.nextDeliverAt).getTime() <= now.getTime()) {
-        this.markMissed(t.id, "process_down", t.schedule.onMissed);
+      if (!this.ownsHere(t.agent)) continue; // another process's action (or nobody's: startDue handles that)
+      if (t.state === "waiting" && t.nextDeliverAt && parseLocalIso(t.nextDeliverAt).getTime() <= now.getTime()) {
+        this.markMissed(t.id, "process_down", "waiting", t.schedule.onMissed);
       }
     }
   }
 
+  // True when a live Agent with this name is registered in THIS process: only then may this process start, deliver or recover its actions; in: the sweeps, startDue and deliverDue, out: a boolean.
+  private ownsHere(agentName: string): boolean {
+    return !!this.agents.get(agentName)?.deref();
+  }
+
+  // True while the process that started a run is still running it: its heartbeat is fresh and (same host) its pid exists; this process counts only for runs in this.running; in: the dead-run sweep and delete, out: the heartbeat or undefined.
+  private liveOwner(id: string): { pid: number } | undefined {
+    if (this.running.has(id)) return { pid: process.pid };
+    const hb = readHeartbeat(this.home, id);
+    if (!hb || hb.ageMs > HEARTBEAT_STALE_MS) return undefined;
+    if (hb.pid === process.pid) return undefined; // an earlier scheduler of this very process is gone
+    if (hb.host === os.hostname() && !processAlive(hb.pid)) return undefined;
+    return { pid: hb.pid };
+  }
+
+  // Refreshes the heartbeat of every run in flight (at most every 5 s); in: tick, out: the .heartbeat files.
+  private keepHeartbeats(now: Date): void {
+    if (this.running.size === 0 || Math.abs(now.getTime() - this.lastBeat) < HEARTBEAT_EVERY_MS) return;
+    this.lastBeat = now.getTime();
+    for (const id of this.running.keys()) touchHeartbeat(this.home, id);
+  }
+
+  // Recovers the runs whose owner is gone (a killed process), but only for actions this process owns, at start and then every 15 s; in: tick, out: recoverCooking calls.
+  private sweepDeadRuns(now: Date): void {
+    if (this.lastDeadSweep !== 0 && Math.abs(now.getTime() - this.lastDeadSweep) < DEAD_SWEEP_EVERY_MS) return;
+    this.lastDeadSweep = now.getTime();
+    for (const t of this.snapshot().live) {
+      if (t.state === "cooking" && this.ownsHere(t.agent) && !this.liveOwner(t.id)) this.recoverCooking(t);
+    }
+  }
+
   /** The process died mid-cook: rebuild the delivery if the run file was already written, else it is missed. */
   private recoverCooking(t: ScheduledActionRecord): void {
     const current = t.current!;
     const file = findRunFile(this.home, t.id, parseLocalIso(current.deliverAt), current.cookStartedAt);
     const run = file ? readRun(this.home, file) : undefined;
     if (!file || !run) {
-      this.markMissed(t.id, "interrupted", t.schedule.onMissed);
+      this.markMissed(t.id, "interrupted", "cooking", t.schedule.onMissed);
       return;
     }
-    updateDeliveries(this.home, (pending) => {
+    updateDeliveries(this.home, t.id, (pending) => {
       if (pending.some((p) => p.file === file)) return;
       pending.push({
         id: t.id,
@@ -345,24 +394,24 @@ export class Scheduler {
         ...(run.header["late"] === "true" ? { late: true } : {}),
       });
     });
-    updateTasks(this.home, (tasks) => {
-      const rec = tasks.find((x) => x.id === t.id);
+    updateTask(this.home, t.id, (rec) => {
       if (!rec || rec.state !== "cooking") return;
       delete rec.current;
       rec.state = rec.nextDeliverAt ? "waiting" : "done";
     });
   }
 
-  // Marks a run whose moment passed as missed, then applies the action's onMissed policy: `skip` moves on to the next time, `run` runs it now, unset waits for run_now / skip; in: the startup sweep, out: tasks.json + the missed (and skipped / started) events.
-  private markMissed(id: string, reason: string, policy?: "skip" | "run"): void {
+  // Marks a run whose moment passed as missed, then applies the action's onMissed policy: `skip` moves on to the next time, `run` runs it now, unset waits for run_now / skip; only when the action is still in the state the caller saw (`from`), so two processes never both mark it; in: the sweeps, out: task.json + the missed (and skipped / started) events.
+  private markMissed(id: string, reason: string, from: "waiting" | "cooking", policy?: "skip" | "run"): void {
     let name = id;
-    updateTasks(this.home, (tasks) => {
-      const t = tasks.find((x) => x.id === id);
-      if (!t) return;
+    const changed = updateTask(this.home, id, (t) => {
+      if (!t || t.state !== from) return false; // another process already dealt with it
       name = t.name;
       t.state = "missed";
       delete t.current;
+      return true;
     });
+    if (!changed) return;
     const next = policy === "skip" ? "Skipping it (onMissed: skip)." : policy === "run" ? "Running it now (onMissed: run)." : "Use run_now or skip.";
     emit("missed", `"${name}" (${id}) missed its run (${reason}). ${next}`, { id, name, reason, ...(policy ? { onMissed: policy } : {}) }, "warn");
     if (policy === "skip") this.skip(id);
@@ -374,21 +423,25 @@ export class Scheduler {
   // Delivers every saved run whose delivery time has come; in: tick, out: deliver calls.
   private deliverDue(now: Date): void {
     for (const entry of this.snapshot().pending) {
-      if (parseLocalIso(entry.deliverAt).getTime() <= now.getTime()) this.deliver(entry, now);
+      if (parseLocalIso(entry.deliverAt).getTime() > now.getTime()) continue;
+      const owner = readTask(this.home, entry.id)?.agent; // the delivered event must fire in the process that owns the action
+      if (owner === undefined || this.ownsHere(owner)) this.deliver(entry, now);
     }
   }
 
-  // Removes the entry, records `lastRun`, THEN emits (whether or not anyone listens); late = it replaced a missed occurrence, was delivered over two ticks after its time, or finished after it; in: deliverDue, out: tasks.json + the delivered event.
+  // Removes the entry (only the process that removed it goes on), records `lastRun`, THEN emits (whether or not anyone listens); late = it replaced a missed occurrence, was delivered over two ticks after its time, or finished after it; in: deliverDue, out: task.json + the delivered event.
   private deliver(entry: PendingDelivery, now: Date): void {
-    updateDeliveries(this.home, (pending) => {
+    const removed = updateDeliveries(this.home, entry.id, (pending) => {
       const i = pending.findIndex((p) => p.id === entry.id && p.file === entry.file);
-      if (i >= 0) pending.splice(i, 1);
+      if (i < 0) return false;
+      pending.splice(i, 1);
+      return true;
     });
+    if (!removed) return; // another process took this delivery: exactly one process delivers it
     const deliverAt = parseLocalIso(entry.deliverAt).getTime();
     const late = entry.late === true || now.getTime() - deliverAt > 2 * this.tickMs || parseLocalIso(entry.readyAt).getTime() > deliverAt;
     let name = entry.id;
-    updateTasks(this.home, (tasks) => {
-      const t = tasks.find((x) => x.id === entry.id);
+    updateTask(this.home, entry.id, (t) => {
       if (!t) return;
       name = t.name;
       t.lastRun = { status: entry.status, file: entry.file, deliverAt: entry.deliverAt, deliveredAt: toLocalIso(now), late };
@@ -410,6 +463,13 @@ export class Scheduler {
   // Starts waiting actions whose cook time has come and skips the overlap of those still cooking; in: tick, out: startCook/skipOverlap calls.
   private startDue(now: Date): void {
     for (const t of this.snapshot().live) {
+      if (!this.ownsHere(t.agent)) {
+        // Nobody here can run it. Another process may own it, so only once its delivery time has passed with no run started is it missed.
+        if (t.state === "waiting" && t.nextDeliverAt && parseLocalIso(t.nextDeliverAt).getTime() <= now.getTime()) {
+          this.markMissed(t.id, "no_agent", "waiting");
+        }
+        continue;
+      }
       if (!t.nextCookAt || parseLocalIso(t.nextCookAt).getTime() > now.getTime()) continue;
       if (t.state === "waiting") this.startCook(t.id, false);
       else if (t.state === "cooking") this.skipOverlap(t.id, now);
@@ -433,8 +493,7 @@ export class Scheduler {
   private startCook(id: string, manual: boolean): ScheduledActionRecord | undefined {
     const now = this.now();
     const ctx: { agent?: Agent; noAgent?: boolean; replacesMissed?: boolean } = {};
-    const started = updateTasks(this.home, (tasks) => {
-      const t = tasks.find((x) => x.id === id);
+    const started = updateTask(this.home, id, (t) => {
       if (!t) return undefined;
       const problem = validateRecord(t);
       if (problem) {
@@ -442,6 +501,8 @@ export class Scheduler {
         return undefined;
       }
       if (t.state === "cooking") return undefined;
+      // Another process may have started (and even finished) this run since the caller looked: a scheduled start needs the action to be waiting and due right now.
+      if (!manual && (t.state !== "waiting" || !t.nextCookAt || parseLocalIso(t.nextCookAt).getTime() > now.getTime())) return undefined;
       ctx.replacesMissed = manual && t.state === "missed";
       ctx.agent = this.agents.get(t.agent)?.deref();
       if (!ctx.agent) {
@@ -465,11 +526,12 @@ export class Scheduler {
       t.current = { cookStartedAt: toLocalIso(now), deliverAt: toLocalIso(deliverAt) };
       t.nextCookAt = next.cook;
       t.nextDeliverAt = next.deliver;
+      writeHeartbeat(this.home, id, this.token); // before the record shows `cooking`, so no process sees a cooking action without an owner
       return t;
     });
     if (ctx.noAgent) {
       const name = this.nameOf(id);
-      emit("missed", `"${name}" (${id}) cannot run: no live Agent named in tasks.json is registered.`, { id, name, reason: "no_agent" }, "warn");
+      emit("missed", `"${name}" (${id}) cannot run: no live Agent named in its task.json is registered.`, { id, name, reason: "no_agent" }, "warn");
     }
     if (!started || !ctx.agent) return undefined;
     emit("started", `"${started.name}" (${id}) started cooking.`, {
@@ -482,16 +544,15 @@ export class Scheduler {
     return started;
   }
 
-  // The display name of an action from tasks.json, else its id; in: startCook's no-agent message, out: event text.
+  // The display name of an action from task.json, else its id; in: startCook's no-agent message, out: event text.
   private nameOf(id: string): string {
-    return readTasks(this.home).find((t) => t.id === id)?.name ?? id;
+    return readTask(this.home, id)?.name ?? id;
   }
 
   /** The next run is due while this one still cooks: never stack. Skip that occurrence. */
   private skipOverlap(id: string, now: Date): void {
     const ctx: { skipped?: { name: string; deliverAt: string } } = {};
-    updateTasks(this.home, (tasks) => {
-      const t = tasks.find((x) => x.id === id);
+    updateTask(this.home, id, (t) => {
       if (!t || t.state !== "cooking" || !t.nextCookAt || !t.nextDeliverAt) return;
       ctx.skipped = { name: t.name, deliverAt: t.nextDeliverAt };
       if (!t.schedule.repeatEvery) {
@@ -520,6 +581,7 @@ export class Scheduler {
       })
       .finally(() => {
         this.running.delete(task.id);
+        clearHeartbeat(this.home, task.id);
       });
     this.ensureRunning();
   }
@@ -593,7 +655,7 @@ export class Scheduler {
     }
   }
 
-  // Writes a finished run: run file, then the `deliveries.json` entry, then `tasks.json` (a crash in between is repaired on start); a manual run is due when it finishes and is late only if it replaced a missed occurrence, a scheduled one is late only past its second; in: runWorker, out: the files and the ready/failed event.
+  // Writes a finished run: run file, then the `delivery.json` entry, then `task.json` (a crash in between is repaired on start); a manual run is due when it finishes and is late only if it replaced a missed occurrence, a scheduled one is late only past its second; in: runWorker, out: the files and the ready/failed event.
   private finish(task: ScheduledActionRecord, outcome: Outcome, startedAt: string, deliverAt: Date, run: Pick<RunningEntry, "manual" | "missed">): void {
     const now = this.now();
     const ok = "res" in outcome;
@@ -614,11 +676,10 @@ export class Scheduler {
     };
     const body = ok ? outcome.res.text.trim() || "[The worker returned no text.]" : `The run failed: ${outcome.error}`;
     const file = writeRunFile(this.home, task.id, deliverAt, header, body);
-    updateDeliveries(this.home, (pending) => {
+    updateDeliveries(this.home, task.id, (pending) => {
       pending.push({ id: task.id, file, status: header.status, readyAt: finishedAt, deliverAt: header.deliverAt, ...(run.missed ? { late: true } : {}) });
     });
-    updateTasks(this.home, (tasks) => {
-      const t = tasks.find((x) => x.id === task.id);
+    updateTask(this.home, task.id, (t) => {
       if (!t || t.state !== "cooking") return;
       delete t.current;
       t.state = t.nextDeliverAt ? "waiting" : "done";
@@ -632,7 +693,7 @@ export class Scheduler {
 
   // Starts an action immediately outside its schedule (also resolves a missed one); in: runScheduledAction, out: the cooking record.
   runNow(id: string): ScheduledActionRecord {
-    const rec = readTasks(this.home).find((t) => t.id === id);
+    const rec = readTask(this.home, id);
     if (!rec) throw notFound(id);
     if (rec.state === "cooking" || this.running.has(id)) {
       throw new ValidationError(`Scheduled action "${id}" is already cooking; wait for it to finish.`);
@@ -650,8 +711,7 @@ export class Scheduler {
   // Ignores a missed occurrence and schedules the next one (a one-shot becomes done); in: skipScheduledAction and onMissed: skip, out: the updated record.
   skip(id: string): ScheduledActionRecord {
     const now = this.now();
-    const rec = updateTasks(this.home, (tasks) => {
-      const t = tasks.find((x) => x.id === id);
+    const rec = updateTask(this.home, id, (t) => {
       if (!t) throw notFound(id);
       if (t.state !== "missed") throw new ValidationError(`Scheduled action "${id}" is ${t.state}, not missed: nothing to skip.`);
       const next = this.afterMissed(t, now);
@@ -668,9 +728,17 @@ export class Scheduler {
 
   // Deletes an action (aborting a cooking run only with force) and optionally purges its run files; in: deleteScheduledAction, out: a DeleteResult.
   async delete(id: string, opts: { force?: boolean; purge?: boolean }): Promise<DeleteResult> {
-    const rec = readTasks(this.home).find((t) => t.id === id);
+    const rec = readTask(this.home, id);
     if (!rec) return { ok: false, reason: "not_found" };
     const run = this.running.get(id);
+    const other = !run && rec.state === "cooking" ? this.liveOwner(id) : undefined;
+    if (other) {
+      return {
+        ok: false,
+        reason: "running",
+        message: `"${id}" is cooking in another process (pid ${other.pid}), so nothing was changed. Only that process can abort it: wait for it to finish, or delete it from there.`,
+      };
+    }
     if (run && !opts.force) {
       return {
         ok: false,
@@ -683,13 +751,7 @@ export class Scheduler {
       run.controller.abort(new Error("deleted"));
       await run.done;
     }
-    updateTasks(this.home, (tasks) => {
-      const i = tasks.findIndex((t) => t.id === id);
-      if (i >= 0) tasks.splice(i, 1);
-    });
-    updateDeliveries(this.home, (pending) => {
-      for (let i = pending.length - 1; i >= 0; i--) if (pending[i]!.id === id) pending.splice(i, 1);
-    });
+    if (!deleteTask(this.home, id)) return { ok: false, reason: "not_found" }; // another process deleted it first; only the one that removed it reports it
     if (opts.purge) removeTaskFolder(this.home, id);
     emit("deleted", `"${rec.name}" (${id}) was deleted.`, { id, name: rec.name, forced: !!run, purged: !!opts.purge });
     return { ok: true };
@@ -706,8 +768,6 @@ const schedulers = new Map<string, Scheduler>();
 export function getScheduler(home: string): Scheduler {
   let s = schedulers.get(home);
   if (!s) {
-    lockFolder(home); // every scheduler function goes through here: one process per home
-    migrateLegacyFolder(home);
     schedulers.set(home, (s = new Scheduler(home)));
   }
   return s;
@@ -749,11 +809,7 @@ export function createScheduledAction(agent: Agent, input: ScheduledActionInput)
   const sa = input.scheduled_action;
   const lead = sa.startCookingInAdvance ?? DEFAULT_COOK_LEAD;
   const deliverAt = resolveDelivery(now, sa.timeToDeliver, sa.meridiem);
-  const record = updateTasks(s.home, (tasks) => {
-    const taken = new Set(tasks.map((t) => t.id));
-    let id: string;
-    do id = `${sa.id}-${randomSuffix()}`;
-    while (taken.has(id));
+  const record = createTask(s.home, () => `${sa.id}-${randomSuffix()}`, (id) => {
     const rec: ScheduledActionRecord = {
       id,
       name: sa.name.trim(),
@@ -776,7 +832,6 @@ export function createScheduledAction(agent: Agent, input: ScheduledActionInput)
       nextDeliverAt: toLocalIso(deliverAt),
       createdAt: toLocalIso(now),
     };
-    tasks.push(rec);
     return rec;
   });
   s.agents.set(agent.name, new WeakRef(agent));
@@ -807,11 +862,10 @@ export function updateScheduledAction(id: string, patch: ScheduledActionPatch, o
   const now = s.now();
   const sa = patch.scheduled_action ?? {};
   const { name, ...scheduleChange } = sa;
-  const rec = updateTasks(s.home, (tasks) => {
-    const t = tasks.find((x) => x.id === id);
+  const rec = updateTask(s.home, id, (t) => {
     if (!t) throw notFound(id);
     const stored = validateRecord(t);
-    if (stored) throw new ValidationError(`Scheduled action "${id}" is invalid in tasks.json: ${stored}`);
+    if (stored) throw new ValidationError(`Scheduled action "${id}" is invalid in its task.json: ${stored}`);
     const scheduleChanged = Object.values(scheduleChange).some((v) => v !== undefined);
     if (scheduleChanged && t.state === "cooking") {
       throw new ValidationError(`Scheduled action "${id}" is cooking right now; schedule changes are refused while it runs. Try again after it finishes.`);