@frockbot/kernel-do 0.3.11 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-do",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,8 +12,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-composition": "0.3.11",
-    "@frockbot/kernel-contracts": "0.3.11",
+    "@frockbot/kernel-composition": "0.3.13",
+    "@frockbot/kernel-contracts": "0.3.13",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {

package/src/authority.ts

@@ -34,11 +34,13 @@ import {
 import {
   eventsForFailedRun,
   latestModelRequestJournalState,
+  latestModelRequestProviderV1,
   planBotRunRecovery,
   type ProviderReconcilesV1,
   repairedSessionLogV1,
   unresolvedModelRequestFailure,
 } from "./run-recovery.js";
+import { runLivenessV1, STALE_RUNNING_RUN_FAILURE_V1 } from "./run-liveness.js";
 import {
   BotTurnReconciliationRequiredError,
   BotTurnRecoveryRequiredError,
@@ -46,6 +48,7 @@ import {
 } from "./turn-errors.js";
 import {
   botConversationBaseSessionIdV1,
+  ConversationBusyError,
   conversationSessionIdV1,
   decodeConversationRecordV1,
   decodeStoredConversationV1,
@@ -254,7 +257,7 @@ export class BotDurableAuthority<Snapshot> {
     // Turn is durable either way and the alarm retries it; admission now
     // refuses or supersedes on its own terms.
     await this.recoverActiveRun().catch(() => undefined);
-    const replay = await this.settledRunResult(command);
+    const replay = await this.settledReplayResult(command);
     if (replay) return replay;
     const admission = await this.acceptRun(command);
     if (admission.kind === "queued") {
@@ -494,7 +497,7 @@ export class BotDurableAuthority<Snapshot> {
       // followed 500'd on the half-repaired record. The run is durable and
       // terminal by this point, and its own record says why it ended, so the
       // caller is handed that record and reads the reason from the transcript.
-      const settled = await this.settledReconciliationResult(runId);
+      const settled = await this.settledTerminalRunResult(runId);
       if (settled) return settled;
       throw error;
     }
@@ -505,7 +508,7 @@ export class BotDurableAuthority<Snapshot> {
    * resolving has reached a terminal state — whatever that state turned out to
    * be. Anything still open is not this method's to answer for.
    */
-  private async settledReconciliationResult(
+  private async settledTerminalRunResult(
     runId: string,
   ): Promise<BotTurnCompletion | undefined> {
     const run = this.codec.optional(
@@ -605,7 +608,7 @@ export class BotDurableAuthority<Snapshot> {
           modelState.status === "unresolved") &&
         !runWasDiscardedV1(durableRun)
       ) {
-        await this.requireRunReconciliation(
+        const settled = await this.parkOrSettleUnresolvedRun(
           command.runId,
           previous,
           events,
@@ -613,10 +616,19 @@ export class BotDurableAuthority<Snapshot> {
             ? unresolvedModelRequestFailure(events, modelState.request)
             : message,
         );
+        if (settled) return settled;
         throw new Error(message);
       }
       await this.failRun(command.runId, previous, events, message);
-      const settled = await this.discardedRunResult(command.runId);
+      // `settledTerminalRunResult`, not `discardedRunResult`: a Turn the Package failed
+      // outright — a provider 401, a step limit — reaches a `turn/end` and a
+      // durable `failed` record just as surely as a stopped one does, and
+      // rethrowing over the top of that settlement is what made the Worker log
+      // `Uncaught Error: Bot turn ended with outcome model-error: Model request
+      // failed (401)` and answer 500. The run is terminal by this point and its
+      // record says why; the caller is handed that record and the client reads
+      // the sentence for the outcome off it.
+      const settled = await this.settledTerminalRunResult(command.runId);
       if (settled) return settled;
       throw new Error(message);
     } finally {
@@ -746,7 +758,7 @@ export class BotDurableAuthority<Snapshot> {
           modelState.status === "unresolved") &&
         !runWasDiscardedV1(durableRun)
       ) {
-        await this.requireRunReconciliation(
+        const parked = await this.parkOrSettleUnresolvedRun(
           run.runId,
           previous,
           events,
@@ -754,10 +766,11 @@ export class BotDurableAuthority<Snapshot> {
             ? unresolvedModelRequestFailure(events, modelState.request)
             : message,
         );
+        if (parked) return parked;
         throw new Error(message);
       }
       await this.failRun(run.runId, previous, events, message);
-      const settled = await this.discardedRunResult(run.runId);
+      const settled = await this.settledTerminalRunResult(run.runId);
       if (settled) return settled;
       throw new Error(message);
     } finally {
@@ -781,7 +794,7 @@ export class BotDurableAuthority<Snapshot> {
     });
   }
 
-  private async settledRunResult(
+  private async settledReplayResult(
     command: OwnedBotTurnCommand,
   ): Promise<BotTurnCompletion | undefined> {
     const { runId } = command;
@@ -1046,9 +1059,10 @@ export class BotDurableAuthority<Snapshot> {
       const active = await transaction.get<string>(ACTIVE_RUN_KEY);
       const pending = await transaction.get<string>(PENDING_RUN_KEY);
       if (active || pending) {
-        throw new Error(
-          "This Bot is still working on a Turn. Wait for it to finish, then start a new conversation.",
-        );
+        // A typed refusal, not a bare Error: the Durable Object boundary turns
+        // this one case into a 409 value rather than letting it escape the
+        // object's entry frame as an uncaught exception.
+        throw new ConversationBusyError();
       }
       const current =
         decodeStoredConversationV1(
@@ -1135,6 +1149,81 @@ export class BotDurableAuthority<Snapshot> {
     return run;
   }
 
+  /**
+   * Whether a run is still working, settling its record when it is not.
+   *
+   * This is the only honest answer to "is this Bot busy", and both readers that
+   * ask — the sidebar's activity ring and the transcript's running Turn — go
+   * through here. `status === "running"` alone is a claim the record makes and
+   * nothing renews: a Turn that died mid-answer never wrote its own
+   * settlement, so idle Bots wore a pulsing ring for hours.
+   * {@link runLivenessV1} holds the rule; this adds the two things a pure rule
+   * cannot have.
+   *
+   * The first is the fence. A run this object is executing right now is alive
+   * by direct observation, whatever the durable record and the log look like
+   * mid-flush, and it is never judged or touched. The object is
+   * single-threaded, so `executingRunId` is exact for the run in this isolate,
+   * and a run executing in some *other* isolate cannot be at issue: the durable
+   * `active-run` marker admits one Turn at a time, and a record older than the
+   * Turn deadline is past the point where any isolate is still holding it.
+   *
+   * The second is the repair. A read that finds a dead record settles it rather
+   * than merely hiding it, so the ring goes out for every other reader too and
+   * the next message inherits a closed Turn instead of repairing one. The
+   * settlement is `failStoredRun`, exactly as recovery's is, which closes the
+   * open Turn in the log on the way and routes a run carrying a durable Stop or
+   * supersede intent to the outcome that intent already decided. It is
+   * idempotent — a second caller finds a terminal record and settles nothing —
+   * and the run-record write it commits is what publishes the `runs`
+   * invalidation the watching clients re-read on.
+   */
+  async resolveRunWorking(runId: string | undefined): Promise<boolean> {
+    if (runId === undefined) return false;
+    if (runId === this.executingRunId) return true;
+    const run = await this.readRun(runId);
+    if (!run || run.status !== "running") return false;
+    const sessionEvents = (
+      (await this.ctx.storage.get<SessionEvent[]>(LATEST_EVENTS_KEY)) ?? []
+    ).map(decodeSessionEvent);
+    if (runLivenessV1({ run, sessionEvents }).working) return true;
+    await this.settleStaleRun(runId);
+    return false;
+  }
+
+  /**
+   * Settles one run whose record says `running` and whose Turn is over.
+   *
+   * The verdict is taken again inside the transaction, against the record and
+   * the log as they are committed there, so a Turn that settled itself between
+   * the read above and this write is left exactly as it settled — and so is one
+   * that started executing in this object in the meantime.
+   */
+  private async settleStaleRun(runId: string): Promise<void> {
+    await this.ctx.storage.transaction(async (transaction) => {
+      if (runId === this.executingRunId) return;
+      const run = this.codec.optional(
+        await transaction.get<unknown>(`${RUN_PREFIX}${runId}`),
+      );
+      if (!run || run.runId !== runId || run.status !== "running") return;
+      const latest = (
+        (await transaction.get<SessionEvent[]>(LATEST_EVENTS_KEY)) ?? []
+      ).map(decodeSessionEvent);
+      if (runLivenessV1({ run, sessionEvents: latest }).working) return;
+      await failStoredRun(
+        this.codec,
+        transaction,
+        this.terminalKeys(runId),
+        runId,
+        latest.slice(0, run.previousEventCount),
+        run.events,
+        STALE_RUNNING_RUN_FAILURE_V1,
+        this.supersededPackageRecords(),
+      );
+      await this.refreshRecoveryAlarm(transaction);
+    });
+  }
+
   /** Reverse-ordered admission index page: `[cursor, runId]` entries. */
   async listRunIndex(query: {
     limit: number;
@@ -1650,6 +1739,48 @@ export class BotDurableAuthority<Snapshot> {
     });
   }
 
+  /**
+   * Settles a Turn whose model outcome is unknown, or parks it when somebody
+   * can still be asked — and never lets the uncertainty escape as a throw.
+   *
+   * This is ADR 0028 applied to the live path. Recovery already refuses to park
+   * a run whose provider offers no retrieval, because parking there is not
+   * caution but a dead end; the executing path did not, and the asymmetry is
+   * what produced the blocker. A model request that ran past its budget threw
+   * out of the Agent as an uncertain outcome, this method's predecessor parked
+   * the run and rethrew, and the `POST /turns` the composer was holding open
+   * answered 500 — so the person read "Couldn't reach the Bot. Check your
+   * connection", which blamed their network for a model that took too long,
+   * and the Bot stayed wedged behind a banner whose only possible resolution
+   * was the settlement we could have written here.
+   *
+   * When the provider does reconcile, nothing changes: the run parks, the
+   * caller still rethrows, and a later attempt can genuinely retrieve the
+   * effect. Uncertainty is never assumed away in either branch — the request is
+   * not re-sent, and every streamed word stays in the journal.
+   *
+   * Returns the settled completion when it settled, `undefined` when it parked.
+   */
+  private async parkOrSettleUnresolvedRun(
+    runId: string,
+    previous: SessionEvent[],
+    events: SessionEvent[],
+    reason: string,
+  ): Promise<BotTurnCompletion | undefined> {
+    const provider = latestModelRequestProviderV1(events);
+    const reconciles = this.hooks.providerReconciles ?? (() => true);
+    if (provider === undefined || reconciles(provider)) {
+      await this.requireRunReconciliation(runId, previous, events, reason);
+      return undefined;
+    }
+    // `failRun` runs the ordinary terminal settlement: the open Turn is closed
+    // with a `turn/end`, the partial text is kept, and the record carries the
+    // reason. The reason is a diagnostic for the debug surface — what the
+    // person reads is the client's own copy for the outcome.
+    await this.failRun(runId, previous, events, reason);
+    return this.settledTerminalRunResult(runId);
+  }
+
   /**
    * Starts the Turn that was waiting when the object last stopped.
    *

package/src/conversations.test.ts

@@ -9,7 +9,9 @@ import {
   type BotDurableAuthorityHooks,
 } from "./authority.ts";
 import {
+  ConversationBusyError,
   conversationSessionIdV1,
+  isConversationBusyV1,
   isConversationSessionIdV1,
 } from "./conversations.ts";
 import { MemoryStorage } from "./memory-storage.fixture.ts";
@@ -152,8 +154,15 @@ describe("starting a new conversation", () => {
     const probe = createAuthority(storage);
     storage.values.set("active-run", "run-9");
 
-    await expect(probe.authority.startConversation(IDENTITY)).rejects.toThrow(
-      /still working on a Turn/,
-    );
+    // Typed, not a bare Error: the Durable Object boundary keys on the name to
+    // turn this one case into a 409 value rather than letting it escape the
+    // object's entry frame as an uncaught exception.
+    const refusal = await probe.authority
+      .startConversation(IDENTITY)
+      .then(() => undefined)
+      .catch((error: unknown) => error);
+    expect(isConversationBusyV1(refusal)).toBe(true);
+    expect(refusal).toBeInstanceOf(ConversationBusyError);
+    expect((refusal as Error).message).toMatch(/still working on a Turn/);
   });
 });

package/src/conversations.ts

@@ -124,3 +124,40 @@ export function isConversationSessionIdV1(
   if (!sessionId.startsWith(`${base}#`)) return false;
   return /^[1-9][0-9]{0,6}$/.test(sessionId.slice(base.length + 1));
 }
+
+/**
+ * What a person is told when a new conversation is refused.
+ *
+ * The Turn that is running owns the event log the next Turn derives its
+ * request from, so a click may not pull it out from under it. That is a "not
+ * now", not a fault, and the sentence says what to do about it.
+ */
+export const CONVERSATION_BUSY_MESSAGE_V1 =
+  "This Bot is still working on a Turn. Wait for it to finish, then start a new conversation.";
+
+/**
+ * A refusal, told apart from a genuine failure.
+ *
+ * It exists so the Durable Object boundary can turn this one case into a value
+ * — a 409 the composer already understands — instead of letting it escape as
+ * an uncaught exception. An exception that crosses a DO's entry frame is
+ * logged by workerd as `Uncaught Error`, and the isolate that logs it has been
+ * seen to go down with a broken pipe immediately afterwards; in production the
+ * same sequence is a 500 where a 409 belonged.
+ */
+export class ConversationBusyError extends Error {
+  override readonly name = "ConversationBusyError";
+  constructor(message = CONVERSATION_BUSY_MESSAGE_V1) {
+    super(message);
+  }
+}
+
+/** Whether this is the "still working on a Turn" refusal, across bundles. */
+export function isConversationBusyV1(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    (error as { name?: unknown }).name === "ConversationBusyError"
+  );
+}

package/src/index.ts

@@ -4,6 +4,7 @@ export * from "./composition-failures.js";
 export * from "./conversations.js";
 export * from "./composition-store.js";
 export * from "./run-records.js";
+export * from "./run-liveness.js";
 export * from "./run-recovery.js";
 export * from "./run-terminal.js";
 export * from "./storage-keys.js";

package/src/model-timeout-settlement.test.ts

@@ -0,0 +1,265 @@
+// A model request that ran out of time settles the Turn instead of escaping.
+//
+// The blocker this file describes: a tool-heavy step against a real Flock AI
+// model crossed the gateway's sixty-second budget, the abort surfaced out of
+// the Agent as `Model response outcome is uncertain: The operation was aborted
+// due to timeout`, the authority parked the run on a reconciliation and
+// rethrew — and the `POST /api/bots/<bot>/turns` the composer was holding open
+// answered 500 after 65 seconds. On screen: "Couldn't reach the Bot. Check your
+// connection and try again", blaming a network that was fine, over a Bot that
+// stayed wedged behind a banner nothing could ever resolve.
+//
+// ADR 0028 already settled the question for recovery: park only when somebody
+// can be asked, and Flock AI keeps no addressable copy of a completion, so
+// nobody can. This is that rule on the live path.
+import { describe, expect, test } from "bun:test";
+import {
+  bootstrapGeneration,
+  type CompositionGenerationV1,
+} from "@frockbot/kernel-composition/generation";
+import {
+  MODEL_FIRST_BYTE_DEADLINE_REASON_V1,
+  type SessionEvent,
+} from "@frockbot/kernel-contracts";
+import {
+  BotDurableAuthority,
+  type BotDurableAuthorityHooks,
+  type OwnedBotTurnCommand,
+} from "./authority.ts";
+import { MemoryStorage } from "./memory-storage.fixture.ts";
+import {
+  BotTurnExecutionError,
+  BotTurnReconciliationRequiredError,
+} from "./turn-errors.ts";
+import { createStoredRunCodecV1, type StoredRunV1 } from "./run-records.ts";
+
+const codec = createStoredRunCodecV1<undefined>({
+  decodeRunId: (value) => value as string,
+  decodeConfigurationSnapshot: () => undefined,
+});
+
+const identity = { userId: "user-1", botId: "primary" };
+const SESSION_ID = "user-1:primary";
+
+/** Providers that keep an addressable copy of a completion. Neither does. */
+const RECONCILING_PROVIDERS = new Set(["foundation"]);
+
+function bootstrap(): Promise<CompositionGenerationV1> {
+  return bootstrapGeneration(
+    [
+      {
+        packageId: "shell",
+        specifier: "@frockbot/plugin-shell",
+        version: "0.0.1",
+        manifest: { id: "shell", version: "0.0.1" },
+      },
+    ],
+    { createdAt: "2026-09-03T00:00:00.000Z" },
+  );
+}
+
+function command(runId: string, text: string): OwnedBotTurnCommand {
+  return {
+    ...identity,
+    runId,
+    sessionId: SESSION_ID,
+    acceptedAt: "2026-09-03T00:00:01.000Z",
+    text,
+  };
+}
+
+/**
+ * An authority whose Package stalls its model request past the budget: it
+ * journals the request, streams a first line, then unwinds exactly as the
+ * Agent loop does on a deadline — a `model/reconciliation-required` carrying
+ * the deadline's own sentence, and no `turn/end`.
+ */
+function createAuthority(
+  storage: MemoryStorage,
+  provider: string,
+  options: { providerReconciles?: boolean; refuseWith?: string } = {},
+): BotDurableAuthority<undefined> {
+  const hooks: BotDurableAuthorityHooks<undefined> = {
+    resolveAdmissionSnapshot: () => Promise.resolve(undefined),
+    bootstrapComposition: () => bootstrap(),
+    admittedSnapshot: () => Promise.resolve(undefined),
+    ...(options.providerReconciles === undefined
+      ? { providerReconciles: (id: string) => RECONCILING_PROVIDERS.has(id) }
+      : { providerReconciles: () => options.providerReconciles as boolean }),
+    executeTurn: async (input) => {
+      let seq = input.previousEvents.length;
+      const appended: SessionEvent[] = [];
+      const persist = async (
+        ...events: Omit<SessionEvent, "seq" | "timestamp">[]
+      ) => {
+        const stamped = events.map(
+          (event) =>
+            ({
+              ...event,
+              seq: seq++,
+              timestamp: "2026-09-03T00:00:10.000Z",
+            }) as SessionEvent,
+        );
+        appended.push(...stamped);
+        await input.persistSessionEvents(input.command.sessionId, stamped);
+      };
+      await persist(
+        { type: "turn/start", turn: 1 } as never,
+        { type: "step/start", turn: 1, step: 1 } as never,
+        {
+          type: "user/message",
+          turn: 1,
+          step: 1,
+          messageId: "message-1",
+          text: input.command.text,
+        } as never,
+        {
+          type: "model/request",
+          turn: 1,
+          step: 1,
+          request: {
+            requestId: "request-1",
+            provider,
+            model: "@flock/auto",
+            system: "system",
+            messages: [{ role: "user", content: input.command.text }],
+            tools: [],
+          },
+        } as never,
+        {
+          type: "assistant/chunk",
+          turn: 1,
+          step: 1,
+          requestId: "request-1",
+          text: "On it — building it now.",
+        } as never,
+      );
+      // A provider that refused definitively — a revoked key answering 401 —
+      // reaches a real `turn/end`, the way the Agent loop settles a model
+      // error it never has to reconcile.
+      if (options.refuseWith) {
+        await persist(
+          {
+            type: "model/effect-not-started",
+            turn: 1,
+            step: 1,
+            requestId: "request-1",
+            reason: options.refuseWith,
+          } as never,
+          {
+            type: "step/end",
+            turn: 1,
+            step: 1,
+            outcome: "model-error",
+          } as never,
+          {
+            type: "turn/end",
+            turn: 1,
+            outcome: "model-error",
+            reason: options.refuseWith,
+          } as never,
+        );
+        throw new BotTurnExecutionError(
+          `Bot turn ended with outcome model-error: ${options.refuseWith}`,
+          appended,
+        );
+      }
+      const reason = `Model response outcome is uncertain: ${MODEL_FIRST_BYTE_DEADLINE_REASON_V1}`;
+      await persist({
+        type: "model/reconciliation-required",
+        turn: 1,
+        step: 1,
+        requestId: "request-1",
+        reason,
+      } as never);
+      throw new BotTurnReconciliationRequiredError(reason, appended);
+    },
+    notification: () => undefined,
+    scheduledDeadlines: () => Promise.resolve([]),
+    scheduledWorkInFlight: () => false,
+    deferScheduledWork: () => Promise.resolve(),
+    settleScheduledWork: () => Promise.resolve(),
+    interruptTurn: () => {},
+  };
+  return new BotDurableAuthority<undefined>({
+    state: { storage } as unknown as DurableObjectState,
+    codec,
+    hooks,
+  });
+}
+
+function storedRun(
+  storage: MemoryStorage,
+  runId: string,
+): StoredRunV1<undefined> {
+  return codec.require(storage.values.get(`run:${runId}`));
+}
+
+describe("a model request that ran out of time", () => {
+  test("settles the Turn and answers the caller instead of throwing", async () => {
+    const storage = new MemoryStorage();
+    const authority = createAuthority(storage, "flock-ai");
+
+    // The `POST /turns` the composer is holding open. It resolves — this is
+    // the whole defect: it used to reject, and the route answered 500.
+    const completion = await authority.run(command("run-1", "build me one"));
+
+    expect(completion.runId).toBe("run-1");
+    const run = storedRun(storage, "run-1");
+    expect(run.status).toBe("failed");
+    // The ordinary run-terminal path: the open Turn is closed rather than left
+    // for the next message to trip over.
+    const terminal = run.events.findLast((event) => event.type === "turn/end");
+    expect(terminal).toMatchObject({ turn: 1, outcome: "interrupted" });
+    // The words the person watched arrive are kept.
+    expect(run.events.some((event) => event.type === "assistant/chunk")).toBe(
+      true,
+    );
+    // The stored reason is the diagnostic, and it carries the sentence the
+    // client's copy layer reads back out of it.
+    expect(run.failure).toContain(MODEL_FIRST_BYTE_DEADLINE_REASON_V1);
+    // Nothing is left holding the Bot: the next message is admitted.
+    expect(storage.values.get("active-run")).toBeUndefined();
+  });
+
+  test("still parks when the provider can actually be asked", async () => {
+    const storage = new MemoryStorage();
+    const authority = createAuthority(storage, "foundation");
+
+    // A provider that keeps a durable copy loses nothing by waiting, so the
+    // uncertainty is preserved exactly as before and the caller still learns
+    // the Turn did not settle.
+    await expect(
+      authority.run(command("run-1", "build me one")),
+    ).rejects.toThrow();
+
+    const run = storedRun(storage, "run-1");
+    expect(run.status).toBe("reconciliation-required");
+    expect(run.events.some((event) => event.type === "turn/end")).toBe(false);
+  });
+
+  // The same leak, one layer over: a Turn that reached a real `turn/end` and a
+  // durable `failed` record was *still* rethrown, so the Worker logged
+  // `Uncaught Error: Bot turn ended with outcome model-error: Model request
+  // failed (401)` and the route answered 500 over a settlement that had
+  // already happened.
+  test("a provider that refused settles and answers, with no uncaught error", async () => {
+    const storage = new MemoryStorage();
+    const authority = createAuthority(storage, "flock-ai", {
+      refuseWith: "Model request failed (401)",
+    });
+
+    const completion = await authority.run(command("run-1", "hello"));
+
+    expect(completion.runId).toBe("run-1");
+    const run = storedRun(storage, "run-1");
+    expect(run.status).toBe("failed");
+    expect(
+      run.events.findLast((event) => event.type === "turn/end"),
+    ).toMatchObject({ outcome: "model-error" });
+    // The provider's own words stay on the record for the debug surface; the
+    // client maps the outcome to a sentence (`runFailureCopyV1`).
+    expect(run.failure).toContain("401");
+    expect(storage.values.get("active-run")).toBeUndefined();
+  });
+});

package/src/run-liveness.test.ts

@@ -0,0 +1,299 @@
+// An idle Bot wearing the activity ring.
+//
+// The sidebar's `working` flag was `readRun(newest).status === "running"`, and
+// nothing ever renews that field: a Turn that died mid-answer — a Worker torn
+// down, one of the "turn N started while turn N-1 is open" wedges — leaves a
+// record saying `running` for ever. Production had Bots that had been quiet for
+// hours pulsing as though they were mid-sentence.
+//
+// Liveness is three conditions, not one, and a reader that finds a record
+// failing them settles it rather than merely declining to draw a ring.
+import { describe, expect, test } from "bun:test";
+import {
+  bootstrapGeneration,
+  type CompositionGenerationV1,
+} from "@frockbot/kernel-composition/generation";
+import {
+  type SessionEvent,
+  TURN_DEADLINE_MS_V1,
+} from "@frockbot/kernel-contracts";
+import {
+  BotDurableAuthority,
+  type BotDurableAuthorityHooks,
+} from "./authority.ts";
+import { MemoryStorage } from "./memory-storage.fixture.ts";
+import { createStoredRunCodecV1, type StoredRunV1 } from "./run-records.ts";
+import {
+  runLivenessV1,
+  STALE_RUNNING_RUN_FAILURE_V1,
+  STALE_RUNNING_RUN_GRACE_MS_V1,
+} from "./run-liveness.ts";
+import {
+  ACTIVE_RUN_KEY,
+  IDENTITY_KEY,
+  LATEST_EVENTS_KEY,
+  RUN_PREFIX,
+  runIndexKey,
+} from "./storage-keys.ts";
+
+const NOW = Date.UTC(2026, 8, 3, 12, 0, 0);
+const ACCEPTED_AT = new Date(NOW - 1000).toISOString();
+
+function event(
+  seq: number,
+  type: SessionEvent["type"],
+  extra: Record<string, unknown> = {},
+): SessionEvent {
+  return {
+    type,
+    seq,
+    timestamp: new Date(NOW - 1000 + seq).toISOString(),
+    ...extra,
+  } as SessionEvent;
+}
+
+/** The events one Turn writes while it runs, opening the Turn and no more. */
+const openTurn: SessionEvent[] = [
+  event(0, "turn/start", { turn: 1 }),
+  event(1, "step/start", { turn: 1, step: 1 }),
+];
+
+/** The same log, with the ending somebody else wrote for it. */
+const closedTurn: SessionEvent[] = [
+  ...openTurn,
+  event(2, "step/end", { turn: 1, step: 1, outcome: "interrupted" }),
+  event(3, "turn/end", { turn: 1, outcome: "interrupted" }),
+];
+
+function run(
+  overrides: Partial<StoredRunV1<undefined>> = {},
+): StoredRunV1<undefined> {
+  return {
+    runId: "run-1",
+    commandFingerprint: "fingerprint",
+    sessionId: "user-1:primary",
+    acceptedAt: ACCEPTED_AT,
+    input: "hello",
+    events: openTurn,
+    effectAdmissions: [],
+    status: "running",
+    phase: "executing",
+    compositionGenerationId: "generation-1",
+    configurationSnapshot: undefined,
+    previousEventCount: 0,
+    ...overrides,
+  };
+}
+
+describe("whether a run marked running is working", () => {
+  test("a Turn admitted a moment ago is working", () => {
+    expect(
+      runLivenessV1({ run: run(), sessionEvents: openTurn, now: NOW }),
+    ).toEqual({ working: true, stale: false });
+  });
+
+  test("a settled run is not working, and owes no repair", () => {
+    expect(
+      runLivenessV1({
+        run: run({ status: "completed" }),
+        sessionEvents: closedTurn,
+        now: NOW,
+      }),
+    ).toEqual({ working: false, stale: false });
+  });
+
+  test("one still inside the deadline is left alone", () => {
+    expect(
+      runLivenessV1({
+        run: run(),
+        sessionEvents: openTurn,
+        now: NOW + TURN_DEADLINE_MS_V1 - 1000,
+      }),
+    ).toEqual({ working: true, stale: false });
+  });
+
+  test("the grace covers the unwind after the deadline fires", () => {
+    expect(
+      runLivenessV1({
+        run: run(),
+        sessionEvents: openTurn,
+        now: NOW + TURN_DEADLINE_MS_V1 + STALE_RUNNING_RUN_GRACE_MS_V1 - 1000,
+      }).working,
+    ).toBe(true);
+  });
+
+  test("one past the deadline and its grace is stale", () => {
+    expect(
+      runLivenessV1({
+        run: run(),
+        sessionEvents: openTurn,
+        now: NOW + TURN_DEADLINE_MS_V1 + STALE_RUNNING_RUN_GRACE_MS_V1 + 1000,
+      }),
+    ).toEqual({ working: false, stale: true, reason: "deadline" });
+  });
+
+  test("one whose Turn the log already closed is stale, however fresh", () => {
+    expect(
+      runLivenessV1({ run: run(), sessionEvents: closedTurn, now: NOW }),
+    ).toEqual({ working: false, stale: true, reason: "turn-closed" });
+  });
+
+  test("an earlier Turn's ending says nothing about this one", () => {
+    // The log ends closed because the *previous* Turn closed it, and this run
+    // has not journaled its own `turn/start` yet.
+    expect(
+      runLivenessV1({
+        run: run({ events: [], previousEventCount: closedTurn.length }),
+        sessionEvents: closedTurn,
+        now: NOW,
+      }),
+    ).toEqual({ working: true, stale: false });
+  });
+
+  test("an unreadable admission time is not evidence of death", () => {
+    expect(
+      runLivenessV1({
+        run: run({ acceptedAt: "not a timestamp" }),
+        sessionEvents: openTurn,
+        now: NOW + TURN_DEADLINE_MS_V1 * 100,
+      }).stale,
+    ).toBe(false);
+  });
+});
+
+const codec = createStoredRunCodecV1<undefined>({
+  decodeRunId: (value) => value as string,
+  decodeConfigurationSnapshot: () => undefined,
+});
+
+function bootstrap(): Promise<CompositionGenerationV1> {
+  return bootstrapGeneration(
+    [
+      {
+        packageId: "shell",
+        specifier: "@frockbot/plugin-shell",
+        version: "0.0.1",
+        manifest: { id: "shell", version: "0.0.1" },
+      },
+    ],
+    { createdAt: "2026-09-03T00:00:00.000Z" },
+  );
+}
+
+const hooks: BotDurableAuthorityHooks<undefined> = {
+  resolveAdmissionSnapshot: () => Promise.resolve(undefined),
+  bootstrapComposition: () => bootstrap(),
+  admittedSnapshot: () => Promise.resolve(undefined),
+  executeTurn: () => Promise.reject(new Error("no Turn should execute here")),
+  notification: () => undefined,
+  scheduledDeadlines: () => Promise.resolve([]),
+  scheduledWorkInFlight: () => false,
+  deferScheduledWork: () => Promise.resolve(),
+  settleScheduledWork: () => Promise.resolve(),
+};
+
+/**
+ * A Bot left holding exactly what production was left holding: a record that
+ * says `running`, an `active-run` marker pointing at it, and a durable log with
+ * the Turn it opened.
+ */
+async function seed(input: {
+  acceptedAt: string;
+  events: SessionEvent[];
+  log: SessionEvent[];
+}): Promise<{
+  storage: MemoryStorage;
+  authority: BotDurableAuthority<undefined>;
+}> {
+  const storage = new MemoryStorage();
+  const stored = run({ acceptedAt: input.acceptedAt, events: input.events });
+  await storage.put({
+    [`${RUN_PREFIX}${stored.runId}`]: stored,
+    [runIndexKey(stored.acceptedAt, stored.runId)]: stored.runId,
+    [ACTIVE_RUN_KEY]: stored.runId,
+    [LATEST_EVENTS_KEY]: input.log,
+    [IDENTITY_KEY]: { userId: "user-1", botId: "primary" },
+  });
+  const authority = new BotDurableAuthority<undefined>({
+    state: { storage } as unknown as DurableObjectState,
+    codec,
+    hooks,
+  });
+  return { storage, authority };
+}
+
+const longAgo = new Date(
+  Date.now() - TURN_DEADLINE_MS_V1 - STALE_RUNNING_RUN_GRACE_MS_V1 - 60_000,
+).toISOString();
+
+describe("the read that repairs what it finds", () => {
+  test("reports a fresh Turn as working and touches nothing", async () => {
+    const { storage, authority } = await seed({
+      acceptedAt: new Date().toISOString(),
+      events: openTurn,
+      log: openTurn,
+    });
+    expect(await authority.resolveRunWorking("run-1")).toBe(true);
+    expect(
+      (await storage.get<StoredRunV1<undefined>>(`${RUN_PREFIX}run-1`))?.status,
+    ).toBe("running");
+    expect(await storage.get<string>(ACTIVE_RUN_KEY)).toBe("run-1");
+  });
+
+  test("settles one that outlived the Turn deadline", async () => {
+    const { storage, authority } = await seed({
+      acceptedAt: longAgo,
+      events: openTurn,
+      log: openTurn,
+    });
+    expect(await authority.resolveRunWorking("run-1")).toBe(false);
+    const settled = await storage.get<StoredRunV1<undefined>>(
+      `${RUN_PREFIX}run-1`,
+    );
+    expect(settled?.status).toBe("failed");
+    expect(settled?.failure).toBe(STALE_RUNNING_RUN_FAILURE_V1);
+    // The Bot is free: nothing holds the object, and the next Turn admits
+    // against a log that reads as a complete history.
+    expect(await storage.get<string>(ACTIVE_RUN_KEY)).toBeUndefined();
+    const log = (await storage.get<SessionEvent[]>(LATEST_EVENTS_KEY)) ?? [];
+    expect(log.some((entry) => entry.type === "turn/end")).toBe(true);
+  });
+
+  test("settles one whose Turn the log already closed", async () => {
+    const { storage, authority } = await seed({
+      acceptedAt: new Date().toISOString(),
+      events: openTurn,
+      log: closedTurn,
+    });
+    expect(await authority.resolveRunWorking("run-1")).toBe(false);
+    expect(
+      (await storage.get<StoredRunV1<undefined>>(`${RUN_PREFIX}run-1`))?.status,
+    ).toBe("failed");
+  });
+
+  test("is idempotent: a second read settles nothing and still says no ring", async () => {
+    const { storage, authority } = await seed({
+      acceptedAt: longAgo,
+      events: openTurn,
+      log: openTurn,
+    });
+    expect(await authority.resolveRunWorking("run-1")).toBe(false);
+    const first = await storage.get<StoredRunV1<undefined>>(
+      `${RUN_PREFIX}run-1`,
+    );
+    expect(await authority.resolveRunWorking("run-1")).toBe(false);
+    expect(
+      await storage.get<StoredRunV1<undefined>>(`${RUN_PREFIX}run-1`),
+    ).toEqual(first!);
+  });
+
+  test("no run is no ring", async () => {
+    const { authority } = await seed({
+      acceptedAt: longAgo,
+      events: openTurn,
+      log: openTurn,
+    });
+    expect(await authority.resolveRunWorking(undefined)).toBe(false);
+    expect(await authority.resolveRunWorking("run-missing")).toBe(false);
+  });
+});

package/src/run-liveness.ts

@@ -0,0 +1,113 @@
+import {
+  type SessionEvent,
+  TURN_DEADLINE_MS_V1,
+} from "@frockbot/kernel-contracts";
+import type { StoredRunV1 } from "./run-records.js";
+
+/**
+ * How long past the Turn deadline a `running` record is still given the
+ * benefit of the doubt.
+ *
+ * The deadline is enforced by a timer inside the loop, and the settlement that
+ * follows it is a durable write on the far side of an abort: there is a real
+ * interval in which a Turn is legitimately still finishing after its clock ran
+ * out. A minute is far longer than that unwind takes and far shorter than the
+ * hours an abandoned record has been claiming to work.
+ */
+export const STALE_RUNNING_RUN_GRACE_MS_V1 = 60_000;
+
+/**
+ * What a run settled by this rule records, in the register ADR 0028 settles an
+ * unretrievable Turn in: what happened, and what to do about it.
+ */
+export const STALE_RUNNING_RUN_FAILURE_V1 =
+  "This Turn stopped without finishing and was settled when nothing was left to finish it. Try sending it again.";
+
+export interface RunLivenessV1 {
+  /** Whether the run may be shown as working — the activity ring's whole rule. */
+  readonly working: boolean;
+  /**
+   * Whether the record claims to be running and demonstrably is not, so the
+   * reader that asked owes it a terminal settlement.
+   */
+  readonly stale: boolean;
+  /** Why it is stale, for the failure a settlement records. Absent when it is not. */
+  readonly reason?: "deadline" | "turn-closed";
+}
+
+const NOT_RUNNING: RunLivenessV1 = { working: false, stale: false };
+
+/**
+ * The seq of the last `turn/start` this run wrote, or `undefined` when it has
+ * not opened a Turn in the durable log yet.
+ */
+function openedTurnSeqV1(events: readonly SessionEvent[]): number | undefined {
+  let seq: number | undefined;
+  for (const event of events) {
+    if (event.type === "turn/start") seq = event.seq;
+  }
+  return seq;
+}
+
+/**
+ * Whether a run is honestly still working.
+ *
+ * `status === "running"` was the whole test, and it is not one: a record is
+ * only ever moved off `running` by the settlement its own Turn performs, so
+ * every way a Turn can stop without settling — a Worker torn down mid-answer,
+ * the "turn N started while turn N-1 is open" wedges — left a record that says
+ * `running` for ever. The sidebar drew an activity ring off that field, so
+ * Bots that had been idle for hours pulsed as though they were mid-sentence.
+ *
+ * Three conditions, all of which must hold:
+ *
+ * - the record says `running`, which is necessary and was mistaken for
+ *   sufficient;
+ * - it has not outlived {@link TURN_DEADLINE_MS_V1} plus
+ *   {@link STALE_RUNNING_RUN_GRACE_MS_V1}, because the loop stops waiting at
+ *   the deadline and a record older than that cannot be a Turn anybody is
+ *   still running;
+ * - the durable session log does not already close the Turn it opened. A
+ *   `turn/end` at or after this run's own `turn/start` means something has
+ *   already written the Turn's ending — the admission repair, usually — and a
+ *   record still saying `running` behind a closed Turn is a leftover, not work.
+ *
+ * A run that has not written its `turn/start` yet is judged on the deadline
+ * alone: there is no Turn in the log to call closed, and the previous Turn's
+ * `turn/end` says nothing about this one.
+ *
+ * Pure, and deliberately so: it is consulted on a read path, on a settlement
+ * path, and in tests, and all three have to reach the same verdict.
+ */
+export function runLivenessV1(input: {
+  run:
+    Pick<StoredRunV1<unknown>, "status" | "acceptedAt" | "events"> | undefined;
+  /** The Bot's durable session log, as the run's own events sit inside it. */
+  sessionEvents: readonly SessionEvent[];
+  now?: number;
+  deadlineMs?: number;
+  graceMs?: number;
+}): RunLivenessV1 {
+  const run = input.run;
+  if (!run || run.status !== "running") return NOT_RUNNING;
+  const now = input.now ?? Date.now();
+  const deadline =
+    (input.deadlineMs ?? TURN_DEADLINE_MS_V1) +
+    (input.graceMs ?? STALE_RUNNING_RUN_GRACE_MS_V1);
+  const acceptedAt = Date.parse(run.acceptedAt);
+  // An unparseable timestamp is not evidence of death. The record is left
+  // alone rather than settled on a number nobody can read.
+  if (Number.isFinite(acceptedAt) && now - acceptedAt > deadline) {
+    return { working: false, stale: true, reason: "deadline" };
+  }
+  const opened = openedTurnSeqV1(run.events);
+  if (
+    opened !== undefined &&
+    input.sessionEvents.some(
+      (event) => event.type === "turn/end" && event.seq >= opened,
+    )
+  ) {
+    return { working: false, stale: true, reason: "turn-closed" };
+  }
+  return { working: true, stale: false };
+}

package/src/run-recovery.test.ts

@@ -35,7 +35,7 @@ const request: UnstampedEvent = {
   request: {
     requestId: "request-1",
     provider: "flock-ai",
-    model: "@flock/auto",
+    model: "@frock/auto",
     system: "Be concise.",
     messages: [{ role: "user", content: "hello" }],
     tools: [],

package/src/run-terminal-open-turn.test.ts

@@ -63,7 +63,7 @@ function interruptedJournal(): SessionEvent[] {
       request: {
         requestId: "request-1",
         provider: "flock-ai",
-        model: "@flock/auto",
+        model: "@frock/auto",
         system: "",
         messages: [],
         tools: [],