@nothumanwork/pi-canary 0.1.0 → 0.1.1

package/README.md

@@ -41,7 +41,12 @@ Thinking/reasoning blocks, structured tool calls and their arguments, and tool r
 
 ## Recovery
 
-At the end of the agent's response to a user message, a missing prefix triggers this sequence:
+The prefix is checked after each assistant message. A handover is only useful while the agent is still working, so recovery depends on whether that message ends the turn:
+
+- **Mid-run message** (it has tool calls, so the agent will continue): recovery starts immediately, as below. Tool calls in the offending message have already run; tool calls after that are blocked.
+- **Final message** (no tool calls, so the agent is ending its turn): a warning is shown, and nothing else happens. No handover request, tool blocking, compaction, or continuation.
+
+Recovery sequence:
 
 1. Flag the failure with a visible instruction and require the agent's next response to be a self-contained handover prompt. Tool execution is blocked during this phase.
 2. Accept a complete, correctly prefixed, tool-free response beginning with `chirp: # Canary handover`, followed by a newline and handover content.
@@ -50,7 +55,7 @@ At the end of the agent's response to a user message, a missing prefix triggers
 
 “Restart” means **fresh model context within the same session file**, not a new Pi process or new session file. The restarted model receives the system/tool checkpoint, compaction summary, and handover. Older conversation entries remain in the session history but are not replayed into the restarted context. Successful summary usage is attached to the compaction entry. Known limitation: usage from rejected or interrupted summary requests is not included in Pi's session totals; the current extension API does not expose an independent usage-recording operation.
 
-Recovery allows at most two handover responses and one automatic restart per user message. The handover-attempt budget also applies when an earlier extension requests continuation. A deferred handover pauses recovery immediately instead of submitting more requests while a provider job may still be running; this does not explicitly cancel or retrieve that provider job. Further violations pause recovery rather than creating a loop. Provider errors, missing/empty/truncated summaries, and user cancellation do not discard history or automatically restart. Queued user input takes priority; a new user message resets the recovery state. If recovery pauses, inspect the preserved handover/history and send a new instruction, or disable canary mode.
+Recovery allows at most two handover responses and one automatic restart per user message. If the restarted agent misses the prefix mid-run, the run is stopped and recovery pauses. A miss on its final message only shows a warning. The handover-attempt budget also applies when an earlier extension requests continuation. A deferred handover pauses recovery immediately instead of submitting more requests while a provider job may still be running; this does not explicitly cancel or retrieve that provider job. Further violations pause recovery rather than creating a loop. Provider errors, missing/empty/truncated summaries, and user cancellation do not discard history or automatically restart. Queued user input takes priority; a new user message resets the recovery state. If recovery pauses, inspect the preserved handover/history and send a new instruction, or disable canary mode.
 
 ## Tests
 
