@frockbot/plugin-shell 0.3.4 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "private": false,
   "type": "module",
   "exports": {
@@ -47,41 +47,41 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/agent-runtime": "0.3.4",
-    "@frockbot/application-foundation": "0.3.4",
-    "@frockbot/catalog-core": "0.3.4",
-    "@frockbot/client-core": "0.3.4",
-    "@frockbot/client-ui": "0.3.4",
-    "@frockbot/computer-core": "0.3.4",
-    "@frockbot/computer-host-protocol": "0.3.4",
-    "@frockbot/configuration-core": "0.3.4",
-    "@frockbot/connection-core": "0.3.4",
-    "@frockbot/kernel-agent-loop": "0.3.4",
-    "@frockbot/kernel-composition": "0.3.4",
-    "@frockbot/kernel-contracts": "0.3.4",
-    "@frockbot/kernel-do": "0.3.4",
-    "@frockbot/machine-protocol": "0.3.4",
-    "@frockbot/plugin-applets": "0.3.4",
-    "@frockbot/plugin-authoring": "0.3.4",
-    "@frockbot/plugin-bot-template": "0.3.4",
-    "@frockbot/plugin-computer": "0.3.4",
-    "@frockbot/plugin-flock": "0.3.4",
-    "@frockbot/plugin-image": "0.3.4",
-    "@frockbot/plugin-machine-messages": "0.3.4",
-    "@frockbot/plugin-mcp": "0.3.4",
-    "@frockbot/plugin-memory": "0.3.4",
-    "@frockbot/plugin-package-catalog": "0.3.4",
-    "@frockbot/plugin-routines": "0.3.4",
-    "@frockbot/plugin-skills": "0.3.4",
-    "@frockbot/plugin-subagents": "0.3.4",
-    "@frockbot/plugin-user-machine": "0.3.4",
-    "@frockbot/protocol": "0.3.4",
+    "@frockbot/agent-runtime": "0.3.5",
+    "@frockbot/application-foundation": "0.3.5",
+    "@frockbot/catalog-core": "0.3.5",
+    "@frockbot/client-core": "0.3.5",
+    "@frockbot/client-ui": "0.3.5",
+    "@frockbot/computer-core": "0.3.5",
+    "@frockbot/computer-host-protocol": "0.3.5",
+    "@frockbot/configuration-core": "0.3.5",
+    "@frockbot/connection-core": "0.3.5",
+    "@frockbot/kernel-agent-loop": "0.3.5",
+    "@frockbot/kernel-composition": "0.3.5",
+    "@frockbot/kernel-contracts": "0.3.5",
+    "@frockbot/kernel-do": "0.3.5",
+    "@frockbot/machine-protocol": "0.3.5",
+    "@frockbot/plugin-applets": "0.3.5",
+    "@frockbot/plugin-authoring": "0.3.5",
+    "@frockbot/plugin-bot-template": "0.3.5",
+    "@frockbot/plugin-computer": "0.3.5",
+    "@frockbot/plugin-flock": "0.3.5",
+    "@frockbot/plugin-image": "0.3.5",
+    "@frockbot/plugin-machine-messages": "0.3.5",
+    "@frockbot/plugin-mcp": "0.3.5",
+    "@frockbot/plugin-memory": "0.3.5",
+    "@frockbot/plugin-package-catalog": "0.3.5",
+    "@frockbot/plugin-routines": "0.3.5",
+    "@frockbot/plugin-skills": "0.3.5",
+    "@frockbot/plugin-subagents": "0.3.5",
+    "@frockbot/plugin-user-machine": "0.3.5",
+    "@frockbot/protocol": "0.3.5",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "latest",
-    "@frockbot/plugin-tools": "0.3.4",
+    "@frockbot/plugin-tools": "0.3.5",
     "@types/bun": "1.3.6",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/backend-recovery-integration.test.ts

@@ -1310,17 +1310,18 @@ describe("Bot recovery", () => {
         { schemaVersion: 1, runId: `bounded-fence-${index}` },
       );
     }
-    await expect(
-      contribution.fenceRunAdmission(
-        { userId: "user-1", botId: "primary" },
-        { schemaVersion: 1, runId: "fence-over-capacity" },
-      ),
-    ).rejects.toThrow("Run admission fence capacity reached");
+    // The index is a bounded FIFO: the oldest fence ages out, and the fence
+    // itself always succeeds. Refusing it instead meant a Bot that had refused
+    // 256 sends answered every later fence 500, and left the client looping
+    // "Turn admission lookup failed".
+    await contribution.fenceRunAdmission(
+      { userId: "user-1", botId: "primary" },
+      { schemaVersion: 1, runId: "fence-over-capacity" },
+    );
     const fences = await storage.get<string[]>("run-admission-fences");
     expect(fences).toHaveLength(256);
-    expect(fences).toContain("command-fenced");
-    expect(fences).toContain("bounded-fence-0");
-    expect(fences).not.toContain("fence-over-capacity");
+    expect(fences).toContain("fence-over-capacity");
+    expect(fences).not.toContain("command-fenced");
   });
 
   test("rechecks a fence committed during execution-context resolution", async () => {

package/src/backend.ts

@@ -328,7 +328,11 @@ import {
   type PendingBotInputV1,
   type RoutineInboxEntryV1,
 } from "@frockbot/plugin-routines/inbox";
-import type { RoutineScheduler } from "@frockbot/plugin-routines/scheduler";
+import type {
+  RoutineFireOutcomeV1,
+  RoutineScheduler,
+} from "@frockbot/plugin-routines/scheduler";
+import type { RoutineFireV1 } from "@frockbot/plugin-routines/firing";
 import {
   RoutineNotFoundError,
   type RoutineStore,
@@ -395,6 +399,7 @@ import {
   isVisibleRunV1,
   projectClientRunLookupV1,
   projectClientRunV1,
+  projectClientRunOrDegradedV1,
   projectClientAnnouncementsV1,
   projectClientTurnV1,
   type ClientRunLookupV1,
@@ -2975,17 +2980,24 @@ export class ShellBotBackendContribution {
   }
 
   private async settleScheduledWork(): Promise<void> {
-    await this.settleRoutineFirings();
-    await this.runOwedSubagentTurns();
-    await this.reconcileOverdueTasks();
-    await this.expireDueApprovals();
-    await this.replayPendingWakeNotifications();
-    await this.hostSettleScheduledWork?.();
-    // The alarm that woke this object has been consumed. Re-arm on whatever is
-    // owed next, or a Routine that fired once would never fire again.
-    await this.ctx.storage.transaction((transaction) =>
-      this.authority.refreshRecoveryAlarm(transaction),
-    );
+    // The re-arm is in a `finally` because it is the object's only way back.
+    // The alarm that woke this object has already been consumed by the
+    // platform; a throw in any one settler used to skip the re-arm, and then
+    // nothing — no Routine, no approval expiry, no owed subagent Turn — ever
+    // woke this Bot again except by a caller's luck. One producer failing must
+    // cost that producer its pass, never the clock.
+    try {
+      await this.settleRoutineFirings();
+      await this.runOwedSubagentTurns();
+      await this.reconcileOverdueTasks();
+      await this.expireDueApprovals();
+      await this.replayPendingWakeNotifications();
+      await this.hostSettleScheduledWork?.();
+    } finally {
+      await this.ctx.storage.transaction((transaction) =>
+        this.authority.refreshRecoveryAlarm(transaction),
+      );
+    }
   }
 
   /**
@@ -3005,21 +3017,73 @@ export class ShellBotBackendContribution {
     // here whenever the Turn is executing in this isolate, but a durable active
     // run outlives an eviction, and admitting a firing against one would burn
     // the occurrence on an error instead of holding the debt.
-    if (await this.authority.readActiveRunId()) return;
+    //
+    // Returning was not enough: the debt stayed past-due, so `deadlines()`
+    // re-armed on a moment already gone and the alarm spun straight back into
+    // this same bail-out — which is how a Routine racing a long chat Turn
+    // failed once a minute for ever. The hold is what turns the bail-out into
+    // a deferral: `dueAt` does not move, so the firing still lands.
+    if (await this.authority.readActiveRunId()) {
+      await this.ctx.storage.transaction((transaction) =>
+        this.routineScheduler.defer(transaction),
+      );
+      return;
+    }
     await this.routineScheduler.settle(async (fire) => {
-      try {
-        await this.authority.run(
-          routineTurnCommandV1(identity, fire, new Date().toISOString()),
-        );
-      } catch (error) {
-        return routineFireOutcomeV1(
-          await this.authority.readStoredRun(fire.fireId),
-          error,
-        );
-      }
+      const outcome = await this.runOneFiring(identity, fire);
+      await this.notifyFailedFiring(identity, fire, outcome);
+      return outcome;
+    });
+  }
+
+  private async runOneFiring(
+    identity: BotIdentity,
+    fire: RoutineFireV1,
+  ): Promise<RoutineFireOutcomeV1> {
+    try {
+      await this.authority.run(
+        routineTurnCommandV1(identity, fire, new Date().toISOString()),
+      );
+    } catch (error) {
       return routineFireOutcomeV1(
         await this.authority.readStoredRun(fire.fireId),
+        error,
       );
+    }
+    return routineFireOutcomeV1(
+      await this.authority.readStoredRun(fire.fireId),
+    );
+  }
+
+  /**
+   * Tell the person that a firing did not work.
+   *
+   * The scheduler has already written the durable completion-inbox entry in
+   * the transaction that settled the firing; this is the delivery half — the
+   * same seam a hand-off uses, so a Routine that breaks reaches the same place
+   * a Routine that finishes does instead of only a `failed` row nobody opens.
+   * `notifications.enabled` is honoured: it is the mute on updates, and a
+   * broken Routine is an update, not a decision the Bot is waiting on.
+   */
+  private async notifyFailedFiring(
+    identity: BotIdentity,
+    fire: RoutineFireV1,
+    outcome: RoutineFireOutcomeV1,
+  ): Promise<void> {
+    if (outcome.status === "ok") return;
+    const settings = await this.getSettings(identity);
+    if (!settings.notifications.enabled) return;
+    await this.authority.recordNotification({
+      // The same id shape the completion path uses, so one firing is one
+      // intent however many times the alarm retries it.
+      notificationId: `routine-failed:${fire.fireId}`,
+      runId: fire.fireId,
+      createdAt: new Date().toISOString(),
+      title: `${settings.profile.name} could not run a Routine`,
+      body: (outcome.summary ?? "The firing ended without saying why.").slice(
+        0,
+        240,
+      ),
     });
   }
   // -------------------------------------------------------------------------
@@ -5370,7 +5434,9 @@ export class ShellBotBackendContribution {
       // still not part of the conversation: the visible transcript never
       // shows one, running or settled.
       if (active && isVisibleRunV1(active))
-        selected.set(active.runId, { run: projectClientRunV1(active) });
+        selected.set(active.runId, {
+          run: projectClientRunOrDegradedV1(active),
+        });
     }
     const available = candidates.slice(0, CLIENT_RUN_PAGE_LIMIT);
     let stoppedEarly = false;
@@ -5382,7 +5448,7 @@ export class ShellBotBackendContribution {
       }
       const stored = await this.authority.readStoredRun(candidate.runId);
       if (!stored || !isVisibleRunV1(stored)) continue;
-      const projected = projectClientRunV1(stored);
+      const projected = projectClientRunOrDegradedV1(stored);
       const tentative = [
         ...selected.values(),
         { cursor: candidate.cursor, run: projected },

package/src/client/FrockBotApp.vue

@@ -405,6 +405,32 @@ function taskChipsOf(message: WebChatMessage): Array<{
   });
 }
 
+/**
+ * The tools this Turn ran, as the thread draws them.
+ *
+ * A tool whose Package draws its own surface is shown by that surface; every
+ * other one is a chip, because a Turn that spends a minute making tool calls
+ * used to show the User nothing at all but a spinning avatar.
+ */
+function toolChipsOf(message: WebChatMessage): WebToolActivity[] {
+  return message.tools.filter((tool) => iframeEntriesFor(tool).length === 0);
+}
+
+/** What a chip says a tool is doing. Its status, in the User's words. */
+function toolChipStatus(tool: WebToolActivity): string {
+  if (tool.status === "running") return "running";
+  return tool.status === "failed" ? "failed" : "done";
+}
+
+/** Which tool chips the User has opened. Local, and per chip. */
+const expandedTools = ref(new Set<string>());
+
+function toggleTool(toolId: string): void {
+  const next = new Set(expandedTools.value);
+  if (!next.delete(toolId)) next.add(toolId);
+  expandedTools.value = next;
+}
+
 /** Which chips the User has opened. Local, and per chip. */
 const expandedTasks = ref(new Set<string>());
 
@@ -431,6 +457,7 @@ function isVisible(message: WebChatMessage): boolean {
   // visible act was dispatching a subagent.
   return (
     message.text.length > 0 ||
+    (message.notice?.length ?? 0) > 0 ||
     message.tools.some((tool) => iframeEntriesFor(tool).length > 0) ||
     message.sends.length > 0 ||
     (message.tasks?.length ?? 0) > 0 ||
@@ -859,6 +886,13 @@ function handleComposerKeydown(event: KeyboardEvent): void {
               <div v-if="message.text" class="message-bubble">
                 <UiMarkdown :text="message.text" />
               </div>
+              <!--
+                Why the Turn ends where it does, under whatever it had already
+                said rather than in place of it.
+              -->
+              <p v-if="message.notice" class="message-notice">
+                {{ message.notice }}
+              </p>
               <template v-for="tool in message.tools" :key="tool.id">
                 <PackageIframeHost
                   v-for="entry in iframeEntriesFor(tool)"
@@ -906,6 +940,33 @@ function handleComposerKeydown(event: KeyboardEvent): void {
                   :send="send"
                 />
               </div>
+              <!--
+                What the Bot did, while it is doing it. The chip is the
+                conversation's whole account of an ordinary tool call: its
+                name, whether it is running, and — when the User opens it —
+                what it returned.
+              -->
+              <div v-if="toolChipsOf(message).length > 0" class="message-tools">
+                <button
+                  v-for="tool in toolChipsOf(message)"
+                  :key="tool.id"
+                  type="button"
+                  class="tool-chip"
+                  :class="`tool-chip-${tool.status}`"
+                  :aria-expanded="expandedTools.has(tool.id)"
+                  @click="toggleTool(tool.id)"
+                >
+                  <span class="tool-chip-name">{{ tool.name }}</span>
+                  <span class="tool-chip-status">{{
+                    toolChipStatus(tool)
+                  }}</span>
+                  <span
+                    v-if="expandedTools.has(tool.id) && tool.text !== undefined"
+                    class="tool-chip-result"
+                    >{{ tool.text }}</span
+                  >
+                </button>
+              </div>
               <!--
                 The subagents this Turn dispatched. The child's own Session is
                 never in this transcript, so the chip is the whole of what the

package/src/client/index.test.ts

@@ -1847,14 +1847,18 @@ describe("hosted Stop", () => {
       status: "reconciliation-required",
       message:
         "Stop accepted; reconciling the provider outcome before cancelling.",
-      canResume: false,
+      // A parked Turn is offered the resolve control, Stop included: hiding
+      // it there hid it in exactly the case Stop creates.
+      canResume: true,
     });
 
     await provided.value.stopRun();
     expect(provided.value.activeRun).toBeUndefined();
     expect(provided.value.activeRunId).toBeUndefined();
+    // The Turn keeps whatever it had already said; the notice is the line
+    // that says why it ends where it does.
     expect(provided.value.messages[1]).toMatchObject({
-      text: "Stopped by an authenticated Stop command.",
+      notice: "Stopped by an authenticated Stop command.",
       status: "aborted",
     });
 
@@ -1911,12 +1915,15 @@ describe("hosted Stop", () => {
 
     await provided.value.stopRun();
 
-    expect(lookups).toBe(1);
+    // Two, and deliberately: a client that finds itself holding an active run
+    // it did not start now observes it (a reload mid-Turn, a second tab), and
+    // Stop then observes the settlement it asked for.
+    expect(lookups).toBe(2);
     expect(provided.value.activeRun).toBeUndefined();
     expect(provided.value.activeRunId).toBeUndefined();
     expect(provided.value.messages.at(-1)).toMatchObject({
       runId: "run-1",
-      text: "Stopped by an authenticated Stop command.",
+      notice: "Stopped by an authenticated Stop command.",
       status: "aborted",
     });
   });
@@ -2897,7 +2904,7 @@ describe("a message sent while a Turn is running", () => {
     // The superseded Turn keeps the quiet treatment a stopped one gets.
     expect(state.messages[1]).toMatchObject({
       status: "aborted",
-      text: "Interrupted by your next message.",
+      notice: "Interrupted by your next message.",
     });
   });
 

package/src/client/index.ts

@@ -53,7 +53,10 @@ import {
 import { MCP_OAUTH_CONNECTION_TYPE_ID } from "@frockbot/plugin-mcp/agent";
 import { decodeStartConnectionResultV1 } from "@frockbot/connection-core";
 import { decodeClientSkillCatalogV1 } from "../skill-protocol.js";
-import { decodeClientTurnV1 } from "../run-protocol.js";
+import {
+  ClientTurnRefusedErrorV1,
+  decodeClientTurnV1,
+} from "../run-protocol.js";
 import {
   decodeApprovalDecisionReceiptV1,
   decodeApprovalListViewV1,
@@ -244,7 +247,11 @@ function activeRunView(run: ClientRun): WebActiveRun | undefined {
         : (run.recovery?.message ??
           run.failure ??
           "This Turn requires provider reconciliation before it can continue."),
-      canResume: !run.stopRequestedAt && run.recovery?.action === "resume",
+      // Offered whenever the run is parked, Stop included. Hiding it there
+      // hid it in exactly the case Stop creates: a Turn that was stopped
+      // while the model was mid-answer parks, and the person was left with a
+      // banner and no way to act on it.
+      canResume: run.recovery?.action === "resume",
     };
   }
   return undefined;
@@ -287,7 +294,8 @@ function assistantMessage(
       id: `${run.runId}:assistant`,
       runId: run.runId,
       role: "assistant",
-      text: run.failure ?? "Interrupted by your next message.",
+      text: run.responseText ?? "",
+      notice: run.failure ?? "Interrupted by your next message.",
       status: "aborted",
       tools: toolsFrom(run.events),
       sends: sendsFrom(run.events),
@@ -314,7 +322,8 @@ function assistantMessage(
       id: `${run.runId}:assistant`,
       runId: run.runId,
       role: "assistant",
-      text: run.failure ?? "Stopped by an authenticated Stop command.",
+      text: run.responseText ?? "",
+      notice: run.failure ?? "Stopped by an authenticated Stop command.",
       status: "aborted",
       tools: toolsFrom(run.events),
       sends: sendsFrom(run.events),
@@ -2296,6 +2305,12 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       const observed = web.value.activeRunId;
       const supersedes = observed ? { runId: observed } : {};
       web.value.activeRunId = pendingRunId;
+      // Stop is offered for the whole of the Turn the User just started, not
+      // only from the moment a projection happens to arrive. A send that
+      // supersedes a running Turn is the exception: the Turn Stop targets is
+      // still the one executing, and this one is queued behind it. The durable
+      // projection corrects both the instant it arrives.
+      if (!observed) web.value.runningRunId = pendingRunId;
       web.value.error = undefined;
       web.value.messages.push(
         {
@@ -2380,6 +2395,15 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
           web.value.activeBotId !== botId
         )
           return { accepted: true, runId: pendingRunId };
+        // A refusal is a normal answer, not an uncertain send: the Bot
+        // declined and said why. Show that, drop the optimistic bubbles, and
+        // let the composer give the person their text back — fencing a run
+        // that was never admitted only threw the reason away.
+        if (error instanceof ClientTurnRefusedErrorV1) {
+          removeMessages(web.value.messages, pendingRunId);
+          web.value.error = error.refusal.error;
+          return { accepted: false, error: error.refusal.error };
+        }
         const aborted =
           error instanceof DOMException && error.name === "AbortError";
         replaceMessage(web.value.messages, pendingRunId, {
@@ -2435,6 +2459,14 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         ) {
           web.value.activeRunId = undefined;
         }
+        // The optimistic Stop target goes with it: a Turn nobody is running is
+        // not a Turn anybody can stop.
+        if (
+          web.value.runningRunId === pendingRunId &&
+          web.value.activeRunId !== pendingRunId
+        ) {
+          web.value.runningRunId = undefined;
+        }
       }
     },
     async resumeRun(runId: string): Promise<void> {
@@ -2606,6 +2638,70 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     },
   );
 
+  /*
+   * A running Turn reaches every browser that is looking, not only the one
+   * holding its POST.
+   *
+   * The reply to `POST /api/bots/:bot/turns` is one client's copy of a Turn.
+   * A reload, a second tab, or a dropped request has no such copy, so the
+   * transcript would sit on a spinner until somebody reloaded again. Two
+   * seams close that: the Bot's state channel pushes a `runs` invalidation
+   * whenever the durable run records move, and — for any client that has no
+   * socket — the run is polled to its terminal state. Both end in the same
+   * `GET /api/bots/:bot/turns` projection, so neither invents client state
+   * and the one-bubble-per-send contract is untouched.
+   */
+  let stopRunChannel: (() => void) | undefined;
+  const stopRunChannelWatch = watch(
+    () => web.value.activeBotId,
+    (botId) => {
+      stopRunChannel?.();
+      stopRunChannel = undefined;
+      if (!botId || !ctx.transport.watchBotState) return;
+      const generation = selectionGeneration;
+      stopRunChannel = ctx.transport.watchBotState(botId, {
+        async invalidate(topic) {
+          // A reset carries no topic and means "read everything again".
+          if (topic !== undefined && topic !== "runs") return;
+          if (
+            generation !== selectionGeneration ||
+            web.value.activeBotId !== botId
+          )
+            return;
+          await deliverNotifications(botId, generation);
+        },
+        status() {
+          // The channel's health is not the transcript's: an unavailable
+          // socket falls back to the observation below, which is what a
+          // client without one uses anyway.
+        },
+      });
+    },
+    { immediate: true },
+  );
+
+  const stopRunObservation = watch(
+    () => [web.value.activeBotId, web.value.activeRunId] as const,
+    ([botId, runId]) => {
+      // The send path owns the run it started: its POST is the observation,
+      // and `stopRun` starts its own. This is for every other way a client
+      // finds itself watching a Turn it is not holding open.
+      if (!botId || !runId || activeRequest || runObserver) return;
+      const generation = selectionGeneration;
+      const observer = new AbortController();
+      runObserver = observer;
+      void observeRunUntilTerminal(botId, runId, generation, observer.signal)
+        .catch(() => {
+          // `observeRunUntilTerminal` reports its own failures; a rejection
+          // here would be an unhandled one.
+        })
+        .finally(() => {
+          if (runObserver === observer) runObserver = undefined;
+        });
+    },
+    { immediate: true },
+  );
+
   return [
     ctx.provide(clientSurfaceRegistryKey, surfaces),
     // The shared client projection is updated by the contracts lane. This cast
@@ -2624,6 +2720,9 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     () => {
       stopEntrySync();
       stopRunFollow();
+      stopRunChannelWatch();
+      stopRunChannel?.();
+      stopRunObservation();
       stopSourceFollow();
       for (const dispose of entryDisposers.splice(0).toReversed()) dispose();
       activeRequest?.abort();
@@ -2644,6 +2743,13 @@ function replaceMessage(
   if (index >= 0) messages[index] = replacement;
 }
 
+/** Takes back both optimistic lines of a send the Bot never admitted. */
+function removeMessages(messages: WebChatMessage[], runId: string): void {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.runId === runId) messages.splice(index, 1);
+  }
+}
+
 export default shellClientPlugin;
 
 /**

package/src/client/styles.css

@@ -290,6 +290,17 @@
   text-align: center;
 }
 
+/*
+ * Why a Turn ends where it does — stopped, or replaced by a later message.
+ * Quiet, and under the answer rather than instead of it: the words the Bot
+ * already said are the Turn's content, and this is only its last line.
+ */
+.message-notice {
+  margin: 2px 0 0;
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-xs);
+}
+
 /* An assistant Turn is its avatar and, once there is text, its bubble. */
 .message-assistant {
   flex-direction: row;
@@ -411,6 +422,56 @@
   width: min(640px, 84%);
 }
 
+/*
+ * Tool calls. Quieter than anything the Bot said: the User is watching work
+ * happen, not reading a message, so a chip carries the name and its state and
+ * opens in place to what the tool returned.
+ */
+
+.message-tools {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  width: min(640px, 84%);
+}
+
+.tool-chip {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  align-items: baseline;
+  padding: 6px 10px;
+  font: inherit;
+  color: var(--frock-text-muted);
+  text-align: left;
+  cursor: pointer;
+  background: var(--frock-surface);
+  border: 1px solid var(--frock-border);
+  border-radius: 10px;
+}
+
+.tool-chip-name {
+  color: var(--frock-text);
+  font-weight: 600;
+}
+
+.tool-chip-status {
+  flex: 1 1 auto;
+  font-size: var(--frock-text-xs);
+}
+
+.tool-chip-failed .tool-chip-status {
+  color: var(--frock-danger-text);
+}
+
+.tool-chip-result {
+  flex: 1 0 100%;
+  max-height: 12em;
+  overflow: auto;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
 /*
  * Dispatched subagents. A chip is deliberately quiet — a subagent is work the
  * Bot delegated, not something it said — and opens in place to the summary the

package/src/run-protocol.test.ts

@@ -22,6 +22,7 @@ import {
   projectClientRunLookupV1,
   projectClientRunListV1,
   projectClientRunV1,
+  projectClientRunOrDegradedV1,
   projectClientTurnV1,
 } from "./run-protocol.js";
 
@@ -1357,6 +1358,78 @@ describe("dispatched subagents in the run projection", () => {
     expect(() => decodeClientRunPageV1(tampered)).toThrow();
   });
 
+  test("a run whose record cannot be read degrades instead of failing the list", () => {
+    // One badly written record — a resolve that wrote a shape the record does
+    // not allow — used to answer 500 for the whole transcript, for good.
+    const broken = {
+      ...storedRun([], "running"),
+      status: "reconciliation-required",
+      phase: "executing",
+    } as unknown as StoredRun;
+    expect(() => projectClientRunV1(broken)).toThrow();
+
+    const degraded = projectClientRunOrDegradedV1(broken);
+    expect(degraded).toMatchObject({
+      runId: "run-events",
+      status: "failed",
+      outcome: { type: "failed" },
+    });
+    // And the degraded row is itself a valid projection, so the page decodes.
+    expect(
+      decodeClientRunPageV1(
+        createClientRunListV1([degraded], { truncated: false }),
+      ).runs,
+    ).toHaveLength(1);
+  });
+
+  test("an interrupted Turn keeps the text it had already streamed", () => {
+    const streamed: SessionEvent[] = [
+      event({
+        type: "assistant/chunk",
+        seq: 0,
+        timestamp,
+        turn: 1,
+        step: 1,
+        requestId: "request-1",
+        text: "The three things to know are",
+      }),
+      event({
+        type: "assistant/chunk",
+        seq: 1,
+        timestamp,
+        turn: 1,
+        step: 1,
+        requestId: "request-1",
+        text: " first, that",
+      }),
+    ];
+
+    for (const status of ["cancelled", "superseded"] as const) {
+      const projected = projectClientRunV1({
+        ...storedRun(streamed, status),
+        ...(status === "superseded"
+          ? {
+              supersededAt: "2026-08-28T00:00:05.000Z",
+              supersededBy: "run-next",
+            }
+          : {}),
+      });
+      expect(projected.outcome).toMatchObject({
+        type: status,
+        text: "The three things to know are first, that",
+      });
+      // And it survives the wire: the client reads it as the Turn's text, with
+      // the notice kept separately as the line that says why it stops there.
+      const decoded = decodeClientRunPageV1(
+        createClientRunListV1([projected], { truncated: false }),
+      ).runs[0];
+      expect(decoded?.responseText).toBe(
+        "The three things to know are first, that",
+      );
+      expect(decoded?.failure).toBeDefined();
+    }
+  });
+
   test("refuses a chip whose background flag is not a boolean", () => {
     const page = createClientRunListV1(
       [projectClientRunV1(storedRun([dispatched]))],

package/src/run-protocol.ts

@@ -52,6 +52,63 @@ export type ClientRunStatusV1 =
 const CANCELLED_RUN_MESSAGE = "Stopped by an authenticated Stop command.";
 const SUPERSEDED_RUN_MESSAGE = "Interrupted by your next message.";
 
+/**
+ * Why the Bot declined to admit a Turn. A refusal is an ordinary answer — the
+ * Bot is busy with a Turn this command did not ask to replace, is holding an
+ * effect only a User can settle, or the command was fenced or already used —
+ * so the client shows the reason and keeps the person's text rather than
+ * treating it as a failure of the send.
+ */
+export type ClientTurnRefusalReasonV1 =
+  "busy" | "reconciliation-required" | "fenced" | "duplicate";
+
+/** The versioned body a refused Turn answers with, decoded by the client. */
+export interface ClientTurnRefusalV1 {
+  schemaVersion: 1;
+  status: "refused";
+  reason: ClientTurnRefusalReasonV1;
+  error: string;
+}
+
+const TURN_REFUSAL_REASONS_V1: readonly ClientTurnRefusalReasonV1[] = [
+  "busy",
+  "reconciliation-required",
+  "fenced",
+  "duplicate",
+];
+
+/** The refusal a response body carries, or `undefined` when it carries none. */
+export function decodeClientTurnRefusalV1(
+  value: unknown,
+): ClientTurnRefusalV1 | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const body = value as Record<string, unknown>;
+  if (body.schemaVersion !== 1 || body.status !== "refused") return undefined;
+  if (typeof body.error !== "string") return undefined;
+  const reason = TURN_REFUSAL_REASONS_V1.find(
+    (candidate) => candidate === body.reason,
+  );
+  if (!reason) return undefined;
+  return {
+    schemaVersion: 1,
+    status: "refused",
+    reason,
+    error: wireString(body, "error", MAX_FAILURE_BYTES, "turn refusal"),
+  };
+}
+
+/**
+ * A refusal, as an error, because that is how a transport reports a non-2xx.
+ * The reason survives on the error so the client can tell "the Bot said no"
+ * from "the send may or may not have happened".
+ */
+export class ClientTurnRefusedErrorV1 extends Error {
+  constructor(readonly refusal: ClientTurnRefusalV1) {
+    super(refusal.error);
+    this.name = "ClientTurnRefusedErrorV1";
+  }
+}
+
 export type ClientRunEventV1 =
   | {
       type: "run/events-truncated";
@@ -123,8 +180,13 @@ export interface ClientDynamicToolCallInputV1 {
 export type ClientRunOutcomeV1 =
   | { type: "completed"; text: string }
   | { type: "failed"; message: string }
-  | { type: "cancelled"; message: string }
-  | { type: "superseded"; message: string };
+  /**
+   * A Turn a Stop or a later message ended keeps what it had already said:
+   * `text` is that partial answer, and `message` is the line saying why it
+   * ends where it does (ADR 0024).
+   */
+  | { type: "cancelled"; message: string; text?: string }
+  | { type: "superseded"; message: string; text?: string };
 
 export interface ClientRunRecoveryV1 {
   action: "resume";
@@ -565,6 +627,33 @@ function visibleEvents(
   return projection;
 }
 
+/**
+ * What an interrupted Turn had already said, read back out of its journal.
+ *
+ * The kernel records a Turn's answer as it streams, so a Turn stopped or
+ * superseded mid-sentence still holds every word it sent. It never reached a
+ * `responseText`, because it never completed — but the partial answer is a
+ * fact about what the person watched arrive, not a claim that the Turn
+ * succeeded, and the thread keeps it instead of replacing it with a notice.
+ */
+function interruptedOutcomeTextV1(run: StoredRun): { text?: string } {
+  let requestId: string | undefined;
+  let text = run.responseText ?? "";
+  for (const event of run.events) {
+    if (event.type === "assistant/chunk") {
+      if (event.requestId !== requestId) {
+        requestId = event.requestId;
+        text = "";
+      }
+      text += event.text;
+    } else if (event.type === "assistant/message") {
+      requestId = event.requestId;
+      text = event.text;
+    }
+  }
+  return text ? { text: truncateWireString(text, MAX_OUTCOME_BYTES) } : {};
+}
+
 function runStatus(run: StoredRun): ClientRunStatusV1 {
   return requireStoredRunV1(run).status;
 }
@@ -589,11 +678,13 @@ export function projectClientRunV1(run: StoredRun): ClientRunV1 {
           ? ({
               type: "cancelled",
               message: CANCELLED_RUN_MESSAGE,
+              ...interruptedOutcomeTextV1(run),
             } satisfies ClientRunOutcomeV1)
           : status === "superseded"
             ? ({
                 type: "superseded",
                 message: SUPERSEDED_RUN_MESSAGE,
+                ...interruptedOutcomeTextV1(run),
               } satisfies ClientRunOutcomeV1)
             : undefined;
   const recovery =
@@ -695,6 +786,39 @@ export function projectClientTurnV1(result: BotTurnCompletion): ClientTurnV1 {
   };
 }
 
+/**
+ * One stored run on the wire, degraded rather than thrown when the record
+ * cannot be read.
+ *
+ * A single unreadable run — an older shape, or one a bug wrote badly — used to
+ * fail the whole transcript: `GET /turns` answered 500 for every request after
+ * it, and the person's entire conversation disappeared behind one bad row. The
+ * transcript keeps its shape and says which Turn it could not read.
+ */
+export function projectClientRunOrDegradedV1(run: StoredRun): ClientRunV1 {
+  try {
+    return projectClientRunV1(run);
+  } catch {
+    const admittedAt =
+      typeof run.acceptedAt === "string" &&
+      Number.isFinite(Date.parse(run.acceptedAt))
+        ? run.acceptedAt
+        : new Date(0).toISOString();
+    return {
+      schemaVersion: 2,
+      runId: truncate(String(run.runId ?? "unknown"), MAX_RUN_ID_LENGTH),
+      admittedAt,
+      input: typeof run.input === "string" ? run.input : "",
+      status: "failed",
+      events: [],
+      outcome: {
+        type: "failed",
+        message: "This Turn's record could not be read.",
+      },
+    };
+  }
+}
+
 export function projectClientRunListV1(
   runs: readonly StoredRun[],
 ): ClientRunListV1 {
@@ -1004,22 +1128,34 @@ function decodeOutcome(
     };
   }
   if (outcome.type === "cancelled" && runStatus === "cancelled") {
-    exactKeys(outcome, ["type", "message"], "run.outcome");
+    exactKeys(outcome, ["type", "message", "text"], "run.outcome");
     return {
       type: "cancelled",
       message: wireString(outcome, "message", MAX_FAILURE_BYTES, "run.outcome"),
+      ...decodeInterruptedTextV1(outcome),
     };
   }
   if (outcome.type === "superseded" && runStatus === "superseded") {
-    exactKeys(outcome, ["type", "message"], "run.outcome");
+    exactKeys(outcome, ["type", "message", "text"], "run.outcome");
     return {
       type: "superseded",
       message: wireString(outcome, "message", MAX_FAILURE_BYTES, "run.outcome"),
+      ...decodeInterruptedTextV1(outcome),
     };
   }
   throw new Error("run.outcome does not match run.status");
 }
 
+/** The partial answer an interrupted Turn kept, when it said anything. */
+function decodeInterruptedTextV1(outcome: Record<string, unknown>): {
+  text?: string;
+} {
+  if (outcome.text === undefined) return {};
+  return {
+    text: wireString(outcome, "text", MAX_OUTCOME_BYTES, "run.outcome"),
+  };
+}
+
 function decodeRecovery(
   value: unknown,
   runStatus: ClientRunStatusV1,
@@ -1114,8 +1250,12 @@ function decodeRun(value: unknown): ClientRun {
     ...(run.queued === true ? { queued: true as const } : {}),
     ...(outcome?.type === "completed" ? { responseText: outcome.text } : {}),
     ...(outcome?.type === "failed" ? { failure: outcome.message } : {}),
-    ...(outcome?.type === "cancelled" ? { failure: outcome.message } : {}),
-    ...(outcome?.type === "superseded" ? { failure: outcome.message } : {}),
+    ...(outcome?.type === "cancelled" || outcome?.type === "superseded"
+      ? {
+          failure: outcome.message,
+          ...(outcome.text ? { responseText: outcome.text } : {}),
+        }
+      : {}),
     ...(recovery ? { failure: recovery.message, recovery } : {}),
   };
 }

package/src/shared.ts

@@ -101,6 +101,12 @@ export interface WebChatMessage {
    * reached, not a state the User has to understand.
    */
   pending?: boolean;
+  /**
+   * A line under the bubble saying why the Turn ends where it does — it was
+   * stopped, or a later message took its place. The text above it is what the
+   * Bot had already said, which it keeps (ADR 0024).
+   */
+  notice?: string;
   tools: WebToolActivity[];
   /** The typed payloads this Turn sent to the user, oldest first. */
   sends: WebSendPayload[];