@north-light/crouter 0.3.170 → 0.3.172

package/dist/pi-extensions/canvas-context-intro.js

@@ -3,44 +3,17 @@
 // Loaded into every canvas node's pi process via the node's launch.extensions
 // list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job agent).
 //
-// The bearings preamble. On `session_start` — which fires BEFORE the node's
-// first user message enters the session — this injects ONE <crtr-context>
-// message via `pi.sendMessage` (no delivery options, so at the idle start it is
-// pushed straight onto the message list and persisted). Because the session is
-// still empty at that point, the bearings land as the FIRST entry, ahead of the
-// node's first prompt — the orienting frame, not a trailing afterthought.
-//   (before_agent_start / deliverAs:"nextTurn" both append AFTER the user
-//    message — see agent-session's submit path — which is why we use
-//    session_start instead.)
+// On `session_start` — before the node's first real user message — this injects
+// one persisted <crtr-context> custom message. A fresh conversation receives the
+// full baseline as its first entry. A fork receives a compact update after the
+// copied history and immediately before its new mandate. The prose lives in
+// core/runtime/bearings.ts.
 //
-// The block carries: the path to the node's own context dir and the framing for
-// what belongs there (a shared document store for the other nodes). EVERY node
-// also gets a `<memory kind="knowledge">` block rendered from the document
-// substrate — eligible `knowledge` docs at their system-prompt visibility rung,
-// plus the node's own node-local substrate docs — so the bearings name what to
-// read on demand. (Preferences surface as their own `<memory kind="preference">`
-// block of the system prompt, not in this block.) An
-// orchestrator additionally gets the across-refresh-cycles framing (the one
-// thing a terminal worker's bearings drop). The prose lives in
-// core/runtime/bearings.ts (shared with the promotion guidance dump).
-//
-// IDEMPOTENT across resumes, but FORK-AWARE and BRANCH-AWARE: the idempotency
-// scan walks only the ACTIVE BRANCH (root-first from the current leaf), not
-// every entry in the file. A `--session` relaunch that is a true resume keeps
-// the same branch, so the scan finds OUR prior bearings (named by OUR node id)
-// and skips — it never accumulates. A post-yield CYCLE roots a fresh branch (the
-// `crtr-cycle` marker), so the scan correctly finds nothing on that fresh branch
-// and injects a new intro, even though an OLDER cycle's intro still sits
-// elsewhere in the same `.jsonl`. A `--fork-from` boot COPIES the source node's
-// whole conversation onto ITS OWN branch (bearings naming the SOURCE's node id,
-// not ours), so the handler must NOT treat that inherited block as ours; it only
-// skips when a bearings block belonging to OUR node is already present on the
-// active branch (exact `details.nodeId` stamp, content-match fallback),
-// otherwise it injects ours — whose identity assertion (leading the
-// <crtr-bearings> block) reasserts the fork's identity over the inherited
-// persona. This is ONE of two reinforcing channels: spawn.ts ALSO prepends the
-// same identity assertion to a fork's kickoff prompt (the turn-triggering
-// message), so the override does not rest on a single trailing custom_message.
+// BRANCH-AWARE and IDEMPOTENT: the active branch receives one bearings message
+// stamped for this node. A resume finds that stamp and injects nothing. A new
+// cycle has no current-branch stamp and receives a fresh full baseline. A fork
+// whose active branch carries another node's bearings receives only a compact
+// node-scoped update; a fork of a non-crouter session receives the full baseline.
 //
 // COLLAPSED BY DEFAULT: a `registerMessageRenderer` keyed to our customType
 // renders the block as a single one-line stub; the full body only appears when
@@ -53,8 +26,8 @@
 //
 // Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
 // crouter's own tsc build without a dep on the pi packages.
