@frockbot/plugin-shell 0.3.12 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "private": false,
   "type": "module",
   "exports": {
@@ -34,6 +34,7 @@
     "./notification-id": "./src/notification-id.ts",
     "./package.json": "./package.json",
     "./run-cursor": "./src/run-cursor.ts",
+    "./run-failure-copy": "./src/run-failure-copy.ts",
     "./run-protocol": "./src/run-protocol.ts",
     "./settings-links": "./src/settings-links.ts",
     "./shared": "./src/shared.ts",
@@ -49,42 +50,42 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/agent-runtime": "0.3.12",
-    "@frockbot/application-foundation": "0.3.12",
-    "@frockbot/catalog-core": "0.3.12",
-    "@frockbot/client-core": "0.3.12",
-    "@frockbot/client-ui": "0.3.12",
-    "@frockbot/computer-core": "0.3.12",
-    "@frockbot/computer-host-protocol": "0.3.12",
-    "@frockbot/configuration-core": "0.3.12",
-    "@frockbot/connection-core": "0.3.12",
-    "@frockbot/kernel-agent-loop": "0.3.12",
-    "@frockbot/kernel-composition": "0.3.12",
-    "@frockbot/kernel-contracts": "0.3.12",
-    "@frockbot/kernel-do": "0.3.12",
-    "@frockbot/machine-protocol": "0.3.12",
-    "@frockbot/plugin-applets": "0.3.12",
-    "@frockbot/plugin-authoring": "0.3.12",
-    "@frockbot/plugin-bot-template": "0.3.12",
-    "@frockbot/plugin-computer": "0.3.12",
-    "@frockbot/plugin-flock": "0.3.12",
-    "@frockbot/plugin-image": "0.3.12",
-    "@frockbot/plugin-machine-messages": "0.3.12",
-    "@frockbot/plugin-mcp": "0.3.12",
-    "@frockbot/plugin-memory": "0.3.12",
-    "@frockbot/plugin-package-catalog": "0.3.12",
-    "@frockbot/plugin-routines": "0.3.12",
-    "@frockbot/plugin-skills": "0.3.12",
-    "@frockbot/plugin-subagents": "0.3.12",
-    "@frockbot/plugin-user-machine": "0.3.12",
-    "@frockbot/protocol": "0.3.12",
+    "@frockbot/agent-runtime": "0.3.13",
+    "@frockbot/application-foundation": "0.3.13",
+    "@frockbot/catalog-core": "0.3.13",
+    "@frockbot/client-core": "0.3.13",
+    "@frockbot/client-ui": "0.3.13",
+    "@frockbot/computer-core": "0.3.13",
+    "@frockbot/computer-host-protocol": "0.3.13",
+    "@frockbot/configuration-core": "0.3.13",
+    "@frockbot/connection-core": "0.3.13",
+    "@frockbot/kernel-agent-loop": "0.3.13",
+    "@frockbot/kernel-composition": "0.3.13",
+    "@frockbot/kernel-contracts": "0.3.13",
+    "@frockbot/kernel-do": "0.3.13",
+    "@frockbot/machine-protocol": "0.3.13",
+    "@frockbot/plugin-applets": "0.3.13",
+    "@frockbot/plugin-authoring": "0.3.13",
+    "@frockbot/plugin-bot-template": "0.3.13",
+    "@frockbot/plugin-computer": "0.3.13",
+    "@frockbot/plugin-flock": "0.3.13",
+    "@frockbot/plugin-image": "0.3.13",
+    "@frockbot/plugin-machine-messages": "0.3.13",
+    "@frockbot/plugin-mcp": "0.3.13",
+    "@frockbot/plugin-memory": "0.3.13",
+    "@frockbot/plugin-package-catalog": "0.3.13",
+    "@frockbot/plugin-routines": "0.3.13",
+    "@frockbot/plugin-skills": "0.3.13",
+    "@frockbot/plugin-subagents": "0.3.13",
+    "@frockbot/plugin-user-machine": "0.3.13",
+    "@frockbot/protocol": "0.3.13",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "latest",
-    "@frockbot/plugin-prompt": "0.3.12",
-    "@frockbot/plugin-tools": "0.3.12",
+    "@frockbot/plugin-prompt": "0.3.13",
+    "@frockbot/plugin-tools": "0.3.13",
     "@types/bun": "1.3.6",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/agent.test.ts

@@ -448,3 +448,81 @@ describe("the conversation prompt section", () => {
     }
   });
 });
