@sigrun/sigrun 0.2.0 → 0.3.0

package/dist/harness/loader.js

@@ -89,6 +89,7 @@ import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { satisfies, validRange } from "semver";
 import { HOST_RUNTIME_MODULES, hostModuleVersion, readPackageAssetsDir, readPackageName, readPackageVersion, resolveExtensionEntry, } from "./packages.js";
 import { RESERVED_CORE_SECTION_KEYS, RESERVED_EXTENSION_SLUGS, } from "./reserved-sections.js";
 import { slugifyName } from "./stores.js";
@@ -997,6 +998,57 @@ function checkHostModules(moduleDir) {
             `host runs ${hostVersion} (same major, allowed)`);
     }
 }
+/**
+ * The Earendil host modules whose DECLARED peer ranges the loader checks.
+ * Other peers (typebox and @sigrun/sigrun) have different compatibility
+ * contracts and are deliberately outside this guard.
+ */
+const DECLARED_PEER_MODULES = [
+    "@earendil-works/pi-durable",
+    "@earendil-works/chord",
+    "@earendil-works/pi-ai",
+];
+/**
+ * The declared-peer guard (pi-durable 1.4.0 D7): after the resolved-version
+ * guard, reject an Earendil peer range that excludes the running host.
+ * Non-semver specifiers (file:, link:, git:, URLs, workspace:) and wildcards
+ * pass; a missing or unreadable manifest also passes because the guard never
+ * quarantines what it cannot read.
+ *
+ * @param moduleDir the extension ENTRY's directory; the owning package
+ * manifest is the nearest manifest at or above it.
+ * @returns the quarantine reason, or undefined when the declaration admits
+ * the host or cannot be evaluated.
+ */
+function checkDeclaredPeers(moduleDir) {
+    const manifestPath = nearestManifest(moduleDir);
+    if (manifestPath === undefined)
+        return undefined;
+    let peers;
+    try {
+        const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+        if (typeof parsed.peerDependencies !== "object" ||
+            parsed.peerDependencies === null ||
+            Array.isArray(parsed.peerDependencies)) {
+            return undefined;
+        }
+        peers = parsed.peerDependencies;
+    }
+    catch {
+        return undefined;
+    }
+    for (const name of DECLARED_PEER_MODULES) {
+        const range = peers[name];
+        if (typeof range !== "string" || validRange(range) === null)
+            continue;
+        const hostVersion = hostModuleVersion(name);
+        if (hostVersion !== undefined &&
+            !satisfies(hostVersion, range)) {
+            return `peer ${name} ${range} excludes host ${hostVersion}`;
+        }
+    }
+    return undefined;
+}
 /**
  * The extension module's DIRECTORY — the anchor a contributed bundle's
  * relative `dir` resolves against (build-and-webui Task 6: an
@@ -1497,8 +1549,12 @@ export async function loadExtensions(specifiers, registry, options = {}) {
             // here rides the existing per-extension try (quarantine, boot
             // continues) exactly like the reserved-section check below.
             const moduleDir = extensionModuleDir(loaded);
-            if (moduleDir !== undefined)
+            if (moduleDir !== undefined) {
                 checkHostModules(moduleDir);
+                const peerReason = checkDeclaredPeers(moduleDir);
+                if (peerReason !== undefined)
+                    throw new Error(peerReason);
+            }
             // Two-phase host: the factory receives the host at CALL time, but
             // the extension name and kinds it declares are only known from its
             // RESULT. The loader therefore invokes the host factory TWICE with

package/dist/harness/migration-snapshot.js

@@ -0,0 +1,97 @@
+/**
+ * Pre-migration snapshot (spec D4): before pi-durable opens a SQLite store,
+ * preserve the last schema the previous release can read.
+ *
+ * The probe deliberately opens read-write but issues no writes. A read-only
+ * connection cannot recover a WAL left by an unclean shutdown, so the read-
+ * write open lets SQLite perform crash recovery before `VACUUM INTO` writes a
+ * consistent, independent snapshot. Probe/open failures SKIP so the real
+ * storage opener can report the underlying error; a failure of a needed
+ * snapshot instead fails boot through `MigrationSnapshotError`.
+ *
+ * This runs before every durable schema migration, not only v1 → v2.
+ * Snapshots are never removed automatically. JSONL storage has no schema
+ * migration and therefore does not pass through this helper.
+ */
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { CURRENT_SQLITE_SCHEMA_VERSION } from "@earendil-works/pi-durable/storage/sqlite";
+export const SKIP_MIGRATION_SNAPSHOT_ENV = "SIGRUN_SKIP_MIGRATION_SNAPSHOT";
+/** A required pre-migration snapshot could not be written. */
+export class MigrationSnapshotError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "MigrationSnapshotError";
+    }
+}
+/** UTC compact stamp through milliseconds; one-millisecond boots never collide. */
+function compactUtcStamp(date) {
+    return date.toISOString().replace(/[-:]/g, "").replace(".", "");
+}
+/** Quote one SQLite string literal (the snapshot path can contain `'`). */
+function sqlString(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Return the snapshot path when a migration is needed, otherwise `undefined`.
+ * Throws `MigrationSnapshotError` when a required snapshot cannot be written.
+ */
+export async function snapshotBeforeMigration(storagePath, opts) {
+    if (opts.env[SKIP_MIGRATION_SNAPSHOT_ENV] === "1") {
+        opts.log(`sigrun: durable migration snapshot skipped (${SKIP_MIGRATION_SNAPSHOT_ENV}=1): ${storagePath}`);
+        return undefined;
+    }
+    if (!existsSync(storagePath))
+        return undefined;
+    let db;
+    try {
+        db = new DatabaseSync(storagePath);
+    }
+    catch (error) {
+        opts.log(`sigrun: durable migration snapshot skipped; probe could not open ${storagePath}: ${messageOf(error)}`);
+        return undefined;
+    }
+    try {
+        let version;
+        try {
+            const row = db
+                .prepare("SELECT version FROM durable_schema WHERE singleton = 1")
+                .get();
+            version = row?.version;
+        }
+        catch (error) {
+            // A file without durable_schema is not a durable store. Invalid
+            // database files also defer to the real storage opener so it can
+            // report its own, more useful error.
+            const message = messageOf(error);
+            if (message.includes("no such table: durable_schema") ||
+                message.includes("file is not a database")) {
+                opts.log(`sigrun: durable migration snapshot skipped; durable schema probe failed for ${storagePath}: ${message}`);
+                return undefined;
+            }
+            // An environmental failure while probing an existing durable file
+            // can surface here too (SQLite may need journal/WAL sidecars even
+            // for its first SELECT). Do NOT turn that into a silent skip: a
+            // snapshot cannot be assured, so stop before migration.
+            throw new MigrationSnapshotError(`could not probe ${storagePath} before durable schema migration: ${messageOf(error)}; set ${SKIP_MIGRATION_SNAPSHOT_ENV}=1 only when you have an independent backup`, { cause: error });
+        }
+        if (version === undefined || version >= CURRENT_SQLITE_SCHEMA_VERSION) {
+            return undefined;
+        }
+        const snapshotPath = `${storagePath}.pre-durable-schema-v${CURRENT_SQLITE_SCHEMA_VERSION}-${compactUtcStamp(opts.now())}.bak`;
+        try {
+            db.exec(`VACUUM INTO ${sqlString(snapshotPath)}`);
+        }
+        catch (error) {
+            throw new MigrationSnapshotError(`could not snapshot ${storagePath} to ${snapshotPath} before durable schema migration v${version} → v${CURRENT_SQLITE_SCHEMA_VERSION}: ${messageOf(error)}; set ${SKIP_MIGRATION_SNAPSHOT_ENV}=1 only when you have an independent backup`, { cause: error });
+        }
+        opts.log(`sigrun: durable migration snapshot ${snapshotPath} (v${version} → v${CURRENT_SQLITE_SCHEMA_VERSION})`);
+        return snapshotPath;
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/harness/reports.js

@@ -0,0 +1,100 @@
+/**
+ * pi-durable 1.4.0 `HarnessOptions.onReport` visibility (D5).
+ *
+ * Reports can arrive DURING `Harness.open`, before a Harness exists for
+ * follow-up work. This collector is therefore synchronous and small: count
+ * and log immediately; retain task_parked identities for boot's post-open
+ * drain. It never reads transcripts, and no failure in logging or an
+ * observer can escape into pi-durable.
+ */
+export const REPORT_TYPES = [
+    "session_failed",
+    "task_faulted",
+    "task_parked",
+    "migration_failed",
+    "task_outdated",
+    "task_error",
+    "extension_error",
+    "host_error",
+    "listener_error",
+];
+const MESSAGE_LIMIT = 500;
+/** A message without a throw of its own (unknown values can be hostile). */
+function errorMessage(error) {
+    try {
+        if (error instanceof Error)
+            return error.message;
+    }
+    catch {
+        // A cross-realm/hostile error can reject instanceof; fall through.
+    }
+    try {
+        return String(error);
+    }
+    catch {
+        return Object.prototype.toString.call(error);
+    }
+}
+/** One structured log field. JSON quoting keeps newlines out of the line. */
+function field(name, value) {
+    return `${name}=${JSON.stringify(value)}`;
+}
+/** Format one report without exposing transcript content or ordinary stacks. */
+function formatReport(error, info) {
+    const fields = [];
+    if ("task" in info && info.task !== undefined) {
+        fields.push(["task", info.task.id], ["kind", info.task.kind], ["conversation", info.task.conversationId]);
+    }
+    if ("extension" in info && info.extension !== undefined) {
+        fields.push(["extension", info.extension]);
+    }
+    if ("conversationId" in info && info.conversationId !== undefined) {
+        fields.push(["conversation", info.conversationId]);
+    }
+    if ("callback" in info)
+        fields.push(["callback", info.callback]);
+    if ("reason" in info)
+        fields.push(["reason", info.reason]);
+    fields.push(["message", errorMessage(error).slice(0, MESSAGE_LIMIT)]);
+    if (info.type === "session_failed" && error instanceof Error && error.stack !== undefined) {
+        fields.push(["stack", error.stack]);
+    }
+    return [
+        `sigrun: durable ${info.type}`,
+        ...fields.map(([name, value]) => field(String(name), value)),
+    ].join(" ");
+}
+/** Create the one process-local report collector passed to Harness.open. */
+export function createDurableReports(opts) {
+    const totals = Object.fromEntries(REPORT_TYPES.map((type) => [type, 0]));
+    let parked = [];
+    return {
+        onReport(error, info) {
+            // Count and queue before logging: a throwing sink cannot lose the
+            // report, and pi-durable never receives a callback exception.
+            totals[info.type] += 1;
+            if (info.type === "task_parked")
+                parked.push(info.task);
+            try {
+                opts.log(formatReport(error, info));
+            }
+            catch {
+                // A host log sink is not allowed to fail durable scheduling.
+            }
+            try {
+                opts.onReport?.(error, info);
+            }
+            catch {
+                // Test/observer seams have the same containment rule.
+            }
+        },
+        counts() {
+            return { ...totals };
+        },
+        takeParked() {
+            const drained = parked;
+            parked = [];
+            return drained;
+        },
+    };
+}

package/dist/harness/seam-host.js

@@ -18,6 +18,7 @@
  */
 import { AmbientDoc, AmbientOwnersDoc, validateAmbient, } from "./ambient.js";
 import { InteractionDoc, InteractionsIndexDoc, applyAnswer, asInteractionRecord, indexPending, indexSettled, sweepSecretDelivery, takeSecretDelivery, validateInteraction, } from "./interactions.js";
+import { toDurableContext } from "./context.js";
 import { scopedExtensionStores, } from "./stores.js";
 /** One seam violation. Name carries the surface ("interaction"/"ambient"). */
 export class SeamError extends Error {
@@ -62,7 +63,9 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
         const h = await bind.harness();
         // The caller's context gates the wait: an aborted request/tool call
         // unwinds instead of waiting forever for a harness that never opens.
-        context.abortSignal?.throwIfAborted();
+        // Normalize here too so this accessor remains safe for future callers;
+        // each method below also normalizes its own binding for h.* forwarding.
+        toDurableContext(context).abortSignal?.throwIfAborted();
         return h;
     }
     // The server-provided host bridge (W5 Task 5): the conversation/
@@ -120,6 +123,7 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
             const problem = validateInteraction(record);
             if (problem !== null)
                 throw new SeamError("interaction", problem);
+            context = toDurableContext(context);
             const h = await harness(context);
             await h.commit(async (tx) => {
                 // Maintain the index in the SAME commit as the record.
@@ -132,6 +136,7 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
             }, context);
         },
         async answerInteraction(conversationId, callId, answer, context, opts) {
+            context = toDurableContext(context);
             const h = await harness(context);
             return await h.commit(async (tx) => {
                 const draft = await tx.doc(InteractionDoc, conversationId, callId, callId);
@@ -150,6 +155,7 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
             }, context);
         },
         async settleInteraction(conversationId, callId, status, context) {
+            context = toDurableContext(context);
             const h = await harness(context);
             // The sweep (Review Focus 4) is INSIDE the commit, applied only on
             // the terminal transition: sweeping before the pending check would
@@ -171,7 +177,21 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
                 return true;
             }, context);
         },