-import { buildContextBearings, CONTEXT_INTRO_CUSTOM_TYPE } from '../core/runtime/bearings.js';
-import { isWarmSpare } from '../core/canvas/index.js';
+import { buildContextBearings, buildForkBearings, CONTEXT_INTRO_CUSTOM_TYPE } from '../core/runtime/bearings.js';
+import { getNode, isWarmSpare } from '../core/canvas/index.js';
 /** The `customType` stamped on the injected session message. Used both to write
  *  the entry and to detect it on resume (the idempotency guard). Defined beside
  *  the block builder in `core/runtime/bearings.ts` because the warm-pool claim's
@@ -63,12 +36,16 @@ export { CONTEXT_INTRO_CUSTOM_TYPE };
 // ---------------------------------------------------------------------------
 // Block builder
 // ---------------------------------------------------------------------------
-/** Build the <crtr-context> bearings block for `nodeId`. Thin wrapper over the
- *  shared builder in core/runtime/bearings.ts (the single source of truth, also
- *  used by the promotion guidance dump). Exported for testing. */
+/** Build the full bearings baseline for a conversation without inherited
+ *  crouter context. Exported for testing. */
 export function buildContextIntro(nodeId) {
     return buildContextBearings(nodeId);
 }
+/** Build the compact node-scoped update for a fork whose copied branch already
+ *  carries a full crouter baseline. Exported for testing. */
+export function buildForkContextIntro(nodeId) {
+    return buildForkBearings(nodeId);
+}
 // ---------------------------------------------------------------------------
 // Collapsed-by-default rendering
 // ---------------------------------------------------------------------------