+
+// Two ends of one defect. The prompt tells the model to acknowledge with the
+// call; the promotion catches the model that acknowledges in text anyway. The
+// verification run watched a real model do exactly that — "On it — building
+// the 2027 countdown applet now." as plain assistant text, then three tool
+// calls — and nobody ever saw the line.
+describe("the acknowledgement reaches the user", () => {
+  test("the prompt names the call, not just the line", () => {
+    expect(CONVERSATION_PROMPT_TEXT_V1).toContain(
+      "Your own text is not shown to the user",
+    );
+    expect(CONVERSATION_PROMPT_TEXT_V1).toContain(
+      "your first action is a `send_to_user` call",
+    );
+  });
+
+  test("assistant text in a tool-calling step is promoted to one send", async () => {
+    const mounted = await mount();
+    try {
+      await mounted.root.serial(
+        "agent/assistant-text",
+        { session: mounted.session } as never,
+        "On it — building the 2027 countdown applet now.",
+        { turn: 4, step: 2, requestId: "request-1" },
+      );
+
+      const sends = mounted.session.events.filter(
+        (event) => event.type === "send/to-user",
+      );
+      expect(sends).toHaveLength(1);
+      expect(sends[0]).toMatchObject({
+        turn: 4,
+        step: 2,
+        occurrenceId: "assistant-text:request-1",
+        payload: {
+          type: "text",
+          text: "On it — building the 2027 countdown applet now.",
+        },
+      });
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  test("a step that already spoke is left alone, and a replay adds nothing", async () => {
+    const mounted = await mount();
+    try {
+      await invoke(
+        mounted,
+        "chat",
+        call(SEND_TO_USER_TOOL_V1, {
+          payload: { type: "text", text: "On it." },
+        }),
+      );
+      await mounted.root.serial(
+        "agent/assistant-text",
+        { session: mounted.session } as never,
+        "On it — building the countdown applet now.",
+        { turn: 4, step: 2, requestId: "request-1" },
+      );
+      // The same step replayed after an eviction promotes nothing new either.
+      await mounted.root.serial(
+        "agent/assistant-text",
+        { session: mounted.session } as never,
+        "On it — building the countdown applet now.",
+        { turn: 4, step: 2, requestId: "request-1" },
+      );
+
+      const sends = mounted.session.events.filter(
+        (event) => event.type === "send/to-user",
+      );
+      expect(sends).toHaveLength(1);
+      expect(sends[0]).toMatchObject({ payload: { text: "On it." } });
+    } finally {
+      await mounted.dispose();
+    }
+  });
+});

package/src/agent.ts

@@ -124,6 +124,60 @@ function openStepPositionV1(
   return { turn: started.turn, step: started.step };
 }
 
+/** The longest acknowledgement worth promoting; longer is not an ack. */
+export const PROMOTED_ASSISTANT_TEXT_LIMIT_V1 = 600;
+
+/** The occurrence id a promoted send is recorded under, per model request. */
+export function promotedSendOccurrenceIdV1(requestId: string): string {
+  return `assistant-text:${requestId}`;
+}
+
+/**
+ * Promotes a step's assistant text to a send when the model wrote to the
+ * person and then called tools without sending.
+ *
+ * The verification run is the whole argument for this. The model did exactly
+ * what the contract asks — "On it — building the 2027 countdown applet now.",
+ * one short line, no narration — and then called its tools. It went nowhere:
+ * the thread draws one bubble per send (issue 153) and there was no send, so
+ * the person watched a spinner and then a failure, with the acknowledgement
+ * they were owed sitting in the log where only the debug surface could see it.
+ *
+ * A step that already sent is left alone: the model's own text is scratch
+ * space once it has spoken, and promoting it there is how the same line
+ * arrives twice. The occurrence id is derived from the model request, so a
+ * step replayed after an eviction promotes the same text to the same
+ * occurrence rather than a second bubble.
+ *
+ * The prompt asks for the call and this does not replace it — a model that
+ * calls `send_to_user` never reaches here.
+ */
+export async function promoteAssistantTextToSendV1(
+  session: Session,
+  text: string,
+  position: { turn: number; step: number; requestId: string },
+): Promise<void> {
+  const trimmed = text.trim();
+  if (trimmed.length === 0 || trimmed.length > PROMOTED_ASSISTANT_TEXT_LIMIT_V1)
+    return;
+  const occurrenceId = promotedSendOccurrenceIdV1(position.requestId);
+  const spokeThisStep = session.events.some(
+    (event) =>
+      event.type === "send/to-user" &&
+      event.turn === position.turn &&
+      event.step === position.step,
+  );
+  if (spokeThisStep) return;
+  session.append({
+    type: "send/to-user",
+    turn: position.turn,
+    step: position.step,
+    occurrenceId,
+    payload: { type: "text", text: trimmed },
+  });
+  await session.flush();
+}
+
 /** What a recorded send tells the model it did. */
 function sendAcknowledgement(payload: SendToUserPayloadV1): string {
   switch (payload.type) {
@@ -160,7 +214,11 @@ export const CONVERSATION_PROMPT_TEXT_V1 = [
   "## Talking to the user",
   "",
   "Everything the user sees is a `send_to_user` call; nothing else reaches them.",
-  'When a request will take more than a moment, send one short line first — "On it." or "Looking into that." — then go quiet and work.',
+  // The first line said sends are the only thing the user sees, and a model
+  // still wrote its acknowledgement as plain assistant text and went straight
+  // on to call tools — nobody saw it. So the acknowledgement names the call.
+  "Your own text is not shown to the user. Writing a line in your reply instead of calling `send_to_user` means nobody reads it.",
+  'When a request will take more than a moment, your first action is a `send_to_user` call with one short line — "On it." or "Looking into that." — and then you go quiet and work.',
   "After that, send only on a real beat: the result, a decision only the user can make, or a blocker you cannot get past.",
   "Never narrate what you are doing, what you are about to do, or which tool you are using.",
   "Never leave a question or a request hanging: before you stop, the user must have the answer, the result, or the reason there isn't one.",
@@ -361,6 +419,12 @@ export const shellAgentPlugin: Plugin.Function = (ctx) => {
       createWakeParentTool(ctx.sessions),
       parentHandoff ? { admissionCeiling: parentHandoff } : undefined,
     ),
+    // The safety net under the prompt: a model that acknowledges the request
+    // in its own text instead of calling `send_to_user` still reaches the
+    // person. See `promoteAssistantTextToSendV1`.
+    ctx.on("agent/assistant-text", async (agent, text, position) => {
+      await promoteAssistantTextToSendV1(agent.session, text, position);
+    }),
     // ADR 0030. `ctx.inject` rather than a declared dependency: a host that
     // mounts the Shell without a model still gets its tools and its transcript
     // seam, and simply never compacts. The hook is evaluated after `turn/end`

package/src/backend-configuration.test.ts

@@ -701,16 +701,18 @@ describe("generic per-Turn model resolution", () => {
     };
     for (const bot of bots) {
       const runId = `${bot.botId}-disabled-package`;
-      await expect(
-        bot.contribution.run({
-          userId: "user-1",
-          botId: bot.botId,
-          runId,
-          sessionId: `user-1:${bot.botId}`,
-          acceptedAt: "2026-09-02T00:01:00.000Z",
-          text: "must fail",
-        }),
-      ).rejects.toThrow("Turn this model's plugin back on in Plugins");
+      // "Closed" is the durable record, not a rejected call. The Turn settles
+      // itself and the caller is handed that settlement: rethrowing over the
+      // top of it is what answered 500 and logged an uncaught error for a
+      // failure the Bot had already recorded properly.
+      await bot.contribution.run({
+        userId: "user-1",
+        botId: bot.botId,
+        runId,
+        sessionId: `user-1:${bot.botId}`,
+        acceptedAt: "2026-09-02T00:01:00.000Z",
+        text: "must fail",
+      });
       expect(await bot.storage.get(`run:${runId}`)).toMatchObject({
         status: "failed",
         failure: expect.stringContaining(
@@ -723,16 +725,14 @@ describe("generic per-Turn model resolution", () => {
     user.connections[0] = { ...user.connections[0]!, state: "revoked" };
     for (const bot of bots) {
       const runId = `${bot.botId}-revoked-connection`;
-      await expect(
-        bot.contribution.run({
-          userId: "user-1",
-          botId: bot.botId,
-          runId,
-          sessionId: `user-1:${bot.botId}`,
-          acceptedAt: "2026-09-02T00:02:00.000Z",
-          text: "must fail",
-        }),
-      ).rejects.toThrow("needs reconnecting");
+      await bot.contribution.run({
+        userId: "user-1",
+        botId: bot.botId,
+        runId,
+        sessionId: `user-1:${bot.botId}`,
+        acceptedAt: "2026-09-02T00:02:00.000Z",
+        text: "must fail",
+      });
       expect(await bot.storage.get(`run:${runId}`)).toMatchObject({
         status: "failed",
         failure: expect.stringContaining("needs reconnecting"),

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

@@ -344,16 +344,16 @@ describe("Bot recovery", () => {
     };
 
     failRequests = true;
-    await expect(
-      host().run({
-        userId: "user-1",
-        botId: "primary",
-        runId: "ollama-run-uncertain",
-        sessionId: "user-1:primary",
-        acceptedAt: "2026-08-30T00:02:00.000Z",
-        text: "uncertain",
-      }),
-    ).rejects.toThrow("response lost");
+    // The call resolves: the Turn settled itself, and the caller is handed
+    // that settlement rather than a rejection thrown over the top of it.
+    await host().run({
+      userId: "user-1",
+      botId: "primary",
+      runId: "ollama-run-uncertain",
+      sessionId: "user-1:primary",
+      acceptedAt: "2026-08-30T00:02:00.000Z",
+      text: "uncertain",
+    });
     // Ollama keeps no addressable copy of a completion, so a failure raised
     // before the first stream event is definitive rather than uncertain: the
     // run settles as a failed Turn instead of parking on a retrieval this

package/src/client/AppletCanvas.vue

@@ -18,7 +18,10 @@ import { UiIcon, UiIconButton, UiSkeleton } from "@frockbot/client-ui";
 import { computed, inject, onBeforeUnmount, ref, watch } from "vue";
 import { frockBotWebDataKey } from "../shared.js";
 import { appletsBridgeStateV2 } from "./applets-state.js";
-import { mostRecentlyChangedFileV1 } from "./applets-client.js";
+import {
+  appletSourceFingerprintV1,
+  mostRecentlyChangedFileV1,
+} from "./applets-client.js";
 import { packageIframePagesForSlotV1 } from "./package-iframe-entries.js";
 import PackageIframeHost from "./PackageIframeHost.vue";
 
@@ -70,20 +73,30 @@ watch(appletId, () => {
   userSelectedTab.value = undefined;
   followedTab.value = "code";
 });
-// A generation becoming active is the moment the Applet is worth looking at.
+// A generation becoming active is the moment the Applet is worth looking at —
+// and so is opening a page on an Applet that already has one. This runs
+// immediately because a second window, or a reload, mounts the canvas with the
+// viewer credential already in hand: waiting for a *change* left those pages
+// on the code view of an Applet that has been live for minutes.
 watch(
   () => viewer.value?.generationId,
   (generationId) => {
     if (generationId) followedTab.value = "app";
   },
+  { immediate: true },
 );
-// A Turn writing source is the moment the code is.
+// A Turn writing source is the moment the code is. The fingerprint is what
+// says a file changed: the canvas re-reads the source on every poll and gets a
+// fresh view object each time, so a watcher on the view itself fired on Turns
+// that wrote nothing — an Applet's own tool being called, say — and threw the
+// User off the live Applet mid-use. The first source to arrive is a load, not
+// a write, so it never moves the tab either.
 watch(
-  () => source.value?.files.map((file) => file.changedAt ?? file.generationId),
-  () => {
+  () => appletSourceFingerprintV1(source.value),
+  (fingerprint, previous) => {
+    if (!previous || fingerprint === previous) return;
     if (isRunning.value) followedTab.value = "code";
   },
-  { deep: true },
 );
 
 /** The file the code view is on, following the most recently changed one. */

package/src/client/FrockBotApp.vue

@@ -542,16 +542,18 @@ let trailRunId: string | undefined;
 let trailSeq = 0;
 let trailTick = 0;
 
-/** The one Turn still going, if any. Only one runs at a time. */
-const workingMessage = computed(() =>
-  messages.value.find(
+/**
+ * The Turn still going, if any. Only one executes at a time, but a Turn queued
+ * behind it is streaming-shaped too and has produced nothing yet, so the
+ * executing one wins: the trail keeps reading the words that are arriving
+ * rather than restarting on a Turn that has not begun.
+ */
+const workingMessage = computed(() => {
+  const streaming = messages.value.filter(
     (message) => message.role === "assistant" && message.status === "streaming",
-  ),
-);
-
-function isWorking(message: WebChatMessage): boolean {
-  return message.id === workingMessage.value?.id;
-}
+  );
+  return streaming.find((message) => !message.pending) ?? streaming.at(-1);
+});
 
 const workingSample = computed(() => {
   const message = workingMessage.value;
@@ -559,7 +561,16 @@ const workingSample = computed(() => {
   return activityTrailSampleV1({
     text: message.text,
     toolStatuses: message.tools.map((tool) => tool.status),
-    sends: message.sends.length,
+    // Counted across the whole Turn, because every send the Bot delivers is a
+    // message of its own and the working line carries none of them. A send is
+    // still a beat the trail has to feel.
+    sends: messages.value.reduce(
+      (total, candidate) =>
+        candidate.runId === message.runId
+          ? total + candidate.sends.length
+          : total,
+      0,
+    ),
     status: message.status,
   });
 });
@@ -1183,23 +1194,6 @@ function handleComposerKeydown(event: KeyboardEvent): void {
                 <div v-if="message.text" class="message-bubble">
                   <UiMarkdown :text="message.text" />
                 </div>
-                <!--
-                  The working state. Until the model has produced a word there
-                  was nothing beside the avatar at all, for twenty seconds and
-                  occasionally for two minutes, and the only other signal — the
-                  composer's stop button — is at the far end of the window from
-                  where the reply will appear.
-                -->
-                <div
-                  v-else-if="message.status === 'streaming'"
-                  class="message-bubble message-working"
-                  role="status"
-                  aria-label="Working on a reply"
-                >
-                  <span class="working-dots" aria-hidden="true">
-                    <i></i><i></i><i></i>
-                  </span>
-                </div>
                 <!--
                   Why the Turn ends where it does, under whatever it had
                   already said rather than in place of it.
@@ -1324,49 +1318,55 @@ function handleComposerKeydown(event: KeyboardEvent): void {
                   </button>
                 </div>
               </div>
-              <!--
-                The working row: the Bot's own avatar on its own line at the
-                end of the thread, with the comet trail streaming off to its
-                right. It appears only while the Turn is running. Every line in
-                this transcript is from the same Bot — there are no group
-                conversations yet (issue 152) — so a sheep beside a settled
-                reply named nobody the reader did not already know; the one
-                under a running Turn is the whole account of what the Bot is
-                doing.
-
-                The art comes from whichever Package owns Bot identity; when no
-                Package fills the slot the sparkle tile is the only child and
-                shows through. The row carries the status role, and the canvas
-                beside it is hidden from assistive technology: the trail is a
-                picture of a fact the label already states.
-              -->
-              <Transition name="bot-working">
-                <div
-                  v-if="isWorking(message)"
-                  class="bot-working"
-                  role="status"
-                  aria-label="Working"
-                >
-                  <div
-                    class="bot-avatar bot-avatar-live"
-                    :class="{ 'bot-avatar-waiting': !message.text }"
-                  >
-                    <span class="bot-avatar-fallback" aria-hidden="true"
-                      ><UiIcon name="sparkle" size="sm"
-                    /></span>
-                    <k-slot name="frockbot.bot-avatar" />
-                  </div>
-                  <UiActivityTrail
-                    class="bot-working-indicator"
-                    :rate="trailRate"
-                    :bursts="trailBursts"
-                    :state="trailState"
-                  />
-                </div>
-              </Transition>
             </template>
             <div v-else class="message-bubble">{{ message.text }}</div>
           </article>
+          <!--
+            The working row: the Bot's own avatar on its own line at the end of
+            the thread, with the comet trail streaming off to its right. It
+            appears only while a Turn is running. Every line in this transcript
+            is from the same Bot — there are no group conversations yet (issue
+            152) — so a sheep beside a settled reply named nobody the reader did
+            not already know; the one under a running Turn is the whole account
+            of what the Bot is doing.
+
+            It is a child of the thread rather than of the running Turn's
+            article, so it is always the last thing in the transcript. Send a
+            message while the Bot is still winding down and the new message
+            lands above the sheep, where a reader looking at the bottom of the
+            thread expects the newest thing to be — not underneath a running
+            Turn that is already over.
+
+            The art comes from whichever Package owns Bot identity; when no
+            Package fills the slot the sparkle tile is the only child and shows
+            through. The row carries the status role, and the canvas beside it
+            is hidden from assistive technology: the trail is a picture of a
+            fact the label already states.
+          -->
+          <Transition name="bot-working">
+            <div
+              v-if="workingMessage"
+              class="bot-working"
+              role="status"
+              aria-label="Working"
+            >
+              <div
+                class="bot-avatar bot-avatar-live"
+                :class="{ 'bot-avatar-waiting': !workingMessage.text }"
+              >
+                <span class="bot-avatar-fallback" aria-hidden="true"
+                  ><UiIcon name="sparkle" size="sm"
+                /></span>
+                <k-slot name="frockbot.bot-avatar" />
+              </div>
+              <UiActivityTrail
+                class="bot-working-indicator"
+                :rate="trailRate"
+                :bursts="trailBursts"
+                :state="trailState"
+              />
+            </div>
+          </Transition>
         </section>
 
         <Transition name="banner">

package/src/client/applets-client.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import {
+  appletSourceFingerprintV1,
   mostRecentlyChangedFileV1,
   readAppletList,
   readAppletSource,
@@ -119,6 +120,67 @@ describe("Applet routes", () => {
       }),
     ).toBe("ui.tsx");
   });
+
+  test("the source fingerprint is the same for a re-read of the same files", () => {
+    // The canvas moves the User to the code when a Turn *writes* source. It
+    // re-reads the source on every poll and gets a fresh view object each
+    // time, so the identity that decides has to be the files themselves —
+    // otherwise a Turn that only called an Applet's own tool throws the User
+    // off the live Applet.
+    const file = {
+      path: "server.ts",
+      text: "export default class {}",
+      generationId: "w-1",
+      changedAt: "2026-09-03T00:01:00.000Z",
+    };
+    const view = {
+      appletId: "u1abc.todo",
+      truncated: false,
+      files: [file, { ...file, path: "ui.tsx", generationId: "w-2" }],
+    };
+    expect(appletSourceFingerprintV1(view)).toBe(
+      appletSourceFingerprintV1(structuredClone(view)),
+    );
+    // Order is not a change either: two reads may sort the store differently.
+    expect(
+      appletSourceFingerprintV1({ ...view, files: view.files.toReversed() }),
+    ).toBe(appletSourceFingerprintV1(view));
+    expect(appletSourceFingerprintV1(undefined)).toBe("");
+  });
+
+  test("the source fingerprint changes when a Turn writes a file", () => {
+    const view = {
+      appletId: "u1abc.todo",
+      truncated: false,
+      files: [
+        {
+          path: "server.ts",
+          text: "",
+          generationId: "w-1",
+          changedAt: "2026-09-03T00:01:00.000Z",
+        },
+      ],
+    };
+    expect(
+      appletSourceFingerprintV1({
+        ...view,
+        files: [
+          {
+            ...view.files[0]!,
+            generationId: "w-2",
+            changedAt: "2026-09-03T00:02:00.000Z",
+          },
+        ],
+      }),
+    ).not.toBe(appletSourceFingerprintV1(view));
+    // A new file is a write too.
+    expect(
+      appletSourceFingerprintV1({
+        ...view,
+        files: [...view.files, { ...view.files[0]!, path: "ui.tsx" }],
+      }),
+    ).not.toBe(appletSourceFingerprintV1(view));
+  });
 });
 
 describe("the applets feed a page receives", () => {

package/src/client/applets-client.ts

@@ -137,3 +137,22 @@ export function mostRecentlyChangedFileV1(
   });
   return ordered[0]?.path;
 }
+
+/**
+ * A stable identity for the source the canvas is showing.
+ *
+ * The canvas follows the Turn: a Turn that writes source lands the User on the
+ * code. "Wrote source" has to be a fact about the files, though, not about the
+ * store having been re-read — `refreshAppletCanvas` assigns a fresh view object
+ * on every poll, so a watcher on the array itself fired on Turns that touched
+ * no file at all and yanked the User off the live Applet.
+ */
+export function appletSourceFingerprintV1(
+  source: AppletSourceViewV1 | undefined,
+): string {
+  if (!source) return "";
+  return source.files
+    .map((file) => `${file.path}@${file.generationId}@${file.changedAt ?? ""}`)
+    .toSorted()
+    .join("\n");
+}