+        async peekInteraction(conversationId, callId, context) {
+            // The non-consuming inspection read (release-readiness-2 §1):
+            // the SAME stored projection as snapshotInteraction, with NO
+            // path to takeSecretDelivery — an inspector (the gateway
+            // notifier, outcome edits, answer correlation) can never eat
+            // the owning extension's one-shot raw-secret delivery.
+            context = toDurableContext(context);
+            const h = await harness(context);
+            const stored = await h.snapshot(InteractionDoc, conversationId, callId, context);
+            if (stored === undefined)
+                return undefined;
+            return asInteractionRecord(stored);
+        },
         async snapshotInteraction(conversationId, callId, context) {
+            context = toDurableContext(context);
             const h = await harness(context);
             const stored = await h.snapshot(InteractionDoc, conversationId, callId, context);
             if (stored === undefined)
@@ -199,6 +219,7 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
             if (!ambientKinds.has(record.key)) {
                 throw new SeamError("ambient", `surface key ${JSON.stringify(record.key)} is not declared by ${identity.name} (declare it in the factory result's ambientKinds)`);
             }
+            context = toDurableContext(context);
             const h = await harness(context);
             await h.commit(async (tx) => {
                 // Allocation: one owner per key. The claim happens in the same
@@ -233,6 +254,7 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
             if (!ambientKinds.has(key)) {
                 throw new SeamError("ambient", `surface key ${JSON.stringify(key)} is not declared by ${identity.name}`);
             }
+            context = toDurableContext(context);
             const h = await harness(context);
             await h.commit(async (tx) => {
                 const draft = await tx.doc(AmbientDoc, conversationId, key, key);

package/dist/harness/sections/context-files.js

@@ -53,7 +53,7 @@ export const IDENTITY_TEXT = "You are sigrun, an AI assistant running as a persi
  * The persona sigrun ships when no `SOUL.md` exists. A present `SOUL.md`
  * replaces it wholesale; the default is never merged in.
  */
-export const DEFAULT_PERSONA = `You are Sigrun. You choose, and you say why — a valkyrie doesn't dither over the field. You have opinions and you give them straight: if a plan is bad, say it's bad and say what would make it good. Hedging is a way of lying politely.
+export const DEFAULT_PERSONA = `You are Sigrun. You choose, and you say why — choosing is the job, and dithering over the field isn't. You have opinions and you give them straight: if a plan is bad, say it's bad and say what would make it good. Hedging is a way of lying politely.
 
 Match your reply to the weight of the ask. No filler openers, no restating the request, no narrating what the user can already see. When you don't know, say so and name what would settle it.
 

package/dist/harness/settings.js

@@ -500,6 +500,7 @@ function validateServer(server) {
             "reserveTokens",
             "keepRecentTokens",
             "backgroundTokens",
+            "modelOverrides",
         ]);
         if (compaction.enabled !== undefined && typeof compaction.enabled !== "boolean") {
             throw new SettingsValidationError("server.compaction.enabled", "must be a boolean");
@@ -511,10 +512,38 @@ function validateServer(server) {
             // backgroundTokens' minimum is 0 — the designed "background off"
             // value, same as `SIGRUN_COMPACTION_BACKGROUND_TOKENS`.
             const minimum = key === "backgroundTokens" ? 0 : 1;
-            if (typeof v !== "number" ||
-                !Number.isInteger(v) ||
-                v < minimum) {
-                throw new SettingsValidationError(`server.compaction.${key}`, minimum === 0 ? "must be a non-negative integer" : "must be a positive integer");
+            assertIntegerMinimum(`server.compaction.${key}`, v, minimum);
+        }
+        if (compaction.modelOverrides !== undefined) {
+            const overrides = asRecord(compaction.modelOverrides);
+            if (overrides === undefined) {
+                throw new SettingsValidationError("server.compaction.modelOverrides", "must be an object");
+            }
+            // Each entry is a partial policy with the SAME fields and
+            // minimums as the parent block; unknown inner keys fail naming
+            // the full `...modelOverrides.<model>.<field>` path.
+            for (const [modelKey, entry] of Object.entries(overrides)) {
+                const policy = asRecord(entry);
+                if (policy === undefined) {
+                    throw new SettingsValidationError(`server.compaction.modelOverrides.${modelKey}`, "must be an object");
+                }
+                const prefix = `server.compaction.modelOverrides.${modelKey}.`;
+                checkKeys(prefix, policy, [
+                    "enabled",
+                    "reserveTokens",
+                    "keepRecentTokens",
+                    "backgroundTokens",
+                ]);
+                if (policy.enabled !== undefined && typeof policy.enabled !== "boolean") {
+                    throw new SettingsValidationError(`${prefix}enabled`, "must be a boolean");
+                }
+                for (const key of ["reserveTokens", "keepRecentTokens", "backgroundTokens"]) {
+                    const v = policy[key];
+                    if (v === undefined)
+                        continue;
+                    const minimum = key === "backgroundTokens" ? 0 : 1;
+                    assertIntegerMinimum(`${prefix}${key}`, v, minimum);
+                }
             }
         }
     }
@@ -710,6 +739,21 @@ function isPositiveNumber(value) {
 function isNonEmptyString(value) {
     return typeof value === "string" && value !== "";
 }
+/**
+ * The shared compaction numeric rule (parent block and per-model overrides):
+ * an integer at or above `minimum` — `0` for `backgroundTokens` (the designed
+ * "background off" value), `1` for the other token counts. Throws naming the
+ * full dotted field path.
+ */
+function assertIntegerMinimum(field, value, minimum) {
+    if (typeof value !== "number" ||
+        !Number.isInteger(value) ||
+        value < minimum) {
+        throw new SettingsValidationError(field, minimum === 0
+            ? "must be a non-negative integer"
+            : "must be a positive integer");
+    }
+}
 function isNonEmptyStringArray(value) {
     return (Array.isArray(value) &&
         value.every((entry) => isNonEmptyString(entry)));
@@ -865,6 +909,10 @@ export class SettingsStore {
                             ...(sub.compaction ?? {}),
                         };
                         for (const [compKey, compValue] of Object.entries(subValue)) {
+                            // modelOverrides REPLACES the whole map by
+                            // construction: it is a leaf value here, so this
+                            // per-key assign swaps it verbatim rather than
+                            // merging into the previous map.
                             if (compValue === null)
                                 delete mergedCompaction[compKey];
                             else

package/dist/jobs/docs.js

@@ -35,6 +35,7 @@ export const JobDoc = defineDocFamily({
     kind: "sigrun.job",
     version: 1,
     scope: "session",
+    checkpointWhen: () => false,
     family: true,
     initial: (seed) => seed,
 });
@@ -43,6 +44,7 @@ export const JobRevisionDoc = defineDocFamily({
     kind: "sigrun.job.revision",
     version: 1,
     scope: "session",
+    checkpointWhen: () => false,
     family: true,
     initial: (seed) => seed,
 });
@@ -51,6 +53,7 @@ export const JobRunDoc = defineDocFamily({
     kind: "sigrun.job.run",
     version: 1,
     scope: "session",
+    checkpointWhen: () => false,
     family: true,
     initial: (seed) => seed,
 });

package/dist/jobs/fire.js

@@ -325,6 +325,8 @@ async function fireTaskAction(deps, id, record, fireKey, baseRun, prior, context
         }, context);
     }
     await patchJob(deps.harness, id, (draft) => {
+        draft.state = "waiting";
+        delete draft.reason;
         draft.lastRun = run;
     }, context);
     return { outcome: "running" };

package/dist/jobs/parked.js

@@ -0,0 +1,38 @@
+/**
+ * D5 parked-schedule recovery: translate pi-durable's task_parked identity
+ * into the job record's status fields after Harness.open has returned.
+ */
+import { patchJob } from "./docs.js";
+import { SCHEDULE_TASK_KIND } from "./task.js";
+/** Patch each parked schedule job; individual failures are logged and dropped. */
+export async function applyParkedJobs(harness, parked, context) {
+    if (parked.length === 0)
+        return;
+    let inspection;
+    try {
+        inspection = await harness.inspect(context);
+    }
+    catch (error) {
+        console.error("jobs: parked task inspection failed:", error);
+        return;
+    }
+    for (const task of parked) {
+        if (task.kind !== SCHEDULE_TASK_KIND)
+            continue;
+        try {
+            const record = inspection.tasks.find((candidate) => candidate.record.id === task.id)?.record;
+            if (record === undefined)
+                continue;
+            const jobId = record.input.jobId;
+            if (typeof jobId !== "string")
+                continue;
+            await patchJob(harness, jobId, (draft) => {
+                draft.state = "blocked";
+                draft.reason = "restart_limit";
+            }, context);
+        }
+        catch (error) {
+            console.error(`jobs: parked task ${String(task.id)} status patch failed:`, error);
+        }
+    }
+}

package/dist/jobs/task.js

@@ -1,7 +1,8 @@
 /**
  * Jobs Task 2 (spec §8.1 "The executor"): the `sigrun.schedule` task —
  * one long-lived background pi-durable task per ENABLED job, looping
- * `waiting` → `firing` → `waiting` over a durable `runtime.sleep`.
+ * `waiting` → `due` → `firing` → `waiting` over durable
+ * `runtime.sleepUntil` sleeps (pi-durable 1.4.0).
  *
  * The input is only `{jobId, hash, firstAt?}` (the plan's Global
  * Constraints): the task NEVER trusts its input's spec — EVERY phase
@@ -12,7 +13,12 @@
  * fire (`nextFireAt(schedule, now, tz)`).
  *
  * The phases:
- * - `waiting`: durable `runtime.sleep(nextAt)`. On wake: under
+ * - `waiting`: re-read + stale check, derive `nextAt`, patch the job's
+ *   status fields, then END with
+ *   `runtime.sleepUntil(nextAt, {phase:"due", nextAt})` — the task holds
+ *   no invocation while asleep; the scheduler wakes it from one
+ *   foreground timer. NOTHING runs after the sleep in this phase.
+ * - `due` (the old post-sleep body): re-read + stale → terminal; under
  *   `catchUp: "none"` and `now - nextAt > 60_000`, the missed slot is
  *   recorded `skipped` and the task re-commits `waiting` at the NEXT
  *   slot from NOW. Otherwise it commits `{phase: "firing", fireAt:
@@ -26,6 +32,13 @@
  *   completed (a past one-shot `at`).
  *
  * `abort` commits terminal (aborted) — the disable/delete path's signal.
+ * 1.4.0 makes an abort-requested SLEEPING task schedulable, so the
+ * handler also runs while the task sleeps.
+ *
+ * Records persisted mid-`waiting` by 0.2.x (pi-durable 1.3.0, whose
+ * in-process `runtime.sleep` committed no state) re-enter `waiting` on
+ * reopen and sleep durably. No migration code; the definition version
+ * stays 1.
  *
  * The record's status fields (`state`, `nextRun`, `lastRun`) ride
  * `patchJob` — small status edits, never version bumps.
@@ -43,8 +56,8 @@ export const SCHEDULE_TASK_VERSION = 1;
 const CATCHUP_GRACE_MS = 60_000;
 /**
  * The per-job executor. `deps` threads the harness + the injectable
- * clock (`deps.now` — the tests' lever; `runtime.sleep` reads the same
- * clock through the harness, which is why the phases re-check it).
+ * clock (`deps.now` — the tests' lever; `runtime.sleepUntil` deadlines
+ * live on the same harness clock, which is why the phases re-check it).
  */
 export function createScheduleTask(deps) {
     return defineTask({
@@ -80,9 +93,21 @@ export function createScheduleTask(deps) {
                     }
                     nextAt = first;
                 }
-                // The durable wait — the crash point the battery kills inside.
-                await runtime.sleep(nextAt, context);
-                // Re-check the record after the sleep (it may have changed).
+                // Patch the job's status fields BEFORE sleeping (D3): the
+                // record shows the durable deadline while the task sleeps.
+                await patchJob(deps.harness, task.input.jobId, (draft) => {
+                    draft.state = "waiting";
+                    delete draft.reason;
+                    draft.nextRun = new Date(nextAt).toISOString();
+                }, context);
+                // The durable wait — the phase ENDS here. The scheduler
+                // resumes the task at the `due` checkpoint when the harness
+                // clock reaches nextAt (or immediately when it already has).
+                await runtime.sleepUntil(nextAt, { phase: "due", nextAt }, context);
+            },
+            due: async (task, runtime, context) => {
+                const nextAt = task.state.checkpoint.nextAt;
+                // Re-check the record on wake (it may have changed).
                 const after = await readJob(deps.harness, task.input.jobId, context);
                 if (stale(after, task.input.hash)) {
                     await runtime.commit(() => ({
@@ -126,6 +151,7 @@ export function createScheduleTask(deps) {
                     }), context);
                     await patchJob(deps.harness, task.input.jobId, (draft) => {
                         draft.state = "waiting";
+                        delete draft.reason;
                         draft.nextRun = new Date(next).toISOString();
                     }, context);
                     return;
@@ -136,6 +162,7 @@ export function createScheduleTask(deps) {
                 }), context);
                 await patchJob(deps.harness, task.input.jobId, (draft) => {
                     draft.state = "firing";
+                    delete draft.reason;
                 }, context);
             },
             firing: async (task, runtime, context) => {
@@ -156,6 +183,7 @@ export function createScheduleTask(deps) {
                 if (next === undefined) {
                     await patchJob(deps.harness, task.input.jobId, (draft) => {
                         draft.state = "waiting";
+                        delete draft.reason;
                         delete draft.nextRun;
                     }, context);
                     await runtime.commit(() => ({
@@ -170,6 +198,7 @@ export function createScheduleTask(deps) {
                 }), context);
                 await patchJob(deps.harness, task.input.jobId, (draft) => {
                     draft.state = "waiting";
+                    delete draft.reason;
                     draft.nextRun = new Date(next).toISOString();
                 }, context);
             },
@@ -186,5 +215,5 @@ export function createScheduleTask(deps) {
 function stale(record, hash) {
     return (record === undefined || record.hash !== hash || record.enabled === false);
 }
-/** Awaiting `runtime.sleep` on the harness's background context. */
+/** The schedule task's commits run on the harness's background context. */
 export const SCHEDULE_CONTEXT = BACKGROUND_CONTEXT;