@@ -66,6 +71,6 @@ For a standalone extension, point the tests at your installed coding-agent entry
 PI_CANARY_SDK=/absolute/path/to/pi/dist/index.js bun test ./canary.test.ts
 ```
 
-The tests cover keyword persistence and automatic enabling/reload, settings precedence, case preservation, malformed/locked/BOM-prefixed settings, Unicode separators, symlinks, cancelled command changes, exact-prefix checks, reasoning/tool exclusions, branch restoration, bounded/deferred handover attempts, compaction failures, cancellation, queued input, preservation of other extensions' boundary drafts, headless operation, and Pi's real file loader/lifecycle with a scripted, offline provider.
+The tests cover keyword persistence and automatic enabling/reload, settings precedence, case preservation, malformed/locked/BOM-prefixed settings, Unicode separators, symlinks, cancelled command changes, exact-prefix checks, per-message checks (mid-run misses recover, final-message misses only warn), reasoning/tool exclusions, branch restoration, bounded/deferred handover attempts, compaction failures, cancellation, queued input, preservation of other extensions' boundary drafts, headless operation, and Pi's real file loader/lifecycle with a scripted, offline provider.
 
 See [Measured changes](canary.value.md) for before/after results and proposals deliberately not retained. To run the same tests against an older implementation, set `PI_CANARY_EXTENSION` to its absolute file path; both the unit harness and real loader use that implementation.

package/canary.ts

@@ -279,8 +279,9 @@ export default function (pi: ExtensionAPI) {
         text.slice(`${recovery.keyword}: ${HANDOVER_HEADING}\n`.length).trim()
         ? text
         : undefined;
-    } else if (message.stopReason !== "deferred" && text.trim() && !text.startsWith(`${keywordForSpan}: `)) {
-      violated = true;
+    } else {
+      // Judged at this message's turn_end, once it is known whether the agent continues.
+      violated = message.stopReason !== "deferred" && !!text.trim() && !text.startsWith(`${keywordForSpan}: `);
     }
   });
 
@@ -290,17 +291,28 @@ export default function (pi: ExtensionAPI) {
     }
   });
 
+  const requestHandover = (current: Recovery, entries: AgentBeforeSettleEvent["entries"]) => ({
+    entries: [...entries, {
+      type: "custom_message" as const,
+      customType: "canary-handover-request",
+      content: handoverRequest(current.keyword),
+      display: true,
+    }],
+    continue: true,
+  });
+
   const handleBoundary = async (
     event: AgentBeforeSettleEvent | TurnEndEvent,
     ctx: ExtensionContext,
   ) => {
-    if (event.type === "turn_end" && !recovery) return;
+    const missed = event.type === "turn_end" && violated;
+    if (event.type === "turn_end") violated = false;
+    if (!recovery && !missed) return;
     if (!keywordForSpan || activeKeyword() !== keywordForSpan || paused) return;
     // Never override Escape, provider errors, or work already queued by the user.
     // In particular, do not compact a stale snapshot.
     if (event.outcome !== "completed" || ctx.signal?.aborted) {
       recovery = undefined;
-      violated = false;
       return;
     }
     if (event.context.pendingMessages.length || ctx.hasPendingMessages()) return;
@@ -316,26 +328,28 @@ export default function (pi: ExtensionAPI) {
           : "The agent did not produce a complete, correctly prefixed handover after two attempts";
       return { ...pauseRecovery(ctx, reason, event.entries), continue: false };
     }
-    if (event.continue) return;
-
-    if (!recovery) {
-      if (!violated) return;
-      if (restarted) return pauseRecovery(ctx, "The restarted agent missed the prefix again; automatic recovery is limited to once per user message", event.entries);
+    if (!recovery && event.type === "turn_end") {
+      // A message without tool calls ends the agent's turn. A handover there is
+      // too late to be useful, so report the miss without blocking or compacting.
+      if (event.message.role !== "assistant" || !event.message.content.some((block) => block.type === "toolCall")) {
+        notify(ctx, "Canary prefix missing on the final message. No handover requested because the turn has ended.", "warning");
+        return;
+      }
+      if (restarted) {
+        ctx.abort();
+        return { ...pauseRecovery(ctx, "The restarted agent missed the prefix again; automatic recovery is limited to once per user message", event.entries), continue: false };
+      }
       recovery = { keyword: keywordForSpan, attempts: 0 };
       notify(ctx, "Canary prefix missing. Requesting a handover before compaction.", "warning");
+      return requestHandover(recovery, event.entries);
     }
+    if (event.continue || !recovery) return;
+
     const current = recovery;
     if (!current.handover) {
+      // Re-request only once the agent has stopped without a usable handover.
       if (event.type === "turn_end") return;
-      return {
-        entries: [...event.entries, {
-          type: "custom_message" as const,
-          customType: "canary-handover-request",
-          content: handoverRequest(current.keyword),
-          display: true,
-        }],
-        continue: true,
-      };
+      return requestHandover(current, event.entries);
     }
 
     // Summarize at turn_end, while ctx.signal still belongs to the live run.
@@ -363,7 +377,6 @@ export default function (pi: ExtensionAPI) {
       }
       const handover = current.handover;
       recovery = undefined;
-      violated = false;
       restarted = true;
       notify(ctx, "Canary recovery complete. Restarting with the summary and handover.");
       // A boundary compaction is atomic with continuation. Retain-none gives a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nothumanwork/pi-canary",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Context canary and recovery for Pi",
   "keywords": [