@@ -157,74 +134,43 @@ export function renderContextMessage(message, options, theme) {
 // ---------------------------------------------------------------------------
 // Extension
 // ---------------------------------------------------------------------------
-/**
- * Register the context-intro preamble on `pi`.
- *
- * Returns immediately (inert) when CRTR_NODE_ID is absent. On `session_start`
- * it injects the <crtr-context> block as the first message of a brand-new chat
- * — but only when the session does not already carry it, so a `--session <id>`
- * relaunch (which restores the conversation) never duplicates the block.
- */
+/** Register the context-intro preamble. Fresh branches receive one full
+ *  baseline, forked crouter branches receive one compact update, and resumes
+ *  whose active branch already carries this node's stamp receive nothing. */
 export function registerCanvasContextIntro(pi) {
     // Collapse the block to a one-liner until the user expands tool output (Ctrl+O).
     // Harmless to register outside TUI mode (it's only consulted while rendering).
     pi.registerMessageRenderer(CONTEXT_INTRO_CUSTOM_TYPE, renderContextMessage);
     pi.on('session_start', (_event, ctx) => {
-        try {
-            const nodeId = process.env['CRTR_NODE_ID'];
-            if (nodeId === undefined || nodeId.trim() === '')
-                return; // not a canvas node
-            // An UNCLAIMED warm spare gets no bearings. Nobody owns this conversation
-            // yet, so a block built now would assert the spare's placeholder persona
-            // (always `general`/`base`) and snapshot the repo as it looks at MINT
-            // time. The claim builds and delivers the real one over the broker once
-            // the row wears its claimant's kind/mode/name (`deliver-live.ts`), which
-            // still lands first in this session because nobody has spoken in it. A
-            // later revive of the claimed node re-injects nothing: the delivered block
-            // carries the same `details.nodeId` stamp the guard below matches on.
-            if (isWarmSpare(nodeId))
-                return;
-            // Branch-aware idempotency: scan only the ACTIVE branch (root-first from
-            // the current leaf), not every entry in the file. A post-yield cycle roots a
-            // FRESH branch (the crtr-cycle marker), so scanning the whole file would
-            // find a PRIOR cycle's intro and wrongly skip injecting this cycle's own —
-            // the node's first turn would lack its crtr-context bearings entirely.
-            // Falls back to a whole-file scan only if the engine doesn't expose
-            // getBranch (older/degraded engine). Not fooled by a FORK either way: a
-            // `--fork-from` boot copies the source's whole conversation onto ITS OWN
-            // branch (bearings naming the SOURCE's node id, not ours), so a naive
-            // "any crtr-context present?" check would suppress our own intro and let
-            // the fork inherit — and impersonate — the source. So we only skip when a
-            // bearings block belonging to OUR node is already present on the scanned
-            // branch. Primary discriminator: the EXACT `details.nodeId` stamp (machine-
-            // readable, copied on fork, never sent to the LLM). Fallback: a substring
-            // match on the block text (our id appears in the identity line AND the
-            // context-dir path `…/nodes/<nodeId>/context`) — covers legacy blocks
-            // persisted before the stamp existed. Either match ⇒ this is our own
-            // resume, not an inherited fork block, so skip.
-            const scan = typeof ctx.sessionManager.getBranch === 'function'
-                ? ctx.sessionManager.getBranch()
-                : ctx.sessionManager.getEntries();
-            const ours = scan.some((e) => e.type === 'custom_message' &&
-                e.customType === CONTEXT_INTRO_CUSTOM_TYPE &&
-                (e.details?.nodeId === nodeId || entryText(e).includes(nodeId)));
-            if (ours)
-                return;
-            // No delivery options: at the idle start of a session this is pushed onto
-            // the (still empty) message list and persisted immediately, so it precedes
-            // the node's first prompt. The `details.nodeId` stamp rides along as the
-            // exact resume discriminator (not shown to the LLM).
-            pi.sendMessage({
-                customType: CONTEXT_INTRO_CUSTOM_TYPE,
-                content: buildContextIntro(nodeId),
-                display: true,
-                details: { nodeId },
-            });
-        }
-        catch {
-            // Best-effort: a failure here must never break session startup.
+        const nodeId = process.env['CRTR_NODE_ID'];
+        if (nodeId === undefined || nodeId.trim() === '')
+            return;
+        // Warm spares have no claimant yet. Their claim path delivers the full
+        // baseline after assigning the real persona, profile, and working directory.
+        if (isWarmSpare(nodeId))
+            return;
+        // The active branch, rather than the whole session file, is the context the
+        // next turn sees. A new cycle therefore receives its own current baseline.
+        const scan = typeof ctx.sessionManager.getBranch === 'function'
+            ? ctx.sessionManager.getBranch()
+            : ctx.sessionManager.getEntries();
+        const contextEntries = scan.filter((e) => e.type === 'custom_message' && e.customType === CONTEXT_INTRO_CUSTOM_TYPE);
+        const ours = contextEntries.some((e) => e.details?.nodeId === nodeId || entryText(e).includes(nodeId));
+        if (ours)
             return;
-        }
+        // A copied crouter branch already carries the shared baseline. Append only
+        // this fork's new node-scoped facts. A non-crouter branch has no such entry.
+        const inherited = contextEntries.length > 0;
+        const forked = getNode(nodeId)?.fork_from != null;
+        const content = inherited && forked
+            ? buildForkContextIntro(nodeId)
+            : buildContextIntro(nodeId);
+        pi.sendMessage({
+            customType: CONTEXT_INTRO_CUSTOM_TYPE,
+            content,
+            display: true,
+            details: { nodeId },
+        });
     });
 }
 export default registerCanvasContextIntro;

package/dist/pi-extensions/canvas-recap.d.ts

@@ -1,3 +1,5 @@
+import { regenerateAndPersistName } from '../core/runtime/naming-persist.js';
+import { generateRecap } from '../core/runtime/recap.js';
 interface TextContentLike {
     type: string;
     text?: string;
@@ -9,6 +11,10 @@ interface MessageLike {
 interface SessionEntryLike {
     type: string;
     message?: MessageLike;
+    customType?: string;
+    details?: {
+        reviewId?: string;
+    };
 }
 interface SessionManagerLike {
     getEntries(): SessionEntryLike[];
@@ -17,6 +23,7 @@ interface UIContextLike {
     setWidget(key: string, content: string[] | undefined, options?: {
         placement?: 'aboveEditor' | 'belowEditor';
     }): void;
+    notify?(message: string, type?: 'info' | 'warn' | 'warning' | 'error'): void;
 }
 interface ExtensionCtxLike {
     ui?: UIContextLike;
@@ -27,9 +34,15 @@ interface ExtensionCtxLike {
         id?: string;
     };
 }
-type PiEvents = 'session_start' | 'input' | 'turn_end' | 'session_shutdown';
+type PiEvents = 'session_start' | 'input' | 'message_update' | 'turn_end' | 'session_shutdown';
 interface PiLike {
     on(event: PiEvents, handler: (event: any, ctx: ExtensionCtxLike) => void): void;
+    registerCommand?(name: string, options: {
+        description: string;
+        handler: (args: string, ctx: ExtensionCtxLike) => Promise<void> | void;
+    }): void;
+    getSessionName?(): string | undefined;
+    setSessionName?(name: string): void;
 }
 /**
  * Register the inactivity-recap chrome on `pi`.
@@ -37,5 +50,5 @@ interface PiLike {
  * Returns immediately (inert) when CRTR_NODE_ID is absent — a plain pi session
  * or legacy job agent loads it as a no-op.
  */
-export declare function registerCanvasRecap(pi: PiLike): void;
+export declare function registerCanvasRecap(pi: PiLike, recapGenerator?: typeof generateRecap, nameRegenerator?: typeof regenerateAndPersistName): void;
 export default registerCanvasRecap;

package/dist/pi-extensions/canvas-recap.js

@@ -1,26 +1,29 @@
 // canvas-recap.ts — pi extension for pi-native canvas agent nodes.
 //
-// A per-node INACTIVITY BRIEF, drawn faintly immediately above the editor border.
-// When a node has had NO new message (user or assistant) for IDLE_MS (60s by
-// default), it runs a stripped-down headless call on the conversation's current
-// working model and pins one concise, wrapped briefing above the editor, so a
-// developer returning to the conversation sees where it left off at a glance.
-// The card disappears the instant the next message arrives, and the idle clock
-// restarts.
+// A per-node recap, drawn faintly immediately above the editor border. When a
+// node has had NO new message (user or assistant) for IDLE_MS (60s by default),
+// it runs a stripped-down headless call on the conversation's current working
+// model and pins one concise, wrapped briefing above the editor, so a developer
+// returning to the conversation sees where it left off at a glance. `/recap`
+// generates that briefing immediately and refreshes the original generated
+// editor title from a conversation-wide sample. A shown card remains pinned as
+// the conversation advances and is replaced only when a newer recap succeeds.
 //
-//   trigger/clear are keyed off MESSAGES, not turns-of-work:
-//     • a user `input` event OR an assistant `turn_end` resets the idle clock
-//       and clears any shown recap.
+//   generation is keyed off MESSAGES, not turns-of-work:
+//     • user `input`, assistant `message_update`, and assistant `turn_end` events
+//       reset the idle clock and mark any shown recap stale.
 //     • a single low-rate timer (no busy-loop) checks elapsed-since-last-message
-//       and, on crossing IDLE_MS, generates + shows the recap once.
+//       and, on crossing IDLE_MS, replaces a missing or stale recap once.
 //
-//   Brief input = the FIRST 5 and MOST RECENT 5 user/assistant messages (literal
-//   text only — the first messages carry the original request, the last carry
-//   where it left off), plus the node's roadmap file when one exists. Tool calls,
+//   Brief input = the FIRST 5 and MOST RECENT 5 visible user/assistant messages
+//   (literal text only — for review companions, only messages after their durable
+//   boundary are visible), plus the node's roadmap file when one exists. Tool calls,
 //   tool results, thinking blocks, and extension-injected custom messages are
 //   excluded (only `message` entries with role user/assistant, and only their
-//   `text` content blocks). Long messages are truncated per-message so the
-//   opening request is never crowded out by a recent wall of text.
+//   `text` content blocks). While an assistant response is streaming, its latest
+//   `message_update` snapshot is appended because it is not yet in the persisted
+//   entries. Long messages are truncated per-message so the opening request is
+//   never crowded out by a recent wall of text.
 //
 //   Placement: key `crtr-recap`, placement `aboveEditor`.
 //
@@ -35,8 +38,11 @@
 //
 // Plain TS-with-types — no imports from @earendil-works/* so this compiles
 // inside crouter's own tsc build without a dep on the pi packages.
+import { getNode, editorLabel } from '../core/canvas/index.js';
+import { regenerateAndPersistName } from '../core/runtime/naming-persist.js';
 import { generateRecap } from '../core/runtime/recap.js';
 import { readRoadmap } from '../core/runtime/roadmap.js';
+import { isReviewBoundary } from '../core/runtime/session-visibility.js';
 // ---------------------------------------------------------------------------
 // Tuning constants
 // ---------------------------------------------------------------------------
@@ -79,36 +85,56 @@ function messageText(msg) {
         .join('\n')
         .trim();
 }
-/** Concatenate the FIRST and MOST-RECENT CONVO_EDGE_MESSAGES user/assistant
- *  messages into a single `User:`/`Agent:` transcript (each message capped at
- *  MESSAGE_CHAR_BUDGET chars), with an omission marker where the middle was
- *  dropped — the opening messages carry the original request the brief exists
- *  to surface. Excludes tool calls/results (role toolResult, plus toolCall/
- *  thinking content blocks dropped by messageText) and extension-injected
- *  custom messages (entry.type !== 'message'). Returns '' when there is nothing
- *  to summarize. */
-function buildConversation(sm) {
+/** Return the full conversation for ordinary nodes, or only messages after this
+ * review's first durable boundary. A missing review marker intentionally has no
+ * recap input: inherited context must never become widget or naming text. */
+function recapEntries(sm, reviewId) {
     let entries;
     try {
         entries = sm.getEntries();
     }
     catch {
-        return '';
+        return { entries: [], boundaryPresent: reviewId === undefined };
     }
+    if (reviewId === undefined)
+        return { entries, boundaryPresent: true };
+    const markerIndex = entries.findIndex((entry) => isReviewBoundary(entry, reviewId));
+    return markerIndex === -1
+        ? { entries: [], boundaryPresent: false }
+        : { entries: entries.slice(markerIndex + 1), boundaryPresent: true };
+}
+/** Extract every literal user/assistant message in chronological order. */
+function conversationParts(sm, messageCharBudget, assistantPartial, reviewId) {
+    const { entries, boundaryPresent } = recapEntries(sm, reviewId);
     const parts = [];
-    for (const e of entries) {
-        if (e.type !== 'message' || e.message === undefined)
-            continue;
-        const role = e.message.role;
+    const append = (message) => {
+        const role = message.role;
         if (role !== 'user' && role !== 'assistant')
-            continue; // drop toolResult etc.
-        let text = messageText(e.message);
+            return; // drop toolResult etc.
+        let text = messageText(message);
         if (text === '')
+            return;
+        if (text.length > messageCharBudget)
+            text = `${text.slice(0, messageCharBudget)} …[truncated]`;
+        const part = `${role === 'user' ? 'User' : 'Agent'}: ${text}`;
+        // Some pi versions expose the in-progress assistant message through the
+        // session manager as well as message_update. Keep one latest snapshot.
+        if (parts.at(-1) !== part)
+            parts.push(part);
+    };
+    for (const e of entries) {
+        if (e.type !== 'message' || e.message === undefined)
             continue;
-        if (text.length > MESSAGE_CHAR_BUDGET)
-            text = `${text.slice(0, MESSAGE_CHAR_BUDGET)} …[truncated]`;
-        parts.push(`${role === 'user' ? 'User' : 'Agent'}: ${text}`);
+        append(e.message);
     }
+    if (boundaryPresent && assistantPartial?.role === 'assistant')
+        append(assistantPartial);
+    return parts;
+}
+/** Concatenate the first and most-recent messages for the compact inactivity
+ *  briefing. The opening request and current state are the useful recap inputs. */
+function buildConversation(sm, assistantPartial, reviewId) {
+    const parts = conversationParts(sm, MESSAGE_CHAR_BUDGET, assistantPartial, reviewId);
     if (parts.length === 0)
         return '';
     if (parts.length <= CONVO_EDGE_MESSAGES * 2)
@@ -120,6 +146,22 @@ function buildConversation(sm) {
         ...parts.slice(parts.length - CONVO_EDGE_MESSAGES),
     ].join('\n\n');
 }
+/** A bounded chronological sample spanning the whole conversation for title
+ *  regeneration. It keeps the one-shot title request practical while giving new
+ *  information from the middle and end equal weight with the opening request. */
+function buildNamingConversation(sm, assistantPartial, reviewId) {
+    const parts = conversationParts(sm, 600, assistantPartial, reviewId);
+    if (parts.length === 0)
+        return '';
+    const maxParts = 48;
+    if (parts.length <= maxParts)
+        return parts.join('\n\n');
+    const sampled = Array.from({ length: maxParts }, (_, index) => {
+        const sourceIndex = Math.round(index * (parts.length - 1) / (maxParts - 1));
+        return parts[sourceIndex];
+    });
+    return sampled.join('\n\n');
+}
 // ---------------------------------------------------------------------------
 // Extension
 // ---------------------------------------------------------------------------
@@ -129,7 +171,7 @@ function buildConversation(sm) {
  * Returns immediately (inert) when CRTR_NODE_ID is absent — a plain pi session
  * or legacy job agent loads it as a no-op.
  */
-export function registerCanvasRecap(pi) {
+export function registerCanvasRecap(pi, recapGenerator = generateRecap, nameRegenerator = regenerateAndPersistName) {
     const nodeId = process.env['CRTR_NODE_ID'];
     if (nodeId === undefined || nodeId.trim() === '')
         return; // not a canvas node
@@ -148,12 +190,28 @@ export function registerCanvasRecap(pi) {
     };
     /** Wall-clock of the most recent user/assistant message. The idle clock. */
     let lastMessageAt = Date.now();
-    /** True while a recap is currently shown (so we generate at most once per
-     *  idle window, and know whether a clear is needed on the next message). */
+    /** Monotonic conversation activity version used to judge generation results. */
+    let activityVersion = 0;
+    /** Latest in-progress assistant message, which is absent from persisted entries. */
+    let liveAssistantPartial;
+    /** Whether a recap is currently shown and whether conversation activity has
+     *  made that recap eligible for replacement in the next idle window. */
     let recapShown = false;
+    let recapStale = false;
+    /** A markerless review has no safe recap input until new activity occurs. */
+    let recapInputUnavailable = false;
     /** True while a briefing generation is in flight (so we don't fire a second). */
     let generating = false;
     const canPaint = () => ui !== undefined && typeof ui.setWidget === 'function';
+    /** A manual recap is a model call that can take tens of seconds. Confirm its
+     * start immediately so selecting it from Alt+C is never mistaken for a dead
+     * menu action. The finished widget remains the durable completion signal. */
+    const notify = (message) => {
+        try {
+            ui?.notify?.(message, 'info');
+        }
+        catch { /* best-effort */ }
+    };
     const clearRecap = () => {
         if (!canPaint())
             return;
@@ -176,15 +234,93 @@ export function registerCanvasRecap(pi) {
         }
         catch { /* best-effort */ }
     };
-    /** A user or assistant message landed: reset the idle clock and clear any
-     *  shown recap (the conversation has moved on). */
+    /** Conversation activity resets the idle clock. A shown recap remains useful
+     *  context while stale and stays pinned until a replacement succeeds. */
     const onMessage = () => {
         lastMessageAt = Date.now();
-        if (recapShown) {
+        activityVersion += 1;
+        recapInputUnavailable = false;
+        if (recapShown)
+            recapStale = true;
+    };
+    /** Re-name only when the live title is still crouter's generated node label.
+     *  A different title came from a person and is left intact. */
+    const refreshAutomaticName = (conversation) => {
+        if (pi.getSessionName === undefined || pi.setSessionName === undefined)
+            return;
+        const meta = getNode(nodeId);
+        if (meta === null)
+            return;
+        // `/rename` persists a person's explicit handle on the node as well as in
+        // the pi session. Such a handle remains authoritative even when its live
+        // session text exactly matches editorLabel(meta).
+        if (meta.name.trim() !== '' && meta.name !== meta.kind)
+            return;
+        const original = editorLabel(meta);
+        if (pi.getSessionName() !== original)
+            return;
+        nameRegenerator(nodeId, conversation, () => pi.getSessionName?.() === original, (named) => {
+            try {
+                pi.setSessionName?.(editorLabel(named));
+            }
+            catch { /* best-effort */ }
+        });
+    };
+    /** Start one briefing generation. A manual request refreshes an untouched
+     *  generated title as a separate best-effort task from the broader conversation. */
+    const requestRecap = (manual) => {
+        if (!canPaint() || sessionManager === undefined || generating)
+            return;
+        const assistantPartial = liveAssistantPartial;
+        const reviewId = getNode(nodeId)?.review_binding?.review_id;
+        const conversation = buildConversation(sessionManager, assistantPartial, reviewId);
+        if (conversation === '') {
+            recapInputUnavailable = true;
             recapShown = false;
+            recapStale = false;
             clearRecap();
+            return;
+        }
+        recapInputUnavailable = false;
+        const namingConversation = manual ? buildNamingConversation(sessionManager, assistantPartial, reviewId) : '';
+        const snapshotVersion = activityVersion;
+        generating = true;
+        if (manual) {
+            notify('Generating recap…');
+            refreshAutomaticName(namingConversation);
         }
+        let roadmap;
+        try {
+            roadmap = readRoadmap(nodeId) ?? undefined;
+        }
+        catch { /* best-effort */ }
+        recapGenerator(conversation, (briefing) => {
+            generating = false;
+            // A manual recap belongs to its click-time snapshot and always paints.
+            // Automatic work paints only while its idle snapshot remains current.
+            if ((!manual && activityVersion !== snapshotVersion) || !canPaint())
+                return;
+            recapShown = true;
+            recapStale = activityVersion !== snapshotVersion;
+            showRecap(briefing);
+            if (manual)
+                notify('Recap ready');
+        }, liveModel, roadmap);
+        // generateRecap is silent on failure (never calls back), so clear the
+        // in-flight flag after the timeout window even if no callback fires.
+        setTimeout(() => { generating = false; }, 30_000).unref?.();
     };
+    // The prefix menu sends `/recap` into the focused viewer. As an extension
+    // command it never becomes a user message or starts an agent turn.
+    pi.registerCommand?.('recap', {
+        description: 'Generate a Goal/State recap and refresh the original generated session title',
+        handler: (_args, ctx) => {
+            ui = ctx.ui;
+            sessionManager = ctx.sessionManager;
+            captureLiveModel(ctx);
+            requestRecap(true);
+        },
+    });
     // -------------------------------------------------------------------------
     // Events
     // -------------------------------------------------------------------------
@@ -195,17 +331,27 @@ export function registerCanvasRecap(pi) {
         // Fresh session / hot-swap: start the idle clock now and drop any stale
         // recap that bled through a /reload.
         lastMessageAt = Date.now();
+        activityVersion = 0;
+        liveAssistantPartial = undefined;
         recapShown = false;
+        recapStale = false;
+        recapInputUnavailable = false;
         generating = false;
         clearRecap();
     });
     pi.on('input', (_event, _ctx) => {
-        // Every user message (any source) is activity — reset + clear.
+        // Every user message (any source) is activity.
+        onMessage();
+    });
+    pi.on('message_update', (event, _ctx) => {
+        const message = event?.message;
+        if (message?.role === 'assistant')
+            liveAssistantPartial = message;
         onMessage();
     });
     pi.on('turn_end', (_event, ctx) => {
-        // A completed assistant turn is activity — reset + clear, and remember the
-        // exact model/provider that successfully produced it for the later recap.
+        // The completed assistant message now lives in the session manager.
+        liveAssistantPartial = undefined;
         captureLiveModel(ctx);
         onMessage();
     });
@@ -218,34 +364,11 @@ export function registerCanvasRecap(pi) {
         try {
             if (!canPaint() || sessionManager === undefined)
                 return;
-            if (recapShown || generating)
+            if (recapInputUnavailable || (recapShown && !recapStale) || generating)
                 return;
             if (Date.now() - lastMessageAt < idleMs())
                 return;
-            const convo = buildConversation(sessionManager);
-            if (convo === '')
-                return; // nothing to summarize yet
-            // Snapshot the clock: if a message arrives while generation runs, discard the
-            // (now-stale) result instead of painting over the live conversation.
-            const startedAt = lastMessageAt;
-            generating = true;
-            let roadmap;
-            try {
-                roadmap = readRoadmap(nodeId) ?? undefined;
-            }
-            catch { /* best-effort */ }
-            generateRecap(convo, (briefing) => {
-                generating = false;
-                if (lastMessageAt !== startedAt)
-                    return; // a message landed mid-flight
-                if (!canPaint())
-                    return;
-                recapShown = true;
-                showRecap(briefing);
-            }, liveModel, roadmap);
-            // generateRecap is silent on failure (never calls back), so clear the
-            // in-flight flag after the timeout window even if no callback fires.
-            setTimeout(() => { generating = false; }, 30_000).unref?.();
+            requestRecap(false);
         }
         catch {
             /* timer is best-effort */