@nanobpm/nano-workforce 0.185.0 → 0.186.0

package/app/agentic/cockpit/transcript-derive.ts

@@ -1,30 +1,53 @@
-// The cockpit STRUCTURED transcript view — derived from the one event fold (ADR 0056, #251).
+// The cockpit STRUCTURED transcript view — derived from the one ORDERED DISPLAY projection (#566, #757).
 //
 // Beside the byte-level replay (`transcript-render.ts` feeds stored chunks through the live terminal
-// renderer for pixel-faithful playback), the cockpit can also show a STRUCTURED view of a captured
-// session: its derived message history, tool cards and per-turn boundaries. Per the issue's acceptance
-// criterion, that structured view is a DERIVATION of the one typed event log — it re-parses nothing.
-// It reads a fetched transcript page and folds it through the single {@link deriveViewFromChunks} entry
-// point (which routes every chunk through the ONE parser, `parseTranscriptEvent`), so there is no
-// second parser of the raw bytes. The drift-guard test enforces that this module never parses chunks
-// itself.
+// renderer for pixel-faithful playback), the cockpit shows a STRUCTURED view of a captured session. That
+// view is a DERIVATION of the one typed event log — it re-parses nothing. It folds the stored chunks
+// through the single {@link parseTranscriptEvent} parser and the canonical ORDERED DISPLAY projection
+// ({@link createDisplayProjection}, agentic #566): the projection coalesces transport-fragmented message
+// deltas ("I", "not", "ice I am act", …) back into ONE growing block per logical message, and interleaves
+// text blocks, tool cards and permission prompts in strict chronological (offset) order. So a split word
+// reconstructs into exactly that word in one coherent block — never one bordered card per delta — and a
+// tool call issued mid-message renders between the text before and after it (issue #757). The raw log,
+// its offsets and byte-faithful replay are untouched; the drift-guard test enforces this module never
+// parses chunks itself.
 //
-// Framework-free and side-effect-free, like the sibling cockpit views: the same report always yields
-// the same {@link DerivedView}, and the renderer draws into the injected {@link DocumentLike} subset so
-// a real DOM satisfies it at runtime and an in-memory fake satisfies it for DOM-free Node tests.
+// INCREMENTAL, not rebuild-on-every-chunk. {@link createIncrementalTranscript} keeps the display
+// projection and a `blockId → DOM node` map as mutable state, so a live delta updates the ONE active
+// block's node in place (append a new node, or patch an existing one) instead of rebuilding the whole
+// transcript tree. That is what lets the browser adapter (`pages/cockpit/mount.js`) preserve the
+// operator's selection, expansion and scroll position and auto-follow only at the tail. {@link
+// renderDerivedTranscript} is the pure batch convenience over the same fold — historical replay renders
+// IDENTICALLY to the final live rendering because both drive the one incremental renderer.
+//
+// Framework-free and DOM-agnostic, like the sibling cockpit views: it draws into the injected {@link
+// DocumentLike} subset so a real DOM satisfies it at runtime and an in-memory fake satisfies it for
+// DOM-free Node tests.
 import type { DocumentLike, ElementLike } from "@nanobpm/agentic/cockpit";
