@frockbot/kernel-do 0.3.10 → 0.3.12

package/package.json

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

package/src/authority.ts

@@ -39,6 +39,7 @@ import {
   repairedSessionLogV1,
   unresolvedModelRequestFailure,
 } from "./run-recovery.js";
+import { runLivenessV1, STALE_RUNNING_RUN_FAILURE_V1 } from "./run-liveness.js";
 import {
   BotTurnReconciliationRequiredError,
   BotTurnRecoveryRequiredError,
@@ -46,6 +47,7 @@ import {
 } from "./turn-errors.js";
 import {
   botConversationBaseSessionIdV1,
+  ConversationBusyError,
   conversationSessionIdV1,
   decodeConversationRecordV1,
   decodeStoredConversationV1,
@@ -1046,9 +1048,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 +1138,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;

package/src/composition-failures.test.ts

@@ -486,6 +486,45 @@ describe("fail-closed Composition activation", () => {
     expect(activation.quarantined).toBe(false);
   });
 
+  test("the streak expires, so unrelated failures far apart are separate incidents", async () => {
+    // Three repair attempts are one sitting. Three failures months apart are
+    // three incidents, and quarantining the third would strand a Bot for
+    // something it had already recovered from twice.
+    const storage = new MemoryStorage();
+    const state = { storage } as unknown as DurableObjectState;
+    const store = new DurableCompositionStore({ state, bootstrap });
+    let clock = new Date("2026-09-01T00:00:00.000Z");
+    const failures = new DurableCompositionFailureLog({
+      state,
+      now: () => clock,
+      streakWindowMs: 60 * 60 * 1000,
+    });
+    const lastKnownGood = await store.current();
+
+    const outcomes: boolean[] = [];
+    for (const day of [1, 2, 3]) {
+      clock = new Date(`2026-09-0${day}T00:00:00.000Z`);
+      const generation = await authored(
+        lastKnownGood,
+        `2026-09-0${day}T00:00:00.000Z`,
+      );
+      await store.propose(generation, { pin: true });
+      const activation = await activateCompositionV1({
+        generationId: generation.generationId,
+        store: activationStore(store),
+        failures,
+        host: brokenHost(generation.generationId, "mount"),
+        signal: new AbortController().signal,
+        now: () => clock,
+      });
+      if (activation.status !== "failed-closed") throw new Error("expected");
+      outcomes.push(activation.quarantined);
+    }
+
+    // A day apart each time: never a streak, so never a quarantine.
+    expect(outcomes).toEqual([false, false, false]);
+  });
+
   test("a last known good that will not mount has nothing to fail into", async () => {
     const { store, failures, lastKnownGood } = await fixture();
     await expect(

package/src/composition-failures.ts

@@ -27,8 +27,23 @@ export interface DurableCompositionFailureLogOptions {
   now?(): Date;
   /** Consecutive failures that quarantine a generation. Defaults to three. */
   threshold?: number;
+  /** How long the Bot-wide streak stays alive. Defaults to one hour. */
+  streakWindowMs?: number;
 }
 
+/** The Bot's live failure streak: how many, and when the last one landed. */
+interface CompositionFailureStreakV1 {
+  count: number;
+  at: string;
+}
+
+/**
+ * One sitting. Repair attempts arrive minutes apart, so an hour is long enough
+ * to span a Bot's whole attempt to fix itself and short enough that yesterday's
+ * unrelated failure does not count towards today's quarantine.
+ */
+const COMPOSITION_FAILURE_STREAK_WINDOW_MS = 60 * 60 * 1000;
+
 /**
  * `CompositionFailureLog` over the Bot object's prefixed keys:
  * `composition:failure:<generationId>:<attempt>`,
@@ -45,11 +60,14 @@ export class DurableCompositionFailureLog implements CompositionFailureLog {
   private readonly ctx: DurableObjectState;
   private readonly now: () => Date;
   private readonly threshold: number;
+  private readonly streakWindowMs: number;
 
   constructor(options: DurableCompositionFailureLogOptions) {
     this.ctx = options.state;
     this.now = options.now ?? (() => new Date());
     this.threshold = options.threshold ?? COMPOSITION_QUARANTINE_THRESHOLD;
+    this.streakWindowMs =
+      options.streakWindowMs ?? COMPOSITION_FAILURE_STREAK_WINDOW_MS;
   }
 
   /** The attempt number is assigned here, inside the counter's transaction. */
@@ -70,14 +88,27 @@ export class DurableCompositionFailureLog implements CompositionFailureLog {
       // the model repairs by authoring a *new* generation, which is what it
       // always does — so without it the safeguard never fired and the
       // Composition grew one dead generation per repair attempt.
-      const streak =
-        ((await transaction.get<number>(COMPOSITION_FAILURE_STREAK_KEY)) ?? 0) +
-        1;
+      //
+      // The streak is bounded in time as well as reset by success. Three
+      // repair attempts are one sitting; three unrelated failures months apart
+      // are three separate incidents, and quarantining the third would strand
+      // a Bot for something it had already recovered from twice.
+      const at = this.now();
+      const stored = await transaction.get<CompositionFailureStreakV1>(
+        COMPOSITION_FAILURE_STREAK_KEY,
+      );
+      const continues =
+        stored !== undefined &&
+        at.getTime() - Date.parse(stored.at) <= this.streakWindowMs;
+      const streak = (continues ? stored.count : 0) + 1;
       const quarantined = attempt >= this.threshold || streak >= this.threshold;
       const writes: Record<string, unknown> = {
         [compositionFailureKey(generationId, attempt)]: recorded,
         [compositionFailureCountKey(generationId)]: attempt,
-        [COMPOSITION_FAILURE_STREAK_KEY]: streak,
+        [COMPOSITION_FAILURE_STREAK_KEY]: {
+          count: streak,
+          at: at.toISOString(),
+        } satisfies CompositionFailureStreakV1,
       };
       if (quarantined) {
         writes[compositionQuarantineKey(generationId)] =

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/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: [],