@frockbot/kernel-do 0.3.16 → 0.3.18

package/package.json

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

package/src/applets.test.ts

@@ -58,7 +58,12 @@ describe("Applet ids", () => {
     expect(appletIdV1("user-42", "d".repeat(32))).toBe(
       `user-42.${"d".repeat(32)}`,
     );
-    expect(() => appletIdV1("User-42", "d".repeat(32))).toThrow();
+    // A User id as Better Auth mints it: mixed case, 32 characters.
+    expect(appletIdV1("vgpqfaCcwnPlzjYdb2mIfNcOW1YV0SkG", "d".repeat(32))).toBe(
+      `vgpqfaCcwnPlzjYdb2mIfNcOW1YV0SkG.${"d".repeat(32)}`,
+    );
+    expect(() => appletIdV1("user 42", "d".repeat(32))).toThrow();
+    expect(() => appletIdV1("", "d".repeat(32))).toThrow();
     expect(() => appletIdV1("user-42", "nope")).toThrow();
   });
 

package/src/applets.ts

@@ -413,7 +413,9 @@ async function sha256Hex(value: string): Promise<string> {
 }
 
 const APPLET_SECRET_V1 = /^[0-9a-f]{32}$/;
-const APPLET_OWNER_V1 = /^[a-z0-9][a-z0-9-]{0,63}$/;
+// A User id as the auth layer mints it: mixed case, underscore allowed. Must
+// agree with `APPLET_ID_V1`'s owner half.
+const APPLET_OWNER_V1 = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$/;
 
 /**
  * `<publicUserId>.<random>` — ADR 0015's share-id shape, reused.

package/src/authority.ts

@@ -16,6 +16,7 @@ import {
   botTurnCommandFingerprintV1,
   defaultRunLaneV1,
   storedRunAdmissionV1,
+  storedRunLaneV1,
   storedRunEventFieldsV2,
   storedRunRecordV2,
   storedRunSubagentRoleV1,
@@ -67,6 +68,8 @@ import {
   CONVERSATION_INDEX_KEY,
   CONVERSATION_KEY,
   MAX_LISTED_CONVERSATIONS,
+  MAX_PENDING_AGENT_RUNS_V1,
+  PENDING_AGENT_RUN_PREFIX,
   PENDING_RUN_KEY,
   IDENTITY_KEY,
   LATEST_EVENTS_KEY,
@@ -77,6 +80,7 @@ import {
   RUN_ADMISSION_FENCE_PREFIX,
   RUN_INDEX_PREFIX,
   RUN_PREFIX,
+  pendingAgentRunKey,
   runIndexKey,
   storedRunAdmissionFences,
 } from "./storage-keys.js";
@@ -390,12 +394,28 @@ export class BotDurableAuthority<Snapshot> {
     return this.ctx.storage.transaction(async (transaction) => {
       const pendingRunId = await transaction.get<string>(PENDING_RUN_KEY);
       const run = this.codec.optional(await transaction.get<unknown>(key));
-      if (
-        pendingRunId !== runId ||
-        !run ||
-        run.status !== "running" ||
-        run.phase !== "queued"
-      ) {
+      const lane = run ? storedRunLaneV1(run) : undefined;
+      const firstPendingAgent = await transaction.list<string>({
+        prefix: PENDING_AGENT_RUN_PREFIX,
+        limit: 1,
+      });
+      const firstPendingAgentEntry = firstPendingAgent.entries().next()
+        .value as [string, string] | undefined;
+      if (!run || run.status !== "running" || run.phase !== "queued") {
+        return "not-queued" as const;
+      }
+      if (lane === "agent") {
+        // A User Turn always has first claim on an idle Bot, and agent Turns
+        // retain FIFO order behind it. The run is still queued in either case;
+        // reporting `not-queued` here would strand its blocking caller even
+        // though the durable queue entry remains.
+        if (pendingRunId !== undefined) return "blocked" as const;
+        if (firstPendingAgentEntry?.[1] !== runId) {
+          return firstPendingAgentEntry
+            ? ("blocked" as const)
+            : ("not-queued" as const);
+        }
+      } else if (pendingRunId !== runId) {
         return "not-queued" as const;
       }
       if (await transaction.get<string>(ACTIVE_RUN_KEY)) {
@@ -420,7 +440,11 @@ export class BotDurableAuthority<Snapshot> {
         [key]: structuredClone(storedRunRecordV2(promoted)),
         [ACTIVE_RUN_KEY]: runId,
       });
-      await transaction.delete(PENDING_RUN_KEY);
+      if (lane === "agent" && firstPendingAgentEntry) {
+        await transaction.delete(firstPendingAgentEntry[0]);
+      } else {
+        await transaction.delete(PENDING_RUN_KEY);
+      }
       await this.refreshRecoveryAlarm(transaction);
       return {
         previous: latestEvents,
@@ -704,6 +728,7 @@ export class BotDurableAuthority<Snapshot> {
           // Recovery re-mounts on the recorded turn type, so the resumed Turn
           // sees the same trimmed catalog the evicted one did.
           turnType: storedRunTurnTypeV1(run),
+          lane: storedRunLaneV1(run),
           ...(storedRunSubagentRoleV1(run)
             ? { subagentRole: storedRunSubagentRoleV1(run) }
             : {}),
@@ -916,6 +941,26 @@ export class BotDurableAuthority<Snapshot> {
       });
       return;
     }
+    const [activeBeforeAlarm, pendingUser, pendingAgents] = await Promise.all([
+      this.ctx.storage.get<string>(ACTIVE_RUN_KEY),
+      this.ctx.storage.get<string>(PENDING_RUN_KEY),
+      this.ctx.storage.list<string>({
+        prefix: PENDING_AGENT_RUN_PREFIX,
+        limit: 1,
+      }),
+    ]);
+    // An admitted Turn is work already owed. It runs before a due Routine;
+    // otherwise a busy schedule can starve a Bot-to-Bot question indefinitely.
+    if (!activeBeforeAlarm && (pendingUser || pendingAgents.size > 0)) {
+      try {
+        await this.recoverQueuedRun();
+      } finally {
+        await this.ctx.storage.transaction((transaction) =>
+          this.refreshRecoveryAlarm(transaction),
+        );
+      }
+      return;
+    }
     await this.hooks.settleScheduledWork();
     const activeRunId = await this.ctx.storage.get<string>(ACTIVE_RUN_KEY);
     if (activeRunId) {
@@ -1046,7 +1091,11 @@ export class BotDurableAuthority<Snapshot> {
     return this.ctx.storage.transaction(async (transaction) => {
       const active = await transaction.get<string>(ACTIVE_RUN_KEY);
       const pending = await transaction.get<string>(PENDING_RUN_KEY);
-      if (active || pending) {
+      const pendingAgent = await transaction.list<string>({
+        prefix: PENDING_AGENT_RUN_PREFIX,
+        limit: 1,
+      });
+      if (active || pending || pendingAgent.size > 0) {
         // 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.
@@ -1324,9 +1373,13 @@ export class BotDurableAuthority<Snapshot> {
   async refreshRecoveryAlarm(
     transaction: DurableObjectTransaction,
   ): Promise<void> {
-    const [activeRunId, scheduled] = await Promise.all([
+    const [activeRunId, scheduled, pendingAgents] = await Promise.all([
       transaction.get<string>(ACTIVE_RUN_KEY),
       this.hooks.scheduledDeadlines(transaction),
+      transaction.list<string>({
+        prefix: PENDING_AGENT_RUN_PREFIX,
+        limit: 1,
+      }),
     ]);
     const activeRun = activeRunId
       ? this.codec.optional(
@@ -1341,7 +1394,8 @@ export class BotDurableAuthority<Snapshot> {
       deadlines.push(Date.now() + RECOVERY_ALARM_DELAY_MS);
     } else if (
       !activeRunId &&
-      (await transaction.get<string>(PENDING_RUN_KEY))
+      ((await transaction.get<string>(PENDING_RUN_KEY)) ||
+        pendingAgents.size > 0)
     ) {
       // A Turn admitted and waiting is work this object owes, so it keeps the
       // recovery alarm even with nothing running.
@@ -1427,9 +1481,62 @@ export class BotDurableAuthority<Snapshot> {
         throw new Error("Bot authority does not match its durable identity");
       }
       const activeRunId = await transaction.get<string>(ACTIVE_RUN_KEY);
-      const supersede = activeRunId
-        ? await this.planSupersede(transaction, command, activeRunId)
+      const pendingUserRunId = await transaction.get<string>(PENDING_RUN_KEY);
+      const lane = command.lane ?? defaultRunLaneV1(command.turnType ?? "chat");
+      const activeRun = activeRunId
+        ? this.codec.optional(
+            await transaction.get<unknown>(`${RUN_PREFIX}${activeRunId}`),
+          )
         : undefined;
+      const pendingAgents = await transaction.list<string>({
+        prefix: PENDING_AGENT_RUN_PREFIX,
+      });
+      const hasPendingAgent = pendingAgents.size > 0;
+      let supersede: ((supersededBy: string) => Promise<boolean>) | undefined;
+      if (activeRunId) {
+        if (
+          lane === "agent" &&
+          activeRun?.status === "reconciliation-required"
+        ) {
+          throw new BotTurnRefusedError(
+            "reconciliation-required",
+            "bot cannot admit agent work while its active run requires reconciliation",
+          );
+        }
+        if (lane === "user") {
+          supersede = await this.planSupersede(
+            transaction,
+            command,
+            activeRunId,
+          );
+        } else if (lane === "background") {
+          throw new BotTurnRefusedError(
+            "busy",
+            "bot already has an active run",
+          );
+        }
+      } else if (
+        lane === "background" &&
+        (pendingUserRunId || hasPendingAgent)
+      ) {
+        throw new BotTurnRefusedError(
+          "busy",
+          "bot has queued conversational work",
+        );
+      }
+      const queued =
+        Boolean(activeRunId) ||
+        (lane === "agent" && (Boolean(pendingUserRunId) || hasPendingAgent));
+      if (
+        lane === "agent" &&
+        queued &&
+        pendingAgents.size >= MAX_PENDING_AGENT_RUNS_V1
+      ) {
+        throw new BotTurnRefusedError(
+          "busy",
+          `bot agent queue is full (${MAX_PENDING_AGENT_RUNS_V1} Turns)`,
+        );
+      }
       const eventLog = new SessionEventLog(transaction);
       const storedEvents = await eventLog.migrate(command.sessionId);
       // A Turn that died between `turn/start` and `turn/end` — an event the
@@ -1447,11 +1554,6 @@ export class BotDurableAuthority<Snapshot> {
       // that Turn's end: a `running` record is, and so is a
       // `reconciliation-required` one, whose Turn is held open on purpose
       // until its outcome is retrieved. Nothing else is.
-      const activeRun = activeRunId
-        ? this.codec.optional(
-            await transaction.get<unknown>(`${RUN_PREFIX}${activeRunId}`),
-          )
-        : undefined;
       const stillOwned =
         activeRun?.status === "running" ||
         activeRun?.status === "reconciliation-required";
@@ -1484,7 +1586,7 @@ export class BotDurableAuthority<Snapshot> {
         // A queued Turn is admitted — durable, ordered, and owed a terminal
         // state — but has not started. Its `previousEventCount` is recomputed
         // when it is promoted, because the Turn ahead of it is still writing.
-        phase: activeRunId ? "queued" : "admitted",
+        phase: queued ? "queued" : "admitted",
         compositionGenerationId: pin.generationId,
         configurationSnapshot: structuredClone(admittedSettings),
         previousEventCount: latestEvents.length,
@@ -1501,8 +1603,13 @@ export class BotDurableAuthority<Snapshot> {
       await transaction.put({
         [key]: storedRunRecordV2(admittedRun),
         [runIndexKey(command.acceptedAt, command.runId)]: command.runId,
-        ...(activeRunId
-          ? { [PENDING_RUN_KEY]: command.runId }
+        ...(queued
+          ? lane === "agent"
+            ? {
+                [pendingAgentRunKey(command.acceptedAt, command.runId)]:
+                  command.runId,
+              }
+            : { [PENDING_RUN_KEY]: command.runId }
           : { [ACTIVE_RUN_KEY]: command.runId }),
         [IDENTITY_KEY]: identity ?? {
           userId: command.userId,
@@ -1511,13 +1618,15 @@ export class BotDurableAuthority<Snapshot> {
       });
       const interrupted = supersede ? await supersede(command.runId) : false;
       await this.refreshRecoveryAlarm(transaction);
-      if (activeRunId) {
+      if (queued) {
         return {
           kind: "queued" as const,
           // Only a Turn whose supersede intent was actually recorded is
           // interrupted. One that had not dispatched a model request is left
           // to finish, and the new message simply waits behind it.
-          ...(interrupted ? { interrupt: { runId: activeRunId } } : {}),
+          ...(interrupted && activeRunId
+            ? { interrupt: { runId: activeRunId } }
+            : {}),
         };
       }
       return {
@@ -1820,7 +1929,16 @@ export class BotDurableAuthority<Snapshot> {
    * do the promoting itself.
    */
   private async recoverQueuedRun(): Promise<void> {
-    const pendingRunId = await this.ctx.storage.get<string>(PENDING_RUN_KEY);
+    const pendingUserRunId =
+      await this.ctx.storage.get<string>(PENDING_RUN_KEY);
+    const pendingAgents = pendingUserRunId
+      ? new Map<string, string>()
+      : await this.ctx.storage.list<string>({
+          prefix: PENDING_AGENT_RUN_PREFIX,
+          limit: 1,
+        });
+    const pendingRunId =
+      pendingUserRunId ?? pendingAgents.values().next().value;
     if (!pendingRunId || this.queuedWaiters.has(pendingRunId)) return;
     if (pendingRunId === this.executingRunId) return;
     const durableIdentity =
@@ -1851,6 +1969,7 @@ export class BotDurableAuthority<Snapshot> {
       acceptedAt: run.acceptedAt,
       text: run.input,
       turnType: storedRunTurnTypeV1(run),
+      lane: storedRunLaneV1(run),
       ...(storedRunSubagentRoleV1(run)
         ? { subagentRole: storedRunSubagentRoleV1(run) }
         : {}),
@@ -2027,6 +2146,7 @@ export class BotDurableAuthority<Snapshot> {
         acceptedAt: recovery.run.acceptedAt,
         text: recovery.run.input,
         turnType: storedRunTurnTypeV1(recovery.run),
+        lane: storedRunLaneV1(recovery.run),
         ...(storedRunSubagentRoleV1(recovery.run)
           ? { subagentRole: storedRunSubagentRoleV1(recovery.run) }
           : {}),

package/src/run-records.ts

@@ -38,9 +38,9 @@ export type StoredRunStatus =
  * decision to interrupt is made in the admission transaction and has to
  * survive eviction alongside the run it interrupted.
  */
-export type RunLaneV1 = "user" | "background";
+export type RunLaneV1 = "user" | "agent" | "background";
 
-const RUN_LANES_V1: readonly RunLaneV1[] = ["user", "background"];
+const RUN_LANES_V1: readonly RunLaneV1[] = ["user", "agent", "background"];
 
 /**
  * The lane a turn type belongs to when its record names none. Chat is the
@@ -48,7 +48,8 @@ const RUN_LANES_V1: readonly RunLaneV1[] = ["user", "background"];
  * Bot started for itself.
  */
 export function defaultRunLaneV1(turnType: TurnTypeV1): RunLaneV1 {
-  return turnType === "chat" ? "user" : "background";
+  if (turnType === "chat") return "user";
+  return turnType === "agent" ? "agent" : "background";
 }
 
 export type StoredEffectAdmissionOutcome = "admitted" | "fenced";
@@ -85,9 +86,26 @@ export interface StoredRunSubagentOriginV1 {
   parentRunId: string;
 }
 
+/** A same-User Bot asking this Bot a question. */
+export interface StoredRunBotOriginV1 {
+  kind: "bot";
+  fromBotId: string;
+  fromBotName: string;
+  messageId: string;
+}
+
+/** The Voice Package asking this Bot on behalf of its User. */
+export interface StoredRunVoiceOriginV1 {
+  kind: "voice";
+  messageId: string;
+}
+
 /** What produced a Turn, when it was not a person speaking to the Bot. */
 export type StoredRunOriginV1 =
-  StoredRunRoutineOriginV1 | StoredRunSubagentOriginV1;
+  | StoredRunRoutineOriginV1
+  | StoredRunSubagentOriginV1
+  | StoredRunBotOriginV1
+  | StoredRunVoiceOriginV1;
 
 const STORED_RUN_ORIGIN_TRIGGERS: readonly StoredRunTriggerV1[] = [
   "cron",
@@ -436,6 +454,33 @@ function decodeStoredRunOrigin(
       parentRunId: candidate.parentRunId,
     };
   }
+  if (candidate.kind === "bot") {
+    requireExactOriginFields(
+      candidate,
+      ["kind", "fromBotId", "fromBotName", "messageId"],
+      runId,
+    );
+    if (
+      !boundedString(candidate.fromBotId, 128) ||
+      !boundedString(candidate.fromBotName, 100) ||
+      !boundedString(candidate.messageId, 256)
+    ) {
+      throw new Error(`run "${runId}" has an invalid admission origin`);
+    }
+    return {
+      kind: "bot",
+      fromBotId: candidate.fromBotId,
+      fromBotName: candidate.fromBotName,
+      messageId: candidate.messageId,
+    };
+  }
+  if (candidate.kind === "voice") {
+    requireExactOriginFields(candidate, ["kind", "messageId"], runId);
+    if (!boundedString(candidate.messageId, 256)) {
+      throw new Error(`run "${runId}" has an invalid admission origin id`);
+    }
+    return { kind: "voice", messageId: candidate.messageId };
+  }
   if (candidate.kind !== "routine") {
     throw new Error(`run "${runId}" has an invalid admission origin kind`);
   }

package/src/run-recovery.ts

@@ -82,7 +82,8 @@ export function latestModelRequestJournalState(
     ) {
       state = { status: "no-effect", request: state.request, outcome: event };
     } else if (
-      event.type === "assistant/message" &&
+      (event.type === "assistant/message" ||
+        event.type === "model/response-failed") &&
       state.status !== "none" &&
       event.requestId === state.request.request.requestId
     ) {

package/src/storage-keys.ts

@@ -16,6 +16,10 @@ export const ACTIVE_RUN_KEY = "active-run";
  * working through a backlog of things the User has already replaced.
  */
 export const PENDING_RUN_KEY = "pending-run";
+/** Agent-lane Turns wait FIFO behind conversational work. */
+export const PENDING_AGENT_RUN_PREFIX = "pending-agent-run:";
+/** A Bot cannot accumulate an unbounded cross-Bot inbox. */
+export const MAX_PENDING_AGENT_RUNS_V1 = 32;
 /** Legacy pre-ADR-0033 Session value, read only for transparent migration. */
 export const LATEST_EVENTS_KEY = "latest-events";
 export const SESSION_EVENT_LOG_INDEX_PREFIX = "session-events:index:";
@@ -84,6 +88,10 @@ export function runIndexKey(acceptedAt: string, runId: string): string {
   return `${RUN_INDEX_PREFIX}${acceptedAt}:${runId}`;
 }
 
+export function pendingAgentRunKey(acceptedAt: string, runId: string): string {
+  return `${PENDING_AGENT_RUN_PREFIX}${acceptedAt}:${runId}`;
+}
+
 export function compositionGenerationKey(generationId: string): string {
   return `${COMPOSITION_GENERATION_PREFIX}${generationId}`;
 }

package/src/turn-admission.test.ts

@@ -37,6 +37,13 @@ const SUBAGENT_ORIGIN: StoredRunOriginV1 = {
   parentRunId: "run-parent",
 };
 
+const BOT_ORIGIN: StoredRunOriginV1 = {
+  kind: "bot",
+  fromBotId: "researcher",
+  fromBotName: "Researcher",
+  messageId: "agent-message-1",
+};
+
 const codec = createStoredRunCodecV1<undefined>({
   decodeRunId: (value) => value as string,
   decodeConfigurationSnapshot: () => undefined,
@@ -158,6 +165,22 @@ describe("the admission record names what produced the Turn", () => {
     expect(codec.require(structuredClone(decoded))).toEqual(decoded);
   });
 
+  test("round-trips an agent Turn and its sending Bot", () => {
+    const decoded = codec.require(
+      legacyRun({
+        admission: {
+          schemaVersion: 1,
+          turnType: "agent",
+          origin: BOT_ORIGIN,
+        },
+      }),
+    );
+
+    expect(decoded.admission?.origin).toEqual(BOT_ORIGIN);
+    expect(storedRunTurnTypeV1(decoded)).toBe("agent");
+    expect(codec.require(structuredClone(decoded))).toEqual(decoded);
+  });
+
   test("each origin kind has its own exact fields, and cannot borrow another's", () => {
     const withOrigin = (origin: unknown) =>
       legacyRun({
@@ -400,6 +423,22 @@ describe("an admitted Turn re-mounts on its recorded turn type", () => {
     });
   });
 
+  test("an agent Turn defaults to the agent admission lane", async () => {
+    const storage = new MemoryStorage();
+    const probe = createAuthority(storage);
+
+    await probe.authority.run(command("run-agent", "agent"));
+
+    const stored = storage.values.get(
+      "run:run-agent",
+    ) as StoredRunV1<undefined>;
+    expect(stored.admission).toEqual({
+      schemaVersion: 1,
+      turnType: "agent",
+    });
+    expect(probe.observed[0]?.command.turnType).toBe("agent");
+  });
+
   test("after eviction the resumed run re-mounts on the recorded type", async () => {
     const storage = new MemoryStorage();
     const probe = createAuthority(storage);

package/src/turn-supersede.test.ts

@@ -25,6 +25,10 @@ import {
   storedRunLaneV1,
   type StoredRunV1,
 } from "./run-records.ts";
+import {
+  MAX_PENDING_AGENT_RUNS_V1,
+  pendingAgentRunKey,
+} from "./storage-keys.ts";
 
 const codec = createStoredRunCodecV1<undefined>({
   decodeRunId: (value) => value as string,
@@ -612,6 +616,150 @@ describe("a background admission never supersedes", () => {
   });
 });
 
+describe("the agent lane", () => {
+  test("queues behind the active Turn without superseding it", async () => {
+    const storage = new MemoryStorage();
+    const probe = createAuthority(storage);
+    const first = probe.authority.run(command("run-1", "person"));
+    await probe.handle("run-1").started;
+
+    const agent = probe.authority.run(
+      command("run-agent", "question", {
+        turnType: "agent",
+        origin: {
+          kind: "bot",
+          fromBotId: "researcher",
+          fromBotName: "Researcher",
+          messageId: "message-1",
+        },
+      }),
+    );
+    await admitted();
+    expect(probe.interrupts).toEqual([]);
+    expect(storedRun(storage, "run-agent")).toMatchObject({
+      phase: "queued",
+      admission: { turnType: "agent" },
+    });
+    expect(storedRunLaneV1(storedRun(storage, "run-agent"))).toBe("agent");
+
+    probe.handle("run-1").finish();
+    await first;
+    await probe.handle("run-agent").started;
+    probe.handle("run-agent").finish();
+    expect(await agent).toMatchObject({ text: "done: question" });
+  });
+
+  test("runs queued agent Turns FIFO", async () => {
+    const storage = new MemoryStorage();
+    const probe = createAuthority(storage);
+    const active = probe.authority.run(command("run-1", "person"));
+    await probe.handle("run-1").started;
+
+    const firstAgent = probe.authority.run(
+      command("run-agent-1", "first agent", { turnType: "agent" }),
+    );
+    await admitted();
+    const secondAgent = probe.authority.run(
+      command("run-agent-2", "second agent", { turnType: "agent" }),
+    );
+    await admitted();
+
+    probe.handle("run-1").finish();
+    await active;
+    await probe.handle("run-agent-1").started;
+    expect(probe.observed.map(({ command }) => command.runId)).toEqual([
+      "run-1",
+      "run-agent-1",
+    ]);
+    probe.handle("run-agent-1").finish();
+    await firstAgent;
+
+    await probe.handle("run-agent-2").started;
+    probe.handle("run-agent-2").finish();
+    await secondAgent;
+    expect(probe.observed.map(({ command }) => command.runId)).toEqual([
+      "run-1",
+      "run-agent-1",
+      "run-agent-2",
+    ]);
+  });
+
+  test("gives a queued User Turn priority over queued agent work", async () => {
+    const storage = new MemoryStorage();
+    const probe = createAuthority(storage);
+    const active = probe.authority.run(command("run-1", "person"));
+    await probe.handle("run-1").started;
+    const agent = probe.authority.run(
+      command("run-agent", "agent", { turnType: "agent" }),
+    );
+    await admitted();
+
+    const user = probe.authority.run(
+      command("run-user", "next message", {
+        lane: "user",
+        supersedes: { runId: "run-1" },
+      }),
+    );
+    await active;
+    await probe.handle("run-user").started;
+    expect(probe.observed.map(({ command }) => command.runId)).toEqual([
+      "run-1",
+      "run-user",
+    ]);
+    probe.handle("run-user").finish();
+    await user;
+
+    await probe.handle("run-agent").started;
+    probe.handle("run-agent").finish();
+    await agent;
+    expect(probe.observed.map(({ command }) => command.runId)).toEqual([
+      "run-1",
+      "run-user",
+      "run-agent",
+    ]);
+  });
+
+  test("refuses agent admission while the active Turn awaits reconciliation", async () => {
+    const storage = new MemoryStorage();
+    const probe = createAuthority(storage, { parkOnRelease: () => true });
+    const active = probe.authority.run(command("run-1", "person"));
+    await probe.handle("run-1").started;
+    probe.handle("run-1").finish();
+    await active.catch(() => undefined);
+
+    await expect(
+      probe.authority.run(command("run-agent", "agent", { turnType: "agent" })),
+    ).rejects.toThrow(/cannot admit agent work.*requires reconciliation/);
+    expect(storage.values.has("run:run-agent")).toBe(false);
+  });
+
+  test("refuses admission when the Bot's bounded agent queue is full", async () => {
+    const storage = new MemoryStorage();
+    const probe = createAuthority(storage);
+    const first = probe.authority.run(command("run-1", "person"));
+    await probe.handle("run-1").started;
+    for (let index = 0; index < MAX_PENDING_AGENT_RUNS_V1; index += 1) {
+      const runId = `queued-${index}`;
+      storage.values.set(
+        pendingAgentRunKey(
+          new Date(Date.UTC(2026, 8, 3, 1, 0, index)).toISOString(),
+          runId,
+        ),
+        runId,
+      );
+    }
+
+    await expect(
+      probe.authority.run(
+        command("run-past-bound", "question", { turnType: "agent" }),
+      ),
+    ).rejects.toThrow(/agent queue is full \(32 Turns\)/);
+
+    probe.handle("run-1").finish();
+    await first;
+  });
+});
+
 describe("eviction between the two Turns", () => {
   /**
    * Exactly what the object holds at the moment between the superseded Turn