+import { createDisplayProjection } from "../transcript-display.ts";
 import {
   type DerivedPermission,
   type DerivedTool,
   type DerivedView,
+  type DisplayBlock,
+  type DisplayGapBlock,
+  type DisplayProjection,
+  type DisplayTextBlock,
   deriveViewFromChunks,
   optionKindAllows,
+  parseTranscriptEvent,
+  type StoredChunk,
+  type TranscriptEvent,
+  utf8ByteLength,
 } from "../transcript-events.ts";
 import type { TranscriptDataReport } from "./transcript-render.ts";
 
 /**
- * Derive the structured view of a fetched transcript page by folding its stored chunks through the ONE
- * event parser + fold. Pure: the cockpit reads THIS instead of re-parsing raw frame bytes.
+ * Derive the structured (event-fold) view of a fetched transcript page — the flat message/tool/permission
+ * history, per-turn structure and raw-byte accounting. This is the {@link DerivedView} fold, kept for the
+ * raw-fidelity footer and summary counts; the ordered, human-facing block SEQUENCE is the separate
+ * display projection {@link renderDerivedTranscript} draws. Pure: the cockpit reads THESE instead of
+ * re-parsing raw frame bytes.
  */
 export function deriveTranscript(data: TranscriptDataReport): DerivedView {
   return deriveViewFromChunks(data.entries);
@@ -156,9 +179,11 @@ function detectDiff(tool: DerivedTool): DetectedDiff | undefined {
   return undefined;
 }
 
-/** Render one tool card: name, status, args + result content, and a distinguishable diff block. */
-function renderTool(doc: DocumentLike, tool: DerivedTool): ElementLike {
-  const card = el(doc, "div", "cockpit-transcript-tool");
+/** Fill an EXISTING tool card node with one tool's content (name, status, args/result, diff block). Clears
+ *  the node first so it is safe to re-invoke in place when the tool's result later arrives (bounded to
+ *  this one card — no sibling block is touched). */
+function applyTool(card: ElementLike, doc: DocumentLike, tool: DerivedTool): void {
+  card.replaceChildren();
   card.setAttribute("data-tool", tool.name);
   card.setAttribute("data-offset", String(tool.offset));
   card.setAttribute("data-status", tool.result === undefined ? "pending" : tool.result.ok ? "ok" : "error");
@@ -195,6 +220,12 @@ function renderTool(doc: DocumentLike, tool: DerivedTool): ElementLike {
     resEl.setAttribute("data-tool-result", "true");
     card.appendChild(resEl);
   }
+}
+
+/** Render one tool card: name, status, args + result content, and a distinguishable diff block. */
+function renderTool(doc: DocumentLike, tool: DerivedTool): ElementLike {
+  const card = el(doc, "div", "cockpit-transcript-tool");
+  applyTool(card, doc, tool);
   return card;
 }
 
@@ -204,8 +235,8 @@ function renderTool(doc: DocumentLike, tool: DerivedTool): ElementLike {
  * - a `yolo` request → informational only (yolo auto-allows, it never prompts a human);
  * - a resolved permission → settled (`allowed`/`denied`), showing the chosen option, no live buttons.
  */
-function renderPermission(doc: DocumentLike, perm: DerivedPermission, options: RenderDerivedTranscriptOptions): ElementLike {
-  const card = el(doc, "div", "cockpit-transcript-permission");
+function applyPermission(card: ElementLike, doc: DocumentLike, perm: DerivedPermission, options: RenderDerivedTranscriptOptions): void {
+  card.replaceChildren();
   card.setAttribute("data-permission", "request");
   card.setAttribute("data-policy", perm.policy);
   card.setAttribute("data-call-id", perm.callId);
@@ -222,14 +253,14 @@ function renderPermission(doc: DocumentLike, perm: DerivedPermission, options: R
     settled.setAttribute("data-chosen-option", perm.resolved.optionId);
     if (perm.resolved.by !== undefined) settled.setAttribute("data-by", perm.resolved.by);
     card.appendChild(settled);
-    return card;
+    return;
   }
 
   if (perm.policy === "yolo") {
     // Informational: yolo auto-allows and never prompts a human, so no Allow/Deny buttons.
     card.setAttribute("data-status", "auto");
     card.appendChild(el(doc, "div", "cockpit-transcript-permission-note", "Auto-allowed (yolo) — no operator prompt."));
-    return card;
+    return;
   }
 
   // Pending escalate: one interactive button per offered option, wired to the resolve seam.
@@ -249,65 +280,268 @@ function renderPermission(doc: DocumentLike, perm: DerivedPermission, options: R
     actions.appendChild(button);
   }
   card.appendChild(actions);
+}
+
+/**
+ * Render one permission prompt card from a {@link DerivedPermission}:
+ * - a pending `escalate` request → interactive Allow/Deny buttons wired to `onPermissionResolve`;
+ * - a `yolo` request → informational only (yolo auto-allows, it never prompts a human);
+ * - a resolved permission → settled (`allowed`/`denied`), showing the chosen option, no live buttons.
+ */
+function renderPermission(doc: DocumentLike, perm: DerivedPermission, options: RenderDerivedTranscriptOptions): ElementLike {
+  const card = el(doc, "div", "cockpit-transcript-permission");
+  applyPermission(card, doc, perm, options);
   return card;
 }
 
+/** Fill an EXISTING text-block node with a coalesced message's text + offsets. The block is ONE growing
+ *  node per logical message — a delta patches this node's `textContent` in place (never a new card per
+ *  fragment), so a split word reconstructs into exactly that word. */
+function applyText(node: ElementLike, block: DisplayTextBlock): void {
+  node.setAttribute("data-role", block.role);
+  node.setAttribute("data-offset", String(block.startOffset));
+  node.setAttribute("data-end-offset", String(block.endOffset));
+  node.setAttribute("data-block-id", block.id);
+  if (block.messageId !== undefined) node.setAttribute("data-message-id", block.messageId);
+  node.setAttribute("data-complete", String(block.complete));
+  node.textContent = block.text;
+}
+
+/** Render one coalesced-message text block (a single growing node). */
+function renderText(doc: DocumentLike, block: DisplayTextBlock): ElementLike {
+  const node = el(doc, "div", "cockpit-transcript-message");
+  applyText(node, block);
+  return node;
+}
+
+/** Fill an EXISTING retention-gap node. A gap is a first-class visible break so a reattach that dropped
+ *  chunks never implies the surrounding text is continuous; its `beforeOffset` is anchored once the first
+ *  post-gap block opens. */
+function applyGap(node: ElementLike, block: DisplayGapBlock): void {
+  node.setAttribute("data-gap", "true");
+  node.setAttribute("data-block-id", block.id);
+  if (block.beforeOffset !== undefined) node.setAttribute("data-before-offset", String(block.beforeOffset));
+  node.textContent = "⋯ retained-data gap — earlier output was evicted ⋯";
+}
+
+/** Render one retention-gap block. */
+function renderGap(doc: DocumentLike, block: DisplayGapBlock): ElementLike {
+  const node = el(doc, "div", "cockpit-transcript-gap");
+  applyGap(node, block);
+  return node;
+}
+
+/** Build a fresh DOM node for any display block kind. */
+function renderBlock(doc: DocumentLike, block: DisplayBlock, options: RenderDerivedTranscriptOptions): ElementLike {
+  switch (block.kind) {
+    case "text":
+      return renderText(doc, block);
+    case "tool":
+      return renderTool(doc, block.tool);
+    case "permission":
+      return renderPermission(doc, block.permission, options);
+    case "gap":
+      return renderGap(doc, block);
+  }
+}
+
+/** Patch an EXISTING block node in place (bounded to that one block — no sibling node is touched). */
+function patchBlock(node: ElementLike, doc: DocumentLike, block: DisplayBlock, options: RenderDerivedTranscriptOptions): void {
+  switch (block.kind) {
+    case "text":
+      applyText(node, block);
+      return;
+    case "tool":
+      applyTool(node, doc, block.tool);
+      return;
+    case "permission":
+      applyPermission(node, doc, block.permission, options);
+      return;
+    case "gap":
+      applyGap(node, block);
+      return;
+  }
+}
+
 /**
- * Render the DERIVED structured view of a fetched transcript into `host`, replacing whatever was there.
- * Draws per-turn sections with their derived messages, rich tool/diff cards and permission prompts, plus
- * a raw-fidelity footer (retained bytes/chunks) so the operator sees the byte-replay is preserved
- * alongside the structure. Idempotent — call again on each refresh. Everything it shows is a derivation
- * of the one event log. `options.onPermissionResolve`, when provided, is invoked by a pending
- * escalate-permission prompt's Allow/Deny buttons.
+ * A STATEFUL, incremental transcript renderer over a `host` element. It maintains the ordered
+ * {@link DisplayBlock} sequence (via the canonical {@link createDisplayProjection}) and a `blockId → DOM
+ * node` map, so feeding it one live chunk at a time updates just the ONE touched block's node in place —
+ * append a brand-new block node, or patch an existing block's node (a growing text delta, a tool result
+ * pairing, a permission resolution, or a now-anchored gap) — instead of rebuilding the whole transcript
+ * tree. That bounded update is what lets the browser adapter preserve selection, expansion and scroll.
+ *
+ * DOM shape (stable across live growth so unaffected nodes are never replaced):
+ *   div.cockpit-transcript-derived[data-*]
+ *     div.cockpit-transcript-blocks   ← ordered block nodes are appended here / patched in place
+ *     div.cockpit-transcript-empty    ← shown (data-empty="true") only while there are zero blocks
+ *     footer.cockpit-transcript-raw   ← retained raw bytes/chunks (byte-replay is preserved alongside)
  */
-export function renderDerivedTranscript(
+export interface IncrementalTranscript {
+  /** The rendered root (a `cockpit-transcript-derived` element) appended under the host. */
+  readonly root: ElementLike;
+  /**
+   * Fold ONE stored chunk (by offset) into the display and update the DOM minimally. Idempotent on
+   * offset — re-feeding an already-applied offset (reconnect, pagination overlap, a duplicated chunk) is
+   * a no-op, so replayed text never doubles. Feed chunks in offset order (the projection drops a late
+   * lower offset rather than merging it out of place).
+   */
+  applyChunk(chunk: StoredChunk): void;
+  /**
+   * Record a retention gap at the current tail BEFORE feeding the post-gap chunks: the consumer resumed
+   * from an offset older than the oldest retained chunk, so what follows is NOT continuous with what
+   * precedes. Renders a visible break; its `beforeOffset` is anchored when the next block opens.
+   */
+  noteGap(): void;
+  /** A snapshot of the ordered display blocks as they stand now (for tests/inspection). */
+  blocks(): readonly DisplayBlock[];
+}
+
+/** Running summary tallies for the root attributes + raw footer, maintained WITHOUT re-folding. */
+interface Tallies {
+  text: number;
+  tool: number;
+  permission: number;
+  gap: number;
+  turns: number;
+  rawBytes: number;
+  rawChunks: number;
+  lifecycle: "open" | "completed" | "exited";
+}
+
+/**
+ * Build the incremental renderer's stable DOM scaffold under `host` and return the mutable render state.
+ * Shared by {@link createIncrementalTranscript} (live) and {@link renderDerivedTranscript} (batch) so
+ * historical replay renders IDENTICALLY to the final live rendering.
+ */
+export function createIncrementalTranscript(
   host: ElementLike,
   doc: DocumentLike,
-  data: TranscriptDataReport,
+  stream: string,
   options: RenderDerivedTranscriptOptions = {},
-): DerivedTranscriptDom {
-  const view = deriveTranscript(data);
+): IncrementalTranscript {
   host.replaceChildren();
+  const projection: DisplayProjection = createDisplayProjection();
+  const nodes = new Map<string, ElementLike>();
+  const tallies: Tallies = { text: 0, tool: 0, permission: 0, gap: 0, turns: 0, rawBytes: 0, rawChunks: 0, lifecycle: "open" };
+  // A turn opens implicitly before the first structured block even without an explicit `turn` event
+  // (mirrors deriveView's implicit turn 0), so any structured content means at least one turn.
+  let structured = false;
+
   const root = el(doc, "div", "cockpit-transcript-derived");
-  root.setAttribute("data-stream", data.stream);
-  root.setAttribute("data-lifecycle", view.lifecycle);
-  root.setAttribute("data-turn-count", String(view.turns.length));
-  root.setAttribute("data-message-count", String(view.messages.length));
-  root.setAttribute("data-tool-count", String(view.tools.length));
-  root.setAttribute("data-permission-count", String(view.permissions.length));
-
-  if (view.turns.length === 0) {
-    const empty = el(doc, "div", "cockpit-transcript-empty", "No structured events derived — raw replay only.");
-    empty.setAttribute("data-empty", "true");
-    root.appendChild(empty);
+  root.setAttribute("data-stream", stream);
+  const blocksHost = el(doc, "div", "cockpit-transcript-blocks");
+  const empty = el(doc, "div", "cockpit-transcript-empty");
+  const footer = el(doc, "footer", "cockpit-transcript-raw");
+  root.appendChild(blocksHost);
+  root.appendChild(empty);
+  root.appendChild(footer);
+  host.appendChild(root);
+
+  function refreshSummary(): void {
+    const turnCount = tallies.turns > 0 ? tallies.turns : structured ? 1 : 0;
+    root.setAttribute("data-lifecycle", tallies.lifecycle);
+    root.setAttribute("data-turn-count", String(turnCount));
+    root.setAttribute("data-message-count", String(tallies.text));
+    root.setAttribute("data-tool-count", String(tallies.tool));
+    root.setAttribute("data-permission-count", String(tallies.permission));
+    root.setAttribute("data-gap-count", String(tallies.gap));
+    root.setAttribute("data-block-count", String(nodes.size));
+
+    const hasBlocks = tallies.text + tallies.tool + tallies.permission > 0;
+    // Toggle (never remove — ElementLike has no removeChild) so a live first block clears the empty note
+    // without rebuilding, and an all-raw page still shows exactly one data-empty="true" element.
+    empty.setAttribute("data-empty", String(!hasBlocks));
+    empty.textContent = hasBlocks ? "" : "No structured events derived — raw replay only.";
+
+    footer.setAttribute("data-raw-bytes", String(tallies.rawBytes));
+    footer.setAttribute("data-raw-chunks", String(tallies.rawChunks));
+    footer.textContent = `${tallies.rawChunks} raw chunk(s) · ${tallies.rawBytes} B retained for replay`;
+  }
+
+  function countAppended(block: DisplayBlock): void {
+    structured = structured || block.kind !== "gap";
+    if (block.kind === "text") tallies.text++;
+    else if (block.kind === "tool") tallies.tool++;
+    else if (block.kind === "permission") tallies.permission++;
+    else tallies.gap++;
   }
 
-  for (const turn of view.turns) {
-    const section = el(doc, "section", "cockpit-transcript-turn");
-    section.setAttribute("data-turn", String(turn.index));
-    section.setAttribute("data-steps", String(turn.steps));
-    section.appendChild(el(doc, "h3", "cockpit-transcript-turn-title", `Turn ${turn.index}`));
-    for (const msg of turn.messages) {
-      const row = el(doc, "div", "cockpit-transcript-message", msg.text);
-      row.setAttribute("data-role", msg.role);
-      row.setAttribute("data-offset", String(msg.offset));
-      section.appendChild(row);
+  /** Reconcile ONE projection apply-result into the DOM: append a new node, patch an existing one, and/or
+   *  patch a secondary now-anchored gap. Bounded to the touched block(s) — no unaffected node is replaced. */
+  function reconcile(changed: DisplayBlock | undefined, appended: boolean, anchored: DisplayBlock | undefined): void {
+    if (changed !== undefined) {
+      if (appended) {
+        const node = renderBlock(doc, changed, options);
+        nodes.set(changed.id, node);
+        blocksHost.appendChild(node);
+        countAppended(changed);
+      } else {
+        const node = nodes.get(changed.id);
+        if (node !== undefined) patchBlock(node, doc, changed, options);
+      }
     }
-    for (const tool of turn.tools) {
-      section.appendChild(renderTool(doc, tool));
+    if (anchored !== undefined) {
+      const node = nodes.get(anchored.id);
+      if (node !== undefined) patchBlock(node, doc, anchored, options);
     }
-    for (const perm of turn.permissions) {
-      section.appendChild(renderPermission(doc, perm, options));
+  }
+
+  function applyEvent(event: TranscriptEvent): void {
+    // Raw bytes feed the byte-replay footer but produce no display block (the projection ignores them).
+    if (event.kind === "stream-chunk") {
+      tallies.rawChunks++;
+      tallies.rawBytes += utf8ByteLength(event.chunk);
+    } else if (event.kind === "turn") {
+      tallies.turns++;
+    } else if (event.kind === "lifecycle") {
+      tallies.lifecycle = event.phase;
     }
-    root.appendChild(section);
+    const result = projection.apply(event);
+    reconcile(result.changed, result.appended, result.anchored);
   }
 
-  const footer = el(doc, "footer", "cockpit-transcript-raw");
-  footer.setAttribute("data-raw-bytes", String(view.rawByteLength));
-  footer.setAttribute("data-raw-chunks", String(view.rawChunkCount));
-  footer.textContent = `${view.rawChunkCount} raw chunk(s) · ${view.rawByteLength} B retained for replay`;
-  root.appendChild(footer);
+  refreshSummary();
 
-  host.appendChild(root);
-  return { root };
+  return {
+    root,
+    applyChunk(chunk: StoredChunk): void {
+      applyEvent(parseTranscriptEvent(chunk));
+      refreshSummary();
+    },
+    noteGap(): void {
+      const result = projection.noteGap();
+      reconcile(result.changed, result.appended, result.anchored);
+      refreshSummary();
+    },
+    blocks(): readonly DisplayBlock[] {
+      return projection.blocks();
+    },
+  };
+}
+
+/**
+ * Render the DERIVED, ORDERED display of a fetched transcript page into `host`, replacing whatever was
+ * there — the pure BATCH convenience over {@link createIncrementalTranscript}. Draws one growing text
+ * block per logical message, with tool/diff cards and permission prompts interleaved in chronological
+ * (offset) order, plus a raw-fidelity footer (retained bytes/chunks) so the byte-replay stays visibly
+ * preserved. A retention `gap` on the page (`data.gap`) renders a leading visible break. Idempotent —
+ * call again on each refresh. Everything it shows is a derivation of the one event log, and it renders
+ * IDENTICALLY to the final live rendering (same incremental fold). `options.onPermissionResolve`, when
+ * provided, is invoked by a pending escalate-permission prompt's Allow/Deny buttons.
+ */
+export function renderDerivedTranscript(
+  host: ElementLike,
+  doc: DocumentLike,
+  data: TranscriptDataReport,
+  options: RenderDerivedTranscriptOptions = {},
+): DerivedTranscriptDom {
+  const incremental = createIncrementalTranscript(host, doc, data.stream, options);
+  // A page-level retention gap precedes the page's first chunk: note it before folding so a leading
+  // visible break renders (a reattach that dropped chunks never implies false continuity).
+  if (data.gap) incremental.noteGap();
+  // The batch path folds the SAME chunks the live path does, in offset order, through the ONE projection,
+  // so historical and live rendering are byte-for-byte the same tree.
+  for (const chunk of [...data.entries].sort((a, b) => a.offset - b.offset)) incremental.applyChunk(chunk);
+  return { root: incremental.root };
 }

package/app/agentic/transcript-display.ts

@@ -0,0 +1,17 @@
+// nano-workforce — the ordered DISPLAY projection, DERIVED from its one owner (agentic #566).
+//
+// Sibling of `transcript-events.ts`: where that barrel re-exports the transcript EVENT grammar (the one
+// parser + fold), THIS barrel re-exports the canonical ordered DISPLAY derivation — the projection that
+// coalesces transport-fragmented message deltas back into logical blocks and interleaves them
+// chronologically with tool cards and permission prompts (`createDisplayProjection` / `deriveDisplay`).
+// The cockpit renders THIS instead of the raw per-event groups, so a split word reconstructs into one
+// block and text/tool/permission order never scrambles.
+//
+// Why a SEPARATE barrel rather than folding these into `transcript-events.ts`: the browser bundle
+// (`scripts/build-cockpit-browser.ts`) emits one generated ESM sibling per agentic source module, and
+// the display projection lives in agentic's own `dist/transcript/display.js` — a self-contained,
+// browser-safe module distinct from `events.js`. Keeping the display import on its own specifier lets
+// the bundle rewrite it to `./transcript-display.js` (agentic's display module) while the event import
+// still rewrites to `./transcript-events.js`. Both remain thin re-exports of the ONE agentic source of
+// truth — there is no local display algorithm here (Derivation Over Duplication).
+export { createDisplayProjection, deriveDisplay } from "@nanobpm/agentic/transcript";

package/app/readiness.test.ts

@@ -220,6 +220,57 @@ test("matchCapability: the bare '#274' ref form resolves identically to 'nano-id
   assertEquals(res.bind?.resolvedArtifact, "@nanobpm/urban@1.2.3");
 });
 
+// ── #764: single-package repos tag releases `v<version>` / bare `<version>` (semantic-release default) ──
+
+const c8Match = { capabilityRef: "c8ctl-plugin-nano#206", package: "c8ctl-plugin-nano" };
+
+test("#764 matchCapability: a `v<version>` release (body refs the cap) resolves in a single-package repo", () => {
+  // Red before the fix: `v1.58.0` never matched versionForPackage(tag, 'c8ctl-plugin-nano'),
+  // so the gate reported 'not published yet' though the npm package WAS published.
+  const res = matchCapability(c8Match, [rel("v1.58.0", [206])]);
+  assert(res.ready);
+  assertEquals(res.bind?.resolvedArtifact, "c8ctl-plugin-nano@1.58.0");
+});
+
+test("#764 matchCapability: a bare `<version>` release resolves the same way in a single-package repo", () => {
+  const res = matchCapability(c8Match, [rel("1.58.0", [206])]);
+  assert(res.ready);
+  assertEquals(res.bind?.resolvedArtifact, "c8ctl-plugin-nano@1.58.0");
+});
+
+test("#764 monorepo guard: a stray `v2.0.0` alongside package-scoped tags is NOT attributed to another package", () => {
+  // The repo emits package-scoped tags → it is a monorepo → bare `v` tags are ignored, so the stray
+  // v2.0.0 can never leak into @nanobpm/other's resolution.
+  const releases = [rel("@nanobpm/other@1.0.0", [200]), rel("v2.0.0", [274])];
+  const res = matchCapability({ capabilityRef: "nano-ide#274", package: "@nanobpm/other" }, releases);
+  assert(!res.ready, "the stray v2.0.0 must not resolve #274 for @nanobpm/other");
+});
+
+test("#764 summariseCapabilityCandidates: shows the extended `v`-tag candidate in a single-package repo", () => {
+  const summary = summariseCapabilityCandidates(c8Match, [rel("v1.58.0", [206]), rel("v1.57.0", [200])]);
+  assertStringIncludes(summary, "2 c8ctl-plugin-nano release(s) observed");
+  assertStringIncludes(summary, "c8ctl-plugin-nano@1.58.0 refs #206");
+  assertStringIncludes(summary, "c8ctl-plugin-nano@1.57.0 no #206");
+});
+
+test("#764 summariseCapabilityCandidates: in a monorepo a stray `v` tag is not summarised as another package's candidate", () => {
+  const summary = summariseCapabilityCandidates({ capabilityRef: "nano-ide#274", package: "@nanobpm/other" }, [
+    rel("@nanobpm/other@1.0.0", [200]),
+    rel("v2.0.0", [274]),
+  ]);
+  assertStringIncludes(summary, "1 @nanobpm/other release(s) observed");
+  assert(!summary.includes("2.0.0"), "the stray monorepo v2.0.0 is not a candidate for @nanobpm/other");
+});
+
+test("#764 newestPublishedVersion: resolves from `v`-tags under the single-package condition", () => {
+  assertEquals(newestPublishedVersion("c8ctl-plugin-nano", [rel("v1.57.0", []), rel("v1.58.0", [])]), "1.58.0");
+});
+
+test("#764 newestPublishedVersion: a stray `v` tag in a monorepo is ignored for a scoped package", () => {
+  const releases = [rel("@nanobpm/urban@0.9.0", []), rel("v9.9.9", [])];
+  assertEquals(newestPublishedVersion("@nanobpm/urban", releases), "0.9.0");
+});
+
 // ── #514 Defect A: the capability gate is self-diagnosing on escalation ──────────────────────────
 
 test("#514 Defect A summariseCapabilityCandidates: lists candidate releases (newest first) and whether each references the ref", () => {

package/app/readiness.ts

@@ -527,18 +527,58 @@ function bodyReferences(body: string, num: string): boolean {
   return new RegExp(`#${num}(?!\\d)`).test(body);
 }
 
-/** The `<version>` of a release tagged exactly `<package>@<version>` (numeric-dotted), or undefined
- * when the tag belongs to another package or is not a version tag. Per-package scoping is enforced
- * here: a sibling package's provenance can never leak into this package's resolution. */
-function versionForPackage(tag: string, pkg: string): string | undefined {
+/** A numeric-dotted SemVer-ish core, e.g. `1.58.0`. */
+const VERSION_CORE = /^\d+(\.\d+)*$/;
+
+/** Is `tag` a **package-scoped** version tag — `<anything>@<version>` (numeric-dotted), the monorepo
+ * convention (e.g. `@nanobpm/urban@0.54.0`, `c8ctl-plugin-nano@1.58.0`)? Used to decide whether a
+ * repo follows the single-package (`v1.58.0` / bare) convention: a repo is "single-package" only when
+ * it emits NO package-scoped tags at all. Anchored on the LAST `@` so scoped npm names (`@org/name@1.0.0`)
+ * are recognised. */
+function isPackageScopedVersionTag(tag: string): boolean {
+  const at = tag.lastIndexOf("@");
+  if (at <= 0) return false; // no `@`, or a leading `@` (scoped-name start) with nothing before it
+  return VERSION_CORE.test(tag.slice(at + 1).trim());
+}
+
+/** True when the repo's observed release set contains NO `<anything>@<version>`-prefixed package-scoped
+ * tags at all — i.e. it follows the single-package `v<version>` / bare `<version>` convention
+ * (semantic-release default), so a bare `v1.58.0` tag may be attributed to the sole package (#764).
+ * A repo using package-scoped tags is a monorepo: bare `v` tags are ignored there, keeping
+ * per-package provenance scoping airtight (a sibling package's provenance can never leak). */
+function repoIsSinglePackage(releases: readonly GithubRelease[]): boolean {
+  for (const rel of releases) {
+    if (rel && typeof rel.tag === "string" && isPackageScopedVersionTag(rel.tag)) return false;
+  }
+  return true;
+}
+
+/** The `<version>` a release tag carries for `pkg`, or undefined when it belongs to another package /
+ * is not a version tag. A tag is a candidate for `pkg` when **either**:
+ *
+ * 1. it is `<pkg>@<version>` (numeric-dotted) — the monorepo convention, per-package scoped so a
+ *    sibling package's provenance can never leak; **or**
+ * 2. `singlePackage` is true (the repo emits no package-scoped tags — see {@link repoIsSinglePackage})
+ *    AND the tag is `v<version>` or a bare `<version>` — the single-package / semantic-release-default
+ *    convention (#764). In a monorepo (`singlePackage` false) bare `v` tags are ignored, so scoping
+ *    stays airtight. */
+function versionForPackage(tag: string, pkg: string, singlePackage: boolean): string | undefined {
   const prefix = `${pkg}@`;
-  if (!tag.startsWith(prefix)) return undefined;
-  const v = tag.slice(prefix.length).trim();
-  return /^\d+(\.\d+)*$/.test(v) ? v : undefined;
+  if (tag.startsWith(prefix)) {
+    const v = tag.slice(prefix.length).trim();
+    return VERSION_CORE.test(v) ? v : undefined;
+  }
+  if (singlePackage) {
+    const v = (tag.startsWith("v") ? tag.slice(1) : tag).trim();
+    if (VERSION_CORE.test(v)) return v;
+  }
+  return undefined;
 }
 
 /** A compact, deterministic, BOUNDED summary of the capability candidate releases a probe observed
- * (issue #514 Defect A). Lists the releases tagged `<match.package>@<version>` (newest first) and,
+ * (issue #514 Defect A). Lists the releases carrying a resolvable `<match.package>` version — tagged
+ * `<match.package>@<version>`, or (for a single-package repo) a `v<version>`/bare `<version>` tag —
+ * newest first, and,
  * for each, whether its body referenced `match.capabilityRef` — so an escalated capability gate can
  * show a human/agent EXACTLY what the probe saw (a genuine "not published yet" vs. a transient
  * false-negative where a matching release was live but its provenance body was momentarily empty).
@@ -548,6 +588,7 @@ function versionForPackage(tag: string, pkg: string): string | undefined {
 export function summariseCapabilityCandidates(
   match: ProbeMatch | undefined,
   releases: readonly GithubRelease[],
+  singlePackage: boolean = repoIsSinglePackage(releases),
 ): string {
   const pkg = match?.package;
   const ref = match?.capabilityRef;
@@ -556,7 +597,7 @@ export function summariseCapabilityCandidates(
   const candidates: { version: string; refs: boolean }[] = [];
   for (const rel of releases) {
     if (!rel || typeof rel.tag !== "string" || typeof rel.body !== "string") continue;
-    const version = versionForPackage(rel.tag, pkg);
+    const version = versionForPackage(rel.tag, pkg, singlePackage);
     if (!version) continue;
     candidates.push({ version, refs: num !== undefined && bodyReferences(rel.body, num) });
   }
@@ -591,7 +632,8 @@ const CAPABILITY_SUMMARY_LIMIT = 8;
 export function matchCapability(match: ProbeMatch | undefined, releases: readonly GithubRelease[]): ProbeResult {
   const pkg = match?.package;
   const ref = match?.capabilityRef;
-  const observed = summariseCapabilityCandidates(match, releases);
+  const singlePackage = repoIsSinglePackage(releases);
+  const observed = summariseCapabilityCandidates(match, releases, singlePackage);
   if (!pkg || !ref) return { ready: false, detail: "capability: missing package/capabilityRef", observed };
   const num = capabilityNumber(ref);
   if (!num) return { ready: false, detail: "capability: unparseable capabilityRef (no #NNN)", observed };
@@ -599,7 +641,7 @@ export function matchCapability(match: ProbeMatch | undefined, releases: readonl
   let firstVersion: string | undefined;
   for (const rel of releases) {
     if (!rel || typeof rel.tag !== "string" || typeof rel.body !== "string") continue;
-    const version = versionForPackage(rel.tag, pkg);
+    const version = versionForPackage(rel.tag, pkg, singlePackage);
     if (!version) continue;
     if (!bodyReferences(rel.body, num)) continue;
     if (firstVersion === undefined || cmpVersion(version, firstVersion) < 0) firstVersion = version;
@@ -615,9 +657,10 @@ export function matchCapability(match: ProbeMatch | undefined, releases: readonl
 export function newestPublishedVersion(pkg: string | undefined, releases: readonly GithubRelease[]): string | undefined {
   if (!pkg) return undefined;
   let newest: string | undefined;
+  const singlePackage = repoIsSinglePackage(releases);
   for (const rel of releases) {
     if (!rel || typeof rel.tag !== "string") continue;
-    const version = versionForPackage(rel.tag, pkg);
+    const version = versionForPackage(rel.tag, pkg, singlePackage);
     if (!version) continue;
     if (newest === undefined || cmpVersion(version, newest) > 0) newest = version;
   }