@loopingai/core 0.8.0 → 0.8.2

package/dist/a2a/deliver.d.ts

@@ -29,6 +29,40 @@ export interface DeliverTerminalOptions {
      * An agent with no managed children omits it and no `sweep` step appears.
      */
     sweep?: () => Promise<void>;
+    /**
+     * Prefix for this delivery's three step names. Empty by default, which is the
+     * only value an ordinary turn may use.
+     *
+     * **Step names are durable cache keys**, so this is not cosmetic. A workflow
+     * that delivers twice — an ordinary delivery, then
+     * {@link deliverAbandonedTask} from a `catch` above it — would otherwise call
+     * `step.do("complete")` a second time and be handed the *first* call's cached
+     * result, so the failed Task it built would never be written and the outcome
+     * would depend on Workflows' caching semantics for a step whose failure was
+     * caught. A distinct prefix makes the second delivery its own set of steps,
+     * where the guarded write decides the outcome as it is supposed to.
+     */
+    stepPrefix?: string;
+}
+/**
+ * Thrown when a delivery failed *after* its terminal Task was durably saved.
+ *
+ * The distinction it carries is the difference between "this turn produced
+ * nothing" and "this turn produced a result the gateway has not heard about
+ * yet", and only the first of those is an abandoned task.
+ *
+ * Without it, an ordinary delivery whose `notify` step exhausted its retries
+ * would unwind into an abandoned-task recovery, which would write a generic
+ * failure over a real answer. The guarded write refuses that now
+ * ({@link file://../db/models/tasks.ts}), but refusing it is not enough on its
+ * own: the recovery would then succeed at doing nothing, swallow a genuine
+ * callback failure, and log the word "abandoned" about a turn that completed.
+ * So the two work together — this stops the recovery being attempted, and the
+ * guard is the backstop for the narrow window where a `complete` step throws
+ * without saying whether its write applied.
+ */
+export declare class TaskAlreadyTerminalError extends Error {
+    constructor(cause: unknown);
 }
 /**
  * Persist a turn's terminal Task, then notify the gateway.
@@ -47,3 +81,79 @@ export interface DeliverTerminalOptions {
  * it. Everything it calls already lives here.
  */
 export declare function deliverTerminalTask(step: WorkflowStep, options: DeliverTerminalOptions): Promise<void>;
+/** What {@link deliverAbandonedTask} needs to end a turn nobody else will. */
+export interface AbandonedTaskOptions {
+    /** Which Task this is about, and where its callback goes. */
+    push: TurnPushContext;
+    /** The agent's card-signing key, for the callback JWT. */
+    signingKey: string;
+    /** The guarded write — same contract as {@link DeliverTerminalOptions.saveTask}. */
+    saveTask: (task: PlainTask) => Promise<boolean>;
+    /**
+     * The user-facing words. The host's, always: core ships no prompt copy and no
+     * user-facing copy, and a paraphrase invented at the failure site is exactly
+     * what this parameter exists to prevent.
+     */
+    text: string;
+    /** Best-effort child cleanup. Omitted by an agent that delegates to nothing. */
+    sweep?: () => Promise<void>;
+    /** Log prefix — conventionally the agent's tenant id. */
+    label?: string;
+}
+/**
+ * Turn an unrecoverable orchestration fault into a delivered failed Task.
+ *
+ * ## The failure this exists for
+ *
+ * A turn ends badly in two different ways. A **typed** failure — the models were
+ * tried and nothing usable came back — is a value, and the ordinary delivery
+ * path carries it. A **transient** fault instead throws, so the step retries and
+ * recovers without paying for a second inference. That is the right default.
+ *
+ * What neither covers is a transient fault that never stops being one. `step.do`
+ * retries a bounded number of times and then rethrows, and with nothing above it
+ * to catch that, the orchestration unwinds, the delivery path is never reached,
+ * and the Workflow instance errors with the Task still sitting in `working`. The
+ * user is told nothing at all — and because the instance dies mid-`run`, the
+ * runtime records it as *"your Worker's code had hung and would never generate a
+ * response"*, which reads like a bug in the workflow rather than a provider that
+ * was refusing every request.
+ *
+ * Observed exactly that way in a deployed agent on 2026-08-19: a turn step
+ * exhausted its four attempts against a rate-limited provider, and the agent
+ * simply went quiet.
+ *
+ * ## Three behaviours here are load-bearing
+ *
+ * **It resolves after a successful delivery — it does not rethrow.** Rethrowing
+ * would reproduce the very "hung Worker" record this exists to remove, and the
+ * instance genuinely has finished its job: the Task is terminal and the gateway
+ * has been told.
+ *
+ * **It rethrows the *original* `cause` when the delivery itself fails.**
+ * Swallowing there would mark the instance successful while the user got
+ * nothing — strictly worse than the erroring instance being replaced, because it
+ * would also be silent in the Workflows console. `cause` is what an operator
+ * needs to see, not the delivery's own secondary fault.
+ *
+ * **It refuses to run at all once a terminal Task exists.** A
+ * {@link TaskAlreadyTerminalError} means the ordinary delivery persisted its
+ * result and only the callback failed, so the original fault is rethrown and
+ * nothing is written. An earlier draft of this claimed the guarded write alone
+ * made that safe; it did not. The write refused only cancellation conflicts, so
+ * `completed → failed` applied cleanly and a turn that succeeded would have been
+ * rewritten as a generic failure because a webhook was flaky. The guard now
+ * refuses any terminal-over-different-terminal write as a backstop, and this
+ * check is what stops the attempt being made in the first place — without it the
+ * recovery would quietly succeed at doing nothing, swallowing a real callback
+ * failure and logging "abandoned" about a completed turn.
+ *
+ * ## Why it is exported rather than private to `/round`
+ *
+ * `runHandleTask` wraps itself in it, so every round agent gets this without
+ * asking. But an agent whose turn is a single inference writes its own workflow
+ * body and has the identical exposure — and the alternative to exporting this is
+ * that each such host reimplements the delivery, which is precisely the mistake
+ * this function was extracted from.
+ */
+export declare function deliverAbandonedTask(step: WorkflowStep, cause: unknown, options: AbandonedTaskOptions): Promise<void>;

package/dist/a2a/deliver.js

@@ -1,4 +1,30 @@
+import { buildFailedTask } from "./notify.js";
 import { createPushChannel } from "./push.js";
+/**
+ * Thrown when a delivery failed *after* its terminal Task was durably saved.
+ *
+ * The distinction it carries is the difference between "this turn produced
+ * nothing" and "this turn produced a result the gateway has not heard about
+ * yet", and only the first of those is an abandoned task.
+ *
+ * Without it, an ordinary delivery whose `notify` step exhausted its retries
+ * would unwind into an abandoned-task recovery, which would write a generic
+ * failure over a real answer. The guarded write refuses that now
+ * ({@link file://../db/models/tasks.ts}), but refusing it is not enough on its
+ * own: the recovery would then succeed at doing nothing, swallow a genuine
+ * callback failure, and log the word "abandoned" about a turn that completed.
+ * So the two work together — this stops the recovery being attempted, and the
+ * guard is the backstop for the narrow window where a `complete` step throws
+ * without saying whether its write applied.
+ */
+export class TaskAlreadyTerminalError extends Error {
+    constructor(cause) {
+        super("the terminal Task was saved; the callback after it failed", {
+            cause
+        });
+        this.name = "TaskAlreadyTerminalError";
+    }
+}
 /**
  * Persist a turn's terminal Task, then notify the gateway.
  *
@@ -16,7 +42,8 @@ import { createPushChannel } from "./push.js";
  * it. Everything it calls already lives here.
  */
 export async function deliverTerminalTask(step, options) {
-    const task = await step.do("complete", async () => {
+    const at = options.stepPrefix ?? "";
+    const task = await step.do(`${at}complete`, async () => {
         const terminal = options.terminal();
         return (await options.saveTask(terminal)) ? terminal : null;
     });
@@ -28,7 +55,7 @@ export async function deliverTerminalTask(step, options) {
     if (options.sweep) {
         const sweep = options.sweep;
         try {
-            await step.do("sweep", async () => {
+            await step.do(`${at}sweep`, async () => {
                 await sweep();
             });
         }
@@ -43,7 +70,116 @@ export async function deliverTerminalTask(step, options) {
     // terminal messageId is deterministic and the gateway is idempotent and
     // single-use, so retries are safe. If it ultimately fails, the gateway's own
     // reaction backstop clears the pending marker.
-    await step.do("notify", async () => {
-        await createPushChannel(options.signingKey, options.push).deliver(task);
+    //
+    // Wrapped, because by this line the Task is durably terminal: anything that
+    // fails from here is a callback that did not land, never a turn that produced
+    // nothing. See {@link TaskAlreadyTerminalError}.
+    try {
+        await step.do(`${at}notify`, async () => {
+            await createPushChannel(options.signingKey, options.push).deliver(task);
+        });
+    }
+    catch (err) {
+        throw new TaskAlreadyTerminalError(err);
+    }
+}
+/**
+ * The step-name prefix an abandoned delivery runs under.
+ *
+ * Its own namespace so it can never collide with the ordinary delivery's — see
+ * {@link DeliverTerminalOptions.stepPrefix}.
+ */
+const ABANDONED_PREFIX = "abandoned:";
+/**
+ * Turn an unrecoverable orchestration fault into a delivered failed Task.
+ *
+ * ## The failure this exists for
+ *
+ * A turn ends badly in two different ways. A **typed** failure — the models were
+ * tried and nothing usable came back — is a value, and the ordinary delivery
+ * path carries it. A **transient** fault instead throws, so the step retries and
+ * recovers without paying for a second inference. That is the right default.
+ *
+ * What neither covers is a transient fault that never stops being one. `step.do`
+ * retries a bounded number of times and then rethrows, and with nothing above it
+ * to catch that, the orchestration unwinds, the delivery path is never reached,
+ * and the Workflow instance errors with the Task still sitting in `working`. The
+ * user is told nothing at all — and because the instance dies mid-`run`, the
+ * runtime records it as *"your Worker's code had hung and would never generate a
+ * response"*, which reads like a bug in the workflow rather than a provider that
+ * was refusing every request.
+ *
+ * Observed exactly that way in a deployed agent on 2026-08-19: a turn step
+ * exhausted its four attempts against a rate-limited provider, and the agent
+ * simply went quiet.
+ *
+ * ## Three behaviours here are load-bearing
+ *
+ * **It resolves after a successful delivery — it does not rethrow.** Rethrowing
+ * would reproduce the very "hung Worker" record this exists to remove, and the
+ * instance genuinely has finished its job: the Task is terminal and the gateway
+ * has been told.
+ *
+ * **It rethrows the *original* `cause` when the delivery itself fails.**
+ * Swallowing there would mark the instance successful while the user got
+ * nothing — strictly worse than the erroring instance being replaced, because it
+ * would also be silent in the Workflows console. `cause` is what an operator
+ * needs to see, not the delivery's own secondary fault.
+ *
+ * **It refuses to run at all once a terminal Task exists.** A
+ * {@link TaskAlreadyTerminalError} means the ordinary delivery persisted its
+ * result and only the callback failed, so the original fault is rethrown and
+ * nothing is written. An earlier draft of this claimed the guarded write alone
+ * made that safe; it did not. The write refused only cancellation conflicts, so
+ * `completed → failed` applied cleanly and a turn that succeeded would have been
+ * rewritten as a generic failure because a webhook was flaky. The guard now
+ * refuses any terminal-over-different-terminal write as a backstop, and this
+ * check is what stops the attempt being made in the first place — without it the
+ * recovery would quietly succeed at doing nothing, swallowing a real callback
+ * failure and logging "abandoned" about a completed turn.
+ *
+ * ## Why it is exported rather than private to `/round`
+ *
+ * `runHandleTask` wraps itself in it, so every round agent gets this without
+ * asking. But an agent whose turn is a single inference writes its own workflow
+ * body and has the identical exposure — and the alternative to exporting this is
+ * that each such host reimplements the delivery, which is precisely the mistake
+ * this function was extracted from.
+ */
+export async function deliverAbandonedTask(step, cause, options) {
+    // Nothing was abandoned: the ordinary delivery already persisted a terminal
+    // Task and only its callback failed. Rethrow the fault that actually
+    // happened, so the instance still errors exactly as it did before any
+    // recovery existed and the gateway's own backstop clears the pending marker.
+    //
+    // Checked **here** rather than in each caller's `catch` on purpose. This whole
+    // change exists because a recovery every host had to remember to wire was one
+    // three hosts forgot; a caveat every host had to remember to check would be
+    // the same mistake a second time.
+    if (cause instanceof TaskAlreadyTerminalError)
+        throw cause.cause;
+    const label = options.label ?? "agent";
+    // Logged before anything is attempted: if the delivery below also fails, this
+    // line is the only record of what actually went wrong.
+    console.error(`[${label}] task abandoned after retries were exhausted`, {
+        taskId: options.push.taskId,
+        error: String(cause)
     });
+    try {
+        await deliverTerminalTask(step, {
+            push: options.push,
+            signingKey: options.signingKey,
+            saveTask: options.saveTask,
+            terminal: () => buildFailedTask(options.push.taskId, options.push.contextId, options.text),
+            sweep: options.sweep,
+            stepPrefix: ABANDONED_PREFIX
+        });
+    }
+    catch (deliveryFailed) {
+        console.error(`[${label}] could not deliver the failed Task`, {
+            taskId: options.push.taskId,
+            error: String(deliveryFailed)
+        });
+        throw cause;
+    }
 }

package/dist/a2a/index.d.ts

@@ -22,7 +22,7 @@ export { A2A_JWS_ALG, audienceFor, endpointUrl, jwksUrl } from "@loopingai/a2a-p
 export { IDENTITY_CLAIM, TENANT_CLAIM, GatewayAuthError, bearerToken, normalizeGatewayOrigins, verifyGatewayToken, type GatewayIdentity, type VerifyOptions } from "./verify.js";
 export { A2A_RPC_PATH, buildBaseCard, signCard, wireCard, parsePrivateJwk, publicCardJwks, type AgentManifest, type BuildCardOptions, type CardSigningConfig, type WireAgentCard } from "./card.js";
 export { NOTIFICATION_TOKEN_HEADER, buildSubmittedTask, buildWorkingTask, buildCompletedTask, buildFailedTask, buildNoReplyCompletedTask, signCallbackJwt, postNotification } from "./notify.js";
-export { deliverTerminalTask, type DeliverTerminalOptions } from "./deliver.js";
+export { deliverTerminalTask, deliverAbandonedTask, TaskAlreadyTerminalError, type DeliverTerminalOptions, type AbandonedTaskOptions } from "./deliver.js";
 export { signCallerToken, type CallerTokenOptions } from "./caller-token.js";
 export { SelfOrigin } from "./self-origin.js";
 export { callerContext } from "./caller.js";

package/dist/a2a/index.js

@@ -22,7 +22,7 @@ export { A2A_JWS_ALG, audienceFor, endpointUrl, jwksUrl } from "@loopingai/a2a-p
 export { IDENTITY_CLAIM, TENANT_CLAIM, GatewayAuthError, bearerToken, normalizeGatewayOrigins, verifyGatewayToken } from "./verify.js";
 export { A2A_RPC_PATH, buildBaseCard, signCard, wireCard, parsePrivateJwk, publicCardJwks } from "./card.js";
 export { NOTIFICATION_TOKEN_HEADER, buildSubmittedTask, buildWorkingTask, buildCompletedTask, buildFailedTask, buildNoReplyCompletedTask, signCallbackJwt, postNotification } from "./notify.js";
-export { deliverTerminalTask } from "./deliver.js";
+export { deliverTerminalTask, deliverAbandonedTask, TaskAlreadyTerminalError } from "./deliver.js";
 export { signCallerToken } from "./caller-token.js";
 export { SelfOrigin } from "./self-origin.js";
 export { callerContext } from "./caller.js";

package/dist/db/models/tasks.d.ts

@@ -78,6 +78,19 @@ export declare function makeTasks(db: DB): {
      * `canceled` onto a `submitted`/`working` row, or re-writing it onto an
      * already-`canceled` one, stays allowed: that is how the a2a-js handler's own
      * cancel branch records the cancellation.
+     *
+     * **And no terminal row may be replaced by a *different* terminal state.**
+     * The two rules above were written about cancellation and between them left
+     * `completed → failed` wide open, which is not hypothetical: a workflow whose
+     * `notify` step exhausts its retries throws *after* `complete` durably saved
+     * a completed Task, and an abandoned-task recovery above it would then write
+     * a generic failure over a real answer and post a callback contradicting it.
+     * A turn that succeeded would be recorded as having failed because a webhook
+     * was flaky.
+     *
+     * Same terminal state re-written is still allowed, and must be: a Workflow
+     * replay legitimately re-runs `complete` and saves what it already saved, and
+     * refusing that would suppress the callback that replay exists to send.
      */
     save(task: Task): boolean;
     /**

package/dist/db/models/tasks.js

@@ -15,6 +15,21 @@ function nowIso() {
 export function stateOf(task) {
     return task.status?.state ?? TaskState.TASK_STATE_UNSPECIFIED;
 }
+/**
+ * The states a task never leaves.
+ *
+ * `INPUT_REQUIRED` and `AUTH_REQUIRED` are deliberately absent: a turn parked on
+ * either is waiting, not finished, and will move again.
+ */
+const TERMINAL_STATES = new Set([
+    TaskState.TASK_STATE_COMPLETED,
+    TaskState.TASK_STATE_FAILED,
+    TaskState.TASK_STATE_CANCELED,
+    TaskState.TASK_STATE_REJECTED
+]);
+function isTerminal(state) {
+    return TERMINAL_STATES.has(state);
+}
 /**
  * Query methods for the `notify_tasks` table (async A2A task state).
  *
@@ -143,6 +158,19 @@ export function makeTasks(db) {
          * `canceled` onto a `submitted`/`working` row, or re-writing it onto an
          * already-`canceled` one, stays allowed: that is how the a2a-js handler's own
          * cancel branch records the cancellation.
+         *
+         * **And no terminal row may be replaced by a *different* terminal state.**
+         * The two rules above were written about cancellation and between them left
+         * `completed → failed` wide open, which is not hypothetical: a workflow whose
+         * `notify` step exhausts its retries throws *after* `complete` durably saved
+         * a completed Task, and an abandoned-task recovery above it would then write
+         * a generic failure over a real answer and post a callback contradicting it.
+         * A turn that succeeded would be recorded as having failed because a webhook
+         * was flaky.
+         *
+         * Same terminal state re-written is still allowed, and must be: a Workflow
+         * replay legitimately re-runs `complete` and saves what it already saved, and
+         * refusing that would suppress the callback that replay exists to send.
          */
         save(task) {
             const existing = readOne(task.id);
@@ -162,6 +190,11 @@ export function makeTasks(db) {
                 existingState !== TaskState.TASK_STATE_CANCELED) {
                 return false;
             }
+            if (isTerminal(existingState) &&
+                isTerminal(incomingState) &&
+                incomingState !== existingState) {
+                return false;
+            }
             upsert(task);
             return true;
         },

package/dist/job/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@loopingai/core/job` — a long job a Durable Object owns through its alarm.
+ *
+ * **The sibling of `@loopingai/core/alarm`, and the pairing is the point.**
+ * `WakeMap` owns *when* an object wakes; this owns *what a job owes on waking*.
+ * Neither depends on the other's reason for existing, and both are useful to a
+ * plain `DurableObject` rather than only to a `LoopingAgent` — which is why they
+ * are subpaths and not part of the agent machinery.
+ *
+ * **Mechanism only.** Nothing here knows what a job *does*: no command, no
+ * container, no filesystem, no vendor library. A consumer supplies the handle
+ * and the meaning; this supplies the four rules that are wrong in the same way
+ * every time — arming before the work starts, one job at a time, a drain that
+ * can outlive its job, and a job nobody is draining. See {@link JobLifecycle}.
+ *
+ * Deliberately **not** called `task`. Core already has a `Task` — the A2A one,
+ * with its own lifecycle, its own guarded writes and its own table — and two
+ * unrelated meanings in one namespace is a cost paid forever by every reader.
+ */
+export { isRearmable, isRunning, type DoneJob, type FailedJob, type IdleJob, type JobState, type RunningJob, type SkippedJob } from "./state.js";
+export { JobLifecycle, type JobContext, type JobHandle, type JobLifecycleOptions, type JobResult } from "./lifecycle.js";

package/dist/job/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@loopingai/core/job` — a long job a Durable Object owns through its alarm.
+ *
+ * **The sibling of `@loopingai/core/alarm`, and the pairing is the point.**
+ * `WakeMap` owns *when* an object wakes; this owns *what a job owes on waking*.
+ * Neither depends on the other's reason for existing, and both are useful to a
+ * plain `DurableObject` rather than only to a `LoopingAgent` — which is why they
+ * are subpaths and not part of the agent machinery.
+ *
+ * **Mechanism only.** Nothing here knows what a job *does*: no command, no
+ * container, no filesystem, no vendor library. A consumer supplies the handle
+ * and the meaning; this supplies the four rules that are wrong in the same way
+ * every time — arming before the work starts, one job at a time, a drain that
+ * can outlive its job, and a job nobody is draining. See {@link JobLifecycle}.
+ *
+ * Deliberately **not** called `task`. Core already has a `Task` — the A2A one,
+ * with its own lifecycle, its own guarded writes and its own table — and two
+ * unrelated meanings in one namespace is a cost paid forever by every reader.
+ */
+export { isRearmable, isRunning } from "./state.js";
+export { JobLifecycle } from "./lifecycle.js";

package/dist/job/lifecycle.d.ts

@@ -0,0 +1,176 @@
+import type { WakeMap } from "../alarm/index.js";
+import { type JobState, type RunningJob } from "./state.js";
+/**
+ * The choreography around a long job a Durable Object owns through its alarm.
+ *
+ * The job itself — what command, where, and what its output means — belongs to
+ * the owner. What lives here is the part that is the same every time and is
+ * wrong in the same four ways every time:
+ *
+ * 1. **Arming writes `running` before anything runs.** The alarm has not fired
+ *    yet, and a `done` record in that window lets a gated caller through against
+ *    a workspace that is not ready. Writing `running` first also makes arming
+ *    self-limiting: the next call sees it and stops.
+ * 2. **One job at a time**, guarded by a read that goes *through* the staleness
+ *    bound — so a `running` record left by a dead isolate resolves rather than
+ *    blocking every retry forever.
+ * 3. **A drain can outlive the job it watched.** `ctx.waitUntil` keeps running
+ *    after the RPC returns, and a late drain writing its verdict over a record
+ *    describing a *live* job is silent corruption. {@link generation} is the
+ *    marker that makes it harmless.
+ * 4. **Nobody may be draining at all.** A watch intent re-attaches to a job
+ *    whose isolate went away mid-flight.
+ *
+ * What is deliberately *not* here is the drain loop. Two real consumers want
+ * different ones — an install runs to completion under `waitUntil` and writes a
+ * single verdict; a coding-agent run is drained in bounded windows and reports
+ * partial progress between them. They share the four rules above and nothing
+ * below them, so the loop stays with the owner.
+ *
+ * ## Storage keys
+ *
+ * Derived from {@link JobLifecycleOptions.id} so one object can own several
+ * jobs. For `id: "install"` they come out as `install`, `install:armed`,
+ * `install:last-armed`, `install:context`, and the wake intents `install-run`
+ * and `install-watch` — the exact keys the predecessor wrote by hand, which is
+ * why adopting this needs no storage migration.
+ */
+/** What a job's result looks like to the lifecycle. Deliberately minimal. */
+export interface JobResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/** A running command, reduced to what the lifecycle needs of it. */
+export interface JobHandle {
+    result(): Promise<JobResult>;
+    [Symbol.dispose](): void;
+}
+/**
+ * The per-job record naming what is running and *which* run it is.
+ *
+ * `startedAt` is the generation marker, so it is the one required field: a drain
+ * compares the stamp it captured against the stamp on disk, and a mismatch means
+ * it has been superseded and has nothing useful left to say.
+ */
+export interface JobContext {
+    startedAt: number;
+}
+export interface JobLifecycleOptions {
+    /** Namespaces every key and intent. Also the state record's own key. */
+    id: string;
+    storage: DurableObjectStorage;
+    wake: WakeMap;
+    /**
+     * How long a `running` record may stand before it is presumed dead.
+     *
+     * Measured from `startedAt` and compared against the job's own timeout plus
+     * this, never against this alone — the point is to outlast a job that is
+     * merely slow, and only then to declare one that is gone.
+     */
+    staleMs?: number;
+    /** How often the watch intent re-checks a job nobody is draining. */
+    watchMs?: number;
+    /**
+     * The floor between two arming attempts.
+     *
+     * Without it a job that cannot start re-arms on every call into the object.
+     */
+    armCooldownMs?: number;
+}
+export declare class JobLifecycle<TExtra extends object = Record<never, never>, TContext extends JobContext = JobContext> {
+    #private;
+    /** `install` — the state record. */
+    readonly stateKey: string;
+    /** `install:armed` — the stamp the arming path wrote, for the alarm to match. */
+    readonly armedKey: string;
+    /** `install:last-armed` — the cooldown floor. */
+    readonly lastArmedKey: string;
+    /** `install:context` — where the generation marker lives. */
+    readonly contextKey: string;
+    /** `install-run` — the intent that *runs* a job. */
+    readonly runIntent: string;
+    /** `install-watch` — the intent that re-attaches to one nobody is draining. */
+    readonly watchIntent: string;
+    constructor(options: JobLifecycleOptions);
+    /** The raw record, with no staleness repair. `idle` when nothing is written. */
+    read(): Promise<JobState<TExtra>>;
+    write(state: JobState<TExtra>): Promise<void>;
+    context(): Promise<TContext | undefined>;
+    /**
+     * Record which run this is, **before** spawning.
+     *
+     * The order is the whole point: a drain captures `startedAt` after the spawn,
+     * so a context written afterwards would let two runs share a generation.
+     */
+    putContext(context: TContext): Promise<void>;
+    /**
+     * Hand a cold job to the alarm, if one is not already pending.
+     *
+     * Returns the stamp it armed with, or `undefined` when it declined — the
+     * caller needs the stamp because it is what the alarm must present to
+     * {@link claim} to get past the single-flight guard.
+     *
+     * An arming caller must **not** own the run. The predecessor handed one to
+     * `ctx.waitUntil` from a gate poll that returned in milliseconds, and the
+     * drain was disposed underneath it mid-command. An alarm invocation belongs to
+     * the object rather than to any request, so nothing it awaits can be cut short.
+     */
+    arm(placeholder: Omit<RunningJob<TExtra>, "state" | "startedAt">): Promise<number | undefined>;
+    /** The stamp {@link arm} wrote, so the alarm can recognise its own placeholder. */
+    armedAt(): Promise<number | undefined>;
+    clearArmed(): Promise<void>;
+    /**
+     * Decide whether a new run may start.
+     *
+     * `takeOverArmedAt` is the one exemption and it is narrow on purpose. The
+     * alarm's placeholder *is* a `running` record for a job that has not started,
+     * so the alarm has to pass its own guard — and only its own. Matching the
+     * exact stamp it wrote is what stops this becoming "take over any running
+     * job", which is the displacement bug the guard exists to prevent: three
+     * callers spawning under one exec id in fifty seconds, each displacing the
+     * last, every displaced drain still attached and still writing verdicts.
+     *
+     * Applies the staleness bound **itself**, rather than trusting the caller to
+     * have repaired the record first. An earlier draft took an
+     * "already-repaired" state and said so in prose, which enforced nothing: the
+     * repaired and raw types are identical, so a caller passing a raw read got a
+     * `running` record that could never be claimed and a job wedged forever.
+     * `timeoutMs` is the job's own budget; see {@link isStale}.
+     */
+    claim(state: JobState<TExtra>, timeoutMs: number, takeOverArmedAt?: number): {
+        ok: true;
+    } | {
+        ok: false;
+        current: RunningJob<TExtra>;
+    };
+    /**
+     * Whether a `running` record has stood long enough to be presumed dead.
+     *
+     * `timeoutMs` is the job's own budget; the bound is that plus `staleMs`, so a
+     * job that is merely slow is never declared gone.
+     */
+    isStale(state: RunningJob<TExtra>, timeoutMs: number, now?: number): boolean;
+    /** Arm the watchdog that re-attaches to a job nobody is draining. */
+    armWatch(now?: number): Promise<void>;
+    /**
+     * Disarm the watchdog.
+     *
+     * Never call this from a superseded drain: the watchdog belongs to whichever
+     * run owns the record *now*, and clearing it there disarms the one recovery
+     * path the live run has.
+     */
+    clearWatch(): Promise<void>;
+    /**
+     * A predicate a drain calls before every write, to ask whether it still owns
+     * the record.
+     *
+     * Captures the stamp once, at drain start, and compares it against disk each
+     * time. The closure also latches, so a drain can ask afterwards whether it was
+     * superseded — which is what decides if it may touch the watchdog.
+     */
+    generation(startedAt: number): {
+        stillMine: () => Promise<boolean>;
+        superseded: () => boolean;
+    };
+}

package/dist/job/lifecycle.js

@@ -0,0 +1,230 @@
+import { isRearmable } from "./state.js";
+/**
+ * `WakeMap`'s own storage row, spelled here rather than imported.
+ *
+ * Importing `WAKE_KEY` would be a *value* import from `../alarm`, and this
+ * module is careful to reach that package only for types — a runtime edge would
+ * pull the whole alarm module into any bundle that imports `/job`. So the string
+ * is duplicated, and `lifecycle.spec.ts` asserts it still equals `WAKE_KEY`;
+ * specs never ship, so the check costs nothing at runtime and fails loudly if
+ * the two ever drift.
+ */
+const WAKE_MAP_KEY = "wake";
+const DEFAULT_STALE_MS = 5 * 60_000;
+const DEFAULT_WATCH_MS = 60_000;
+const DEFAULT_ARM_COOLDOWN_MS = 5 * 60_000;
+export class JobLifecycle {
+    #o;
+    /** `install` — the state record. */
+    stateKey;
+    /** `install:armed` — the stamp the arming path wrote, for the alarm to match. */
+    armedKey;
+    /** `install:last-armed` — the cooldown floor. */
+    lastArmedKey;
+    /** `install:context` — where the generation marker lives. */
+    contextKey;
+    /** `install-run` — the intent that *runs* a job. */
+    runIntent;
+    /** `install-watch` — the intent that re-attaches to one nobody is draining. */
+    watchIntent;
+    constructor(options) {
+        /**
+         * An id is a storage key, so a bad one is not a bad name — it is a write
+         * landing on somebody else's row.
+         *
+         * `"wake"` is the one that matters and the reason this guard exists: it is
+         * `WakeMap`'s single row, so a job with that id would overwrite the whole
+         * intent map on its first state write, and the `wake.set()` immediately
+         * after would then read job fields as intents. Every pending wake-up on the
+         * object — not just this job's — silently stops happening.
+         *
+         * Empty is rejected for the same reason one level down: it yields the
+         * intents `-run` and `-watch`, which two differently-broken callers would
+         * share.
+         */
+        if (!options.id)
+            throw new Error("a job id must be a non-empty string");
+        if (options.id === WAKE_MAP_KEY) {
+            throw new Error(`"${WAKE_MAP_KEY}" is reserved: it is WakeMap's storage row, and a job ` +
+                `with that id would overwrite every pending intent on this object`);
+        }
+        this.#o = {
+            ...options,
+            staleMs: options.staleMs ?? DEFAULT_STALE_MS,
+            watchMs: options.watchMs ?? DEFAULT_WATCH_MS,
+            armCooldownMs: options.armCooldownMs ?? DEFAULT_ARM_COOLDOWN_MS
+        };
+        this.stateKey = options.id;
+        this.armedKey = `${options.id}:armed`;
+        this.lastArmedKey = `${options.id}:last-armed`;
+        this.contextKey = `${options.id}:context`;
+        this.runIntent = `${options.id}-run`;
+        this.watchIntent = `${options.id}-watch`;
+    }
+    // --- the record ------------------------------------------------------------
+    /** The raw record, with no staleness repair. `idle` when nothing is written. */
+    async read() {
+        return ((await this.#o.storage.get(this.stateKey)) ??
+            { state: "idle" });
+    }
+    async write(state) {
+        await this.#o.storage.put(this.stateKey, state);
+    }
+    async context() {
+        return await this.#o.storage.get(this.contextKey);
+    }
+    /**
+     * Record which run this is, **before** spawning.
+     *
+     * The order is the whole point: a drain captures `startedAt` after the spawn,
+     * so a context written afterwards would let two runs share a generation.
+     */
+    async putContext(context) {
+        await this.#o.storage.put(this.contextKey, context);
+    }
+    // --- arming ----------------------------------------------------------------
+    /**
+     * Hand a cold job to the alarm, if one is not already pending.
+     *
+     * Returns the stamp it armed with, or `undefined` when it declined — the
+     * caller needs the stamp because it is what the alarm must present to
+     * {@link claim} to get past the single-flight guard.
+     *
+     * An arming caller must **not** own the run. The predecessor handed one to
+     * `ctx.waitUntil` from a gate poll that returned in milliseconds, and the
+     * drain was disposed underneath it mid-command. An alarm invocation belongs to
+     * the object rather than to any request, so nothing it awaits can be cut short.
+     */
+    async arm(placeholder) {
+        const state = await this.read();
+        if (!isRearmable(state))
+            return undefined;
+        const lastArmed = await this.#o.storage.get(this.lastArmedKey);
+        if (lastArmed !== undefined &&
+            Date.now() - lastArmed < this.#o.armCooldownMs)
+            return undefined;
+        const armedAt = Date.now();
+        await this.write({
+            ...placeholder,
+            state: "running",
+            startedAt: armedAt
+        });
+        await this.#o.storage.put(this.armedKey, armedAt);
+        // Kept even if the scheduling below fails, deliberately: a floor that only
+        // applied to *successful* arming would let a persistently failing schedule
+        // re-arm on every call into the object, which is what it exists to prevent.
+        await this.#o.storage.put(this.lastArmedKey, armedAt);
+        /**
+         * The placeholder and the alarm that owns it are two writes, and between
+         * them is the one window where this can strand a job: a `running` record no
+         * run intent points at, which every later {@link arm} then declines to
+         * replace *because* it is running.
+         *
+         * The staleness bound in {@link claim} would eventually free it, but only
+         * after a full timeout — so unwind instead, and leave the record exactly as
+         * re-armable as it was found.
+         */
+        try {
+            await this.#o.wake.set({ key: this.runIntent, notBefore: armedAt });
+        }
+        catch (err) {
+            await this.write(state);
+            await this.#o.storage.delete(this.armedKey).catch(() => { });
+            throw err;
+        }
+        return armedAt;
+    }
+    /** The stamp {@link arm} wrote, so the alarm can recognise its own placeholder. */
+    async armedAt() {
+        return await this.#o.storage.get(this.armedKey);
+    }
+    async clearArmed() {
+        await this.#o.storage.delete(this.armedKey);
+    }
+    // --- the single-flight guard ------------------------------------------------
+    /**
+     * Decide whether a new run may start.
+     *
+     * `takeOverArmedAt` is the one exemption and it is narrow on purpose. The
+     * alarm's placeholder *is* a `running` record for a job that has not started,
+     * so the alarm has to pass its own guard — and only its own. Matching the
+     * exact stamp it wrote is what stops this becoming "take over any running
+     * job", which is the displacement bug the guard exists to prevent: three
+     * callers spawning under one exec id in fifty seconds, each displacing the
+     * last, every displaced drain still attached and still writing verdicts.
+     *
+     * Applies the staleness bound **itself**, rather than trusting the caller to
+     * have repaired the record first. An earlier draft took an
+     * "already-repaired" state and said so in prose, which enforced nothing: the
+     * repaired and raw types are identical, so a caller passing a raw read got a
+     * `running` record that could never be claimed and a job wedged forever.
+     * `timeoutMs` is the job's own budget; see {@link isStale}.
+     */
+    claim(state, timeoutMs, takeOverArmedAt) {
+        if (state.state !== "running")
+            return { ok: true };
+        // The alarm presenting its own placeholder — the one narrow exemption.
+        if (state.startedAt === takeOverArmedAt)
+            return { ok: true };
+        // A record whose isolate is gone must not block every later run.
+        if (this.isStale(state, timeoutMs))
+            return { ok: true };
+        return { ok: false, current: state };
+    }
+    // --- staleness and re-attach -------------------------------------------------
+    /**
+     * Whether a `running` record has stood long enough to be presumed dead.
+     *
+     * `timeoutMs` is the job's own budget; the bound is that plus `staleMs`, so a
+     * job that is merely slow is never declared gone.
+     */
+    isStale(state, timeoutMs, now = Date.now()) {
+        return now - state.startedAt > timeoutMs + this.#o.staleMs;
+    }
+    /** Arm the watchdog that re-attaches to a job nobody is draining. */
+    async armWatch(now = Date.now()) {
+        await this.#o.wake.set({
+            key: this.watchIntent,
+            notBefore: now + this.#o.watchMs
+        });
+    }
+    /**
+     * Disarm the watchdog.
+     *
+     * Never call this from a superseded drain: the watchdog belongs to whichever
+     * run owns the record *now*, and clearing it there disarms the one recovery
+     * path the live run has.
+     */
+    async clearWatch() {
+        await this.#o.wake.clear(this.watchIntent).catch(() => { });
+    }
+    // --- generation --------------------------------------------------------------
+    /**
+     * A predicate a drain calls before every write, to ask whether it still owns
+     * the record.
+     *
+     * Captures the stamp once, at drain start, and compares it against disk each
+     * time. The closure also latches, so a drain can ask afterwards whether it was
+     * superseded — which is what decides if it may touch the watchdog.
+     */
+    generation(startedAt) {
+        let superseded = false;
+        return {
+            stillMine: async () => {
+                // The latch is checked *before* the read, not after. Ownership is not
+                // recoverable: once another run has owned this record, a stamp that
+                // happens to match again does not hand it back, and a drain that
+                // regained write access here would be the corruption the marker exists
+                // to prevent.
+                if (superseded)
+                    return false;
+                const now = await this.context();
+                if (now?.startedAt === startedAt)
+                    return true;
+                superseded = true;
+                return false;
+            },
+            superseded: () => superseded
+        };
+    }
+}

package/dist/job/state.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The record an alarm-owned job writes about itself, and the shape a gate reads.
+ *
+ * This is the contract between two halves that do not own each other: the
+ * Durable Object *runs* the job, and something else — a shell tool, a subagent
+ * executor — refuses to proceed while one is in flight. A shape they agreed on
+ * informally would drift, and the drift shows up as a command running halfway
+ * through the job it was supposed to wait for.
+ *
+ * ## Why `TExtra` intersects rather than nests
+ *
+ * The obvious generic is `{ state: "running"; meta: TExtra }`. It is wrong here,
+ * and expensively so: every existing reader spells the job's own field at the
+ * top level (`status.command`), so nesting would rewrite every read site and
+ * every spec assertion in both consumers to buy nothing. Intersecting keeps
+ * `JobState<{ command: string }>` *byte-identical* to the hand-written union it
+ * replaces, which is what makes adopting this a type change and not a refactor.
+ *
+ * The cost of the choice is that `TExtra` must not collide with the field names
+ * below. That is a real constraint, and it is why they are named for the
+ * mechanism (`startedAt`, `finishedAt`, `exitCode`) rather than for any job.
+ */
+/**
+ * A job's durable state.
+ *
+ * Five variants, and the two that look redundant are not:
+ *
+ * - `idle` — nothing has ever run. There is no context recording *where* or
+ *   *what*, so a caller cannot re-drive it; that is the owner's job.
+ * - `skipped` — something looked and decided there was nothing to do. Terminal
+ *   and *correct*, which is why it is not `done`: a gate must not treat a
+ *   deliberate no-op as a failure to retry, and an arming path must not re-drive
+ *   it forever.
+ * - `running` — in flight, or believed to be. Never trusted without the
+ *   staleness bound in {@link JobLifecycle.claim}, because the isolate that
+ *   wrote it may be long gone.
+ * - `done` / `failed` — terminal, carrying enough to explain the outcome without
+ *   the caller reaching for the transcript.
+ */
+/** Nothing has ever run; no context exists naming what would. */
+export type IdleJob = {
+    state: "idle";
+};
+/** Something looked and decided there was nothing to do. Terminal and correct. */
+export type SkippedJob = {
+    state: "skipped";
+    reason: string;
+};
+/** In flight, or believed to be. Never trusted without the staleness bound. */
+export type RunningJob<TExtra = Record<never, never>> = {
+    state: "running";
+    startedAt: number;
+    tail?: string;
+} & TExtra;
+export type DoneJob<TExtra = Record<never, never>> = {
+    state: "done";
+    exitCode: number;
+    finishedAt: number;
+    ms: number;
+    tail?: string;
+} & TExtra;
+export type FailedJob<TExtra = Record<never, never>> = {
+    state: "failed";
+    finishedAt: number;
+    error: string;
+    exitCode?: number;
+    tail?: string;
+} & TExtra;
+/**
+ * A job's durable state.
+ *
+ * The variants are named types rather than inlined into the union because
+ * `Extract<JobState<TExtra>, { state: "running" }>` cannot narrow while `TExtra`
+ * is generic — the compiler has no way to prove `DoneJob & TExtra` does not also
+ * carry `state: "running"`. Naming them is what lets a caller say
+ * `RunningJob<TExtra>` and get its fields.
+ */
+export type JobState<TExtra = Record<never, never>> = IdleJob | SkippedJob | RunningJob<TExtra> | DoneJob<TExtra> | FailedJob<TExtra>;
+/**
+ * Whether a state is one a new run may start from.
+ *
+ * `done` and `failed` both qualify, and the second was a gap worth closing in
+ * the predecessor: arming used to require `done`, so one bad run left a record
+ * that declined to re-arm forever — one failure poisoning every task after it.
+ *
+ * `skipped` and `idle` are excluded for different reasons. `skipped` means the
+ * answer is already correct and permanent. `idle` means no context exists naming
+ * what to run, so there is nothing to re-drive.
+ */
+export declare function isRearmable<TExtra extends object>(state: JobState<TExtra>): boolean;
+/** Whether a state claims a job is in flight. Never conclusive on its own. */
+export declare function isRunning<TExtra extends object>(state: JobState<TExtra>): state is RunningJob<TExtra>;

package/dist/job/state.js

@@ -0,0 +1,40 @@
+/**
+ * The record an alarm-owned job writes about itself, and the shape a gate reads.
+ *
+ * This is the contract between two halves that do not own each other: the
+ * Durable Object *runs* the job, and something else — a shell tool, a subagent
+ * executor — refuses to proceed while one is in flight. A shape they agreed on
+ * informally would drift, and the drift shows up as a command running halfway
+ * through the job it was supposed to wait for.
+ *
+ * ## Why `TExtra` intersects rather than nests
+ *
+ * The obvious generic is `{ state: "running"; meta: TExtra }`. It is wrong here,
+ * and expensively so: every existing reader spells the job's own field at the
+ * top level (`status.command`), so nesting would rewrite every read site and
+ * every spec assertion in both consumers to buy nothing. Intersecting keeps
+ * `JobState<{ command: string }>` *byte-identical* to the hand-written union it
+ * replaces, which is what makes adopting this a type change and not a refactor.
+ *
+ * The cost of the choice is that `TExtra` must not collide with the field names
+ * below. That is a real constraint, and it is why they are named for the
+ * mechanism (`startedAt`, `finishedAt`, `exitCode`) rather than for any job.
+ */
+/**
+ * Whether a state is one a new run may start from.
+ *
+ * `done` and `failed` both qualify, and the second was a gap worth closing in
+ * the predecessor: arming used to require `done`, so one bad run left a record
+ * that declined to re-arm forever — one failure poisoning every task after it.
+ *
+ * `skipped` and `idle` are excluded for different reasons. `skipped` means the
+ * answer is already correct and permanent. `idle` means no context exists naming
+ * what to run, so there is nothing to re-drive.
+ */
+export function isRearmable(state) {
+    return state.state === "done" || state.state === "failed";
+}
+/** Whether a state claims a job is in flight. Never conclusive on its own. */
+export function isRunning(state) {
+    return state.state === "running";
+}

package/dist/round/workflow.d.ts

@@ -102,6 +102,13 @@ export interface HandleTaskDeps {
      * with no change here.
      */
     signingKey: string;
+    /**
+     * Log prefix for the abandoned-task line, conventionally the agent's tenant
+     * id. Optional because nothing here needs it to work — but a deployment that
+     * mounts several agents on one Worker gets one log stream, and without this
+     * every one of them reports going quiet under the same name.
+     */
+    label?: string;
 }
 /**
  * The caller's agent DO stub — every phase runs through it.
@@ -112,19 +119,29 @@ export interface HandleTaskDeps {
  */
 type AgentStub = DurableObjectStub<RoundAgentBase>;
 /**
- * The orchestration itself, split from the `WorkflowEntrypoint` wiring so it can
- * be driven with a fake `step` in tests (workerd forbids constructing a
+ * The orchestration, split from the `WorkflowEntrypoint` wiring so it can be
+ * driven with a fake `step` in tests (workerd forbids constructing a
  * `WorkflowEntrypoint` outside the runtime) — and so a second agent can reuse it
  * with different deps.
  *
- * Every `step.do` return here is a small projection — a status, an id, a reply.
- * Never a Subtask row: a step return is capped at 1 MiB and a Subtask carries
- * verbatim history snapshots, so the rows stay in the DO and the Workflow carries
- * references to them.
+ * ## What the wrapper adds, and why it is not the host's job
+ *
+ * Core distinguishes two ways a turn ends badly. A **typed** failure is a value
+ * and {@link deliver} carries it. A **transient** fault throws, so the step
+ * retries and recovers from the durable rows without paying for a second
+ * inference. Neither covers a transient fault that never stops being one: the
+ * step exhausts its retries, {@link orchestrate} unwinds, the delivery below is
+ * never reached, and the instance errors with the Task still in `working` — the
+ * user told nothing, and the runtime recording a hang. See
+ * {@link deliverAbandonedTask}, which was written for a deployed agent that did
+ * exactly this on 2026-08-19.
  *
- * **Step names are durable cache keys.** Everything inside the round loop carries
- * its round for that reason: `turn:<round>`, `deadline:<round>`, `scan:<round>`,
- * `cancel:<round>`. Renaming one silently re-runs its effect on replay.
+ * This is caught **here** rather than left to each `WorkflowEntrypoint` because
+ * everything the recovery needs is already in {@link HandleTaskDeps}: the stub
+ * (typed on `RoundAgentBase`, so `saveTask` and `sweepTaskChildren` are both
+ * reachable), `policy.copy.taskFailed`, and `signingKey`. A host has nothing to
+ * add — so asking it to remember buys nothing and costs exactly what it cost the
+ * starter, where three of four agents never wrote the `catch` at all.
  */
 export declare function runHandleTask(p: HandleTaskParams, step: WorkflowStep, deps: HandleTaskDeps): Promise<void>;
 export {};

package/dist/round/workflow.js

@@ -1,6 +1,6 @@
 import { CHUNK_STEP, MAX_CHUNKS_PER_BRANCH, STEP_TIMEOUT_MS } from "../platform.js";
 import { buildCompletedTask, buildFailedTask } from "../a2a/notify.js";
-import { deliverTerminalTask } from "../a2a/deliver.js";
+import { deliverAbandonedTask, deliverTerminalTask } from "../a2a/deliver.js";
 /**
  * The same retries, and a timeout a **round** can actually be measured against.
  *
@@ -31,11 +31,67 @@ function turnStep(config) {
     };
 }
 /**
- * The orchestration itself, split from the `WorkflowEntrypoint` wiring so it can
- * be driven with a fake `step` in tests (workerd forbids constructing a
+ * The orchestration, split from the `WorkflowEntrypoint` wiring so it can be
+ * driven with a fake `step` in tests (workerd forbids constructing a
  * `WorkflowEntrypoint` outside the runtime) — and so a second agent can reuse it
  * with different deps.
  *
+ * ## What the wrapper adds, and why it is not the host's job
+ *
+ * Core distinguishes two ways a turn ends badly. A **typed** failure is a value
+ * and {@link deliver} carries it. A **transient** fault throws, so the step
+ * retries and recovers from the durable rows without paying for a second
+ * inference. Neither covers a transient fault that never stops being one: the
+ * step exhausts its retries, {@link orchestrate} unwinds, the delivery below is
+ * never reached, and the instance errors with the Task still in `working` — the
+ * user told nothing, and the runtime recording a hang. See
+ * {@link deliverAbandonedTask}, which was written for a deployed agent that did
+ * exactly this on 2026-08-19.
+ *
+ * This is caught **here** rather than left to each `WorkflowEntrypoint` because
+ * everything the recovery needs is already in {@link HandleTaskDeps}: the stub
+ * (typed on `RoundAgentBase`, so `saveTask` and `sweepTaskChildren` are both
+ * reachable), `policy.copy.taskFailed`, and `signingKey`. A host has nothing to
+ * add — so asking it to remember buys nothing and costs exactly what it cost the
+ * starter, where three of four agents never wrote the `catch` at all.
+ */
+export async function runHandleTask(p, step, deps) {
+    try {
+        await orchestrate(p, step, deps);
+    }
+    catch (cause) {
+        // Everything this needs is already in `deps` — which is the argument for it
+        // living here rather than in each host's `catch`. Four agents in the starter
+        // called this function and only one had written that `catch`; the other three
+        // carried the 2026-08-19 failure silently. A guard nobody can forget is worth
+        // more than a helper everybody must remember.
+        await deliverAbandonedTask(step, cause, {
+            push: {
+                taskId: p.taskId,
+                contextId: p.contextId,
+                pushUrl: p.pushUrl,
+                pushToken: p.pushToken,
+                jku: p.jku
+            },
+            signingKey: deps.signingKey,
+            // Resolved inside each closure, never hoisted — see {@link ResolveAgent}.
+            saveTask: (task) => deps.resolveAgent(p.identity).saveTask(task),
+            // The round never got far enough to say *which* credential or model was at
+            // fault, so `failureCopy` has nothing to answer and the policy's own words
+            // are the honest ones. The diagnostic is logged instead.
+            text: deps.policy.copy.taskFailed,
+            sweep: async () => {
+                await deps.resolveAgent(p.identity).sweepTaskChildren(p.taskId);
+            },
+            label: deps.label
+        });
+    }
+}
+/**
+ * The orchestration proper — every ordinary outcome ends inside here, and
+ * anything that escapes is what {@link runHandleTask} turns into a delivered
+ * failure.
+ *
  * Every `step.do` return here is a small projection — a status, an id, a reply.
  * Never a Subtask row: a step return is capped at 1 MiB and a Subtask carries
  * verbatim history snapshots, so the rows stay in the DO and the Workflow carries
@@ -43,9 +99,11 @@ function turnStep(config) {
  *
  * **Step names are durable cache keys.** Everything inside the round loop carries
  * its round for that reason: `turn:<round>`, `deadline:<round>`, `scan:<round>`,
- * `cancel:<round>`. Renaming one silently re-runs its effect on replay.
+ * `cancel:<round>`. Renaming one silently re-runs its effect on replay — and the
+ * recovery path in {@link runHandleTask} runs under its own prefix for the same
+ * reason, so a second delivery cannot be handed this one's cached results.
  */
-export async function runHandleTask(p, step, deps) {
+async function orchestrate(p, step, deps) {
     const limits = deps.config.mainAgentLimits;
     // Pre-work. Routing is pure, so it needs no step of its own — but it is
     // deliberately *not* resolved here into a value the steps below close over.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopingai/core",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Shared, mandatory foundation for Looping agents on Cloudflare Workers: zero-trust A2A, durable task lifecycle, delegation and subagent runtime, test harness.",
   "keywords": [
     "a2a",
@@ -61,6 +61,10 @@
       "types": "./dist/alarm/index.d.ts",
       "import": "./dist/alarm/index.js"
     },
+    "./job": {
+      "types": "./dist/job/index.d.ts",
+      "import": "./dist/job/index.js"
+    },
     "./round": {
       "types": "./dist/round/index.d.ts",
       "import": "./dist/round/index.js"
@@ -108,7 +112,8 @@
     "test:watch": "vitest",
     "verify:exports": "node scripts/verify-exports.mjs",
     "prepack": "npm run build && npm run verify:exports",
-    "prepublishOnly": "npm run check && npm test && npm run verify:exports"
+    "prepublishOnly": "npm run check && npm test && npm run verify:exports",
+    "prepare": "husky"
   },
   "dependencies": {
     "@a2a-js/sdk": "^1.0.0",
@@ -144,6 +149,7 @@
     "ai": "^7.0.52",
     "drizzle-kit": "^0.31.10",
     "eslint": "^10.8.0",
+    "husky": "^9.1.7",
     "prettier": "^3.9.6",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.66.0",