@nanobpm/nano-workforce 0.183.1 → 0.184.0

package/app/agentic/cockpit/supply-boot-agent-history.test.ts

@@ -0,0 +1,144 @@
+// Unit tests for the SUPPLY cockpit boot layer's engine-native AGENT-HISTORY panel (issue #745/#747).
+//
+// The testable heart of the consumer half: the cockpit renders a settled agent-history list (sourced
+// from engine searchAgentInstances) beside the live supply + relay past-sessions panels; selecting a
+// run renders its ordered conversation turns + metrics (sourced from engine searchAgentInstanceHistory)
+// keyed by agentInstanceKey — never a relay stream id. No browser, no engine, no socket.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { FakeDocument, FakeElement, FakeSocket } from "../../../test/agentic-cockpit-doubles.ts";
+import type {
+  AgentHistory as AgentHistoryReport,
+  AgentInstanceList as AgentInstanceListReport,
+} from "../../../nano-generated/api-io.d.ts";
+import { bootSupplyCockpit, type SupplyCockpitEnv } from "./supply-boot.ts";
+import type { SupplyReport } from "./supply-view.ts";
+
+const flush = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+const supply: SupplyReport = { count: 0, workers: [], leaves: [] };
+
+const instances: AgentInstanceListReport = {
+  count: 2,
+  instances: [
+    { agentInstanceKey: "ai-old", status: "COMPLETED", processInstanceKey: "pi-1", elementId: "implement-task", completionDate: "2024-01-01T00:00:00Z", metrics: { inputTokens: 100, outputTokens: 20, modelCalls: 2, toolCalls: 1 } },
+    { agentInstanceKey: "ai-new", status: "IDLE", processInstanceKey: "pi-2", lastUpdatedDate: "2024-02-01T00:00:00Z" },
+  ],
+};
+
+const history: AgentHistoryReport = {
+  agentInstanceKey: "ai-old",
+  count: 1,
+  instance: instances.instances[0],
+  records: [
+    { historyItemKey: "h-0", agentInstanceKey: "ai-old", loopIteration: 0, role: "ASSISTANT", commitStatus: "COMMITTED", content: [{ contentType: "TEXT", text: "did the thing" }], toolCalls: [] },
+  ],
+};
+
+interface Rig {
+  readonly env: SupplyCockpitEnv;
+  readonly host: FakeElement;
+  requestedHistoryKey: string | undefined;
+  errors: unknown[];
+}
+
+function rig(withAgentHistory = true): Rig {
+  const host = new FakeElement("body");
+  const state: Rig = {
+    host,
+    requestedHistoryKey: undefined,
+    errors: [],
+    env: {
+      host,
+      doc: new FakeDocument(),
+      fetchSupply: () => Promise.resolve(supply),
+      ...(withAgentHistory
+        ? {
+            fetchAgentInstances: () => Promise.resolve(instances),
+            fetchAgentHistory: (agentInstanceKey: string) => {
+              state.requestedHistoryKey = agentInstanceKey;
+              return Promise.resolve(history);
+            },
+          }
+        : {}),
+      connectRelay: () => new FakeSocket(),
+      createTerminal: (terminalHost) => {
+        terminalHost.appendChild(new FakeElement("pre"));
+        return { write: () => {}, dispose: () => {} };
+      },
+      setTimer: () => 0,
+      clearTimer: () => {},
+      onError: (err) => state.errors.push(err),
+    },
+  };
+  return state;
+}
+
+test("refresh renders the engine agent-history list, sorted newest-first", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  await flush();
+  const rows = r.host.byClass("cockpit-agent-session");
+  assert.equal(rows.length, 2, "one row per engine agent instance");
+  assert.equal(rows[0]?.getAttribute("data-agent-instance-key"), "ai-new", "newest-updated run first");
+  assert.equal(r.host.byData("summary", "agent-history").length, 1);
+  assert.deepEqual(r.errors, []);
+});
+
+test("selecting a run renders its engine history keyed by agentInstanceKey", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  await flush();
+
+  await cockpit.viewAgentHistory("ai-old");
+  await flush();
+  assert.equal(r.requestedHistoryKey, "ai-old", "history fetched by agent-instance key, not a stream id");
+  assert.equal(cockpit.currentAgentInstanceKey, "ai-old");
+  const transcript = r.host.byClass("cockpit-agent-transcript")[0];
+  assert.equal(transcript?.getAttribute("data-agent-instance-key"), "ai-old");
+  assert.equal(r.host.byClass("cockpit-agent-turn-text")[0]?.text(), "did the thing");
+  assert.deepEqual(r.errors, []);
+});
+
+test("clicking a run button drives viewAgentHistory", async () => {
+  const r = rig();
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  await flush();
+  const button = r.host.byClass("cockpit-agent-select").find((b) => b.getAttribute("data-agent-instance-key") === "ai-old");
+  button?.dispatch("click");
+  await flush();
+  assert.equal(cockpit.currentAgentInstanceKey, "ai-old");
+});
+
+test("the embedded shell renders the terminal directly beneath the supply list, matching mount.js", async () => {
+  const r = rig();
+  bootSupplyCockpit(r.env);
+  const shell = r.host.byClass("cockpit-shell")[0];
+  const order = (shell?.children ?? []).map((c) => c.className);
+  assert.deepEqual(order, [
+    "cockpit-supply-region",
+    "cockpit-terminal",
+    "cockpit-agent-region",
+    "cockpit-agent-detail-region",
+  ]);
+});
+
+test("no agent-history panel is rendered when the engine read endpoints are unwired", async () => {
+  const r = rig(false);
+  const cockpit = bootSupplyCockpit(r.env);
+  await cockpit.refresh();
+  await flush();
+  assert.equal(r.host.byClass("cockpit-agent-region").length, 0);
+  assert.equal(cockpit.currentAgentInstanceKey, undefined);
+});
+
+test("fetchAgentInstances without fetchAgentHistory fails loudly (matched-pair guard)", () => {
+  const r = rig(false);
+  assert.throws(
+    () => bootSupplyCockpit({ ...r.env, fetchAgentInstances: () => Promise.resolve(instances) }),
+    /fetchAgentInstances and fetchAgentHistory must be provided together/,
+  );
+});

package/app/agentic/cockpit/supply-boot.ts

@@ -28,6 +28,13 @@ import {
   TerminalSession,
   type TerminalSink,
 } from "@nanobpm/agentic/cockpit";
+import { renderAgentHistory, renderAgentSessions } from "./agent-history-render.ts";
+import {
+  type AgentHistoryReport,
+  type AgentInstanceListReport,
+  agentHistoryView,
+  agentSessionsView,
+} from "./agent-history-view.ts";
 import type { CockpitRoute } from "./cockpit-route.ts";
 import { renderSupply } from "./supply-render.ts";
 import type { SupplyReport, SupplyView } from "./supply-view.ts";
@@ -69,6 +76,23 @@ export interface SupplyCockpitEnv {
    * Required for the "past sessions" replay to work; must be provided together with {@link fetchTranscripts}.
    */
   readonly fetchTranscript?: (stream: string, from?: number) => Promise<TranscriptDataReport>;
+  /**
+   * Fetches the engine-native AgentInstance list (`GET /agentic/agent-instances`, served from
+   * `@nanobpm/urban`'s EngineClient `searchAgentInstances`) for the SETTLED "agent history" panel
+   * (issue #745/#747). Optional: when omitted the agent-history panel is not rendered. Must be
+   * provided together with {@link fetchAgentHistory}. This is the CONSUMER read path — settled history
+   * derives from engine truth keyed by agent-instance / process keys, NOT the slash-bearing relay
+   * stream id (so the #744 gateway-proxy bug class is moot); the relay past-sessions panel above stays
+   * the LIVE overlay only.
+   */
+  readonly fetchAgentInstances?: (processInstanceKey?: string) => Promise<AgentInstanceListReport>;
+  /**
+   * Fetches one AgentInstance's durable conversation history (turns + per-turn metrics) from engine
+   * `searchAgentInstanceHistory` (`GET /agentic/agent-instances/{agentInstanceKey}/history`), for the
+   * historical transcript view. Required for the agent-history panel's drill-in to work; must be
+   * provided together with {@link fetchAgentInstances}.
+   */
+  readonly fetchAgentHistory?: (agentInstanceKey: string) => Promise<AgentHistoryReport>;
   /** Opens a socket to the app relay channel (one per drill-in connection). */
   readonly connectRelay: SocketFactory;
   /** Mounts the terminal widget (xterm.js in the browser) and returns its write sink. */
@@ -117,6 +141,8 @@ export interface SupplyCockpitHandle {
   drill(stream: string): void;
   /** Replay a captured past session's stored transcript statically into the terminal (no live worker). */
   replay(stream: string): Promise<void>;
+  /** View one engine-native agent instance's settled conversation history in the agent-history panel. */
+  viewAgentHistory(agentInstanceKey: string): Promise<void>;
   /** Open a worker's dedicated detail page. */
   openWorker(instance: string): void;
   /** Return to the main worker list. */
@@ -125,6 +151,8 @@ export interface SupplyCockpitHandle {
   readonly currentRoute: CockpitRoute;
   /** The stream currently drilled into or replayed, if any. */
   readonly currentStream: string | undefined;
+  /** The agent instance whose settled history is currently shown in the agent-history panel, if any. */
+  readonly currentAgentInstanceKey: string | undefined;
   /** Whether the terminal is showing a LIVE stream or a REPLAYED transcript (undefined when idle). */
   readonly currentMode: TerminalMode | undefined;
   /** Stop everything and release the terminal connection. */
@@ -147,6 +175,11 @@ class SupplyCockpit implements SupplyCockpitHandle {
   readonly #env: SupplyCockpitEnv;
   readonly #listRegion: ElementLike;
   readonly #pastRegion: ElementLike | undefined;
+  // The engine-native SETTLED agent-history panel (issue #745): a list region (the AgentInstance runs)
+  // and a detail region (a selected instance's ordered conversation turns + metrics). Present only when
+  // the engine agent-history read endpoints are wired. Distinct from #pastRegion (the relay live overlay).
+  readonly #agentRegion: ElementLike | undefined;
+  readonly #agentDetailRegion: ElementLike | undefined;
   // A dedicated volatile region the STRUCTURED derived view (messages, rich tool/diff cards, permission
   // prompts) is mounted into on a replay — beside, and additive to, the byte-level terminal replay
   // (which is left untouched). Present only when the transcript read endpoints are wired.
@@ -182,6 +215,12 @@ class SupplyCockpit implements SupplyCockpitHandle {
   // hung transcripts endpoint can't accumulate pending calls.
   #pastRefreshing = false;
   #pastRefreshPending = false;
+  // Single-flight latch for the agent-history list refresh (mirrors #pastRefreshing), so the poll can
+  // never stack engine agent-instance fetches against a slow/unresponsive read endpoint.
+  #agentRefreshing = false;
+  #agentRefreshPending = false;
+  // The agent instance whose settled history is currently rendered in the detail region, if any.
+  #shownAgentInstanceKey: string | undefined;
   #route: CockpitRoute = { kind: "main" };
   #view: SupplyView | undefined;
   // Bumped by every start()/stop() so an in-flight #tick() from a previous start cycle can't
@@ -217,6 +256,12 @@ class SupplyCockpit implements SupplyCockpitHandle {
     if ((env.fetchTranscripts === undefined) !== (env.fetchTranscript === undefined)) {
       throw new Error("SupplyCockpitEnv.fetchTranscripts and fetchTranscript must be provided together (or neither)");
     }
+    // The engine agent-history LIST source and the per-instance HISTORY source are likewise a matched
+    // pair: the panel renders whenever the list source is present, but its rows route through
+    // viewAgentHistory(), which no-ops without the history source. Require both together (or neither).
+    if ((env.fetchAgentInstances === undefined) !== (env.fetchAgentHistory === undefined)) {
+      throw new Error("SupplyCockpitEnv.fetchAgentInstances and fetchAgentHistory must be provided together (or neither)");
+    }
     this.#setTimer =
       env.setTimer ??
       ((run, ms) => {
@@ -255,6 +300,14 @@ class SupplyCockpit implements SupplyCockpitHandle {
       this.#pastRegion = env.doc.createElement("div");
       this.#pastRegion.className = "cockpit-past-region";
     }
+    // The engine-native agent-history panel: a list region + a detail region, present only when the
+    // engine agent-history read endpoints are wired.
+    if (env.fetchAgentInstances !== undefined) {
+      this.#agentRegion = env.doc.createElement("div");
+      this.#agentRegion.className = "cockpit-agent-region";
+      this.#agentDetailRegion = env.doc.createElement("div");
+      this.#agentDetailRegion.className = "cockpit-agent-detail-region";
+    }
     this.#terminalPanel = env.doc.createElement("section");
     this.#terminalPanel.className = "cockpit-terminal";
     this.#terminalPanel.setAttribute("data-terminal-mode", "idle");
@@ -282,9 +335,14 @@ class SupplyCockpit implements SupplyCockpitHandle {
     this.#terminalNote.className = "cockpit-terminal-note";
     this.#terminalNote.setAttribute("data-terminal-note", "none");
     this.#terminalPanel.appendChild(this.#terminalNote);
+    // Order MUST match the browser twin (pages/cockpit/mount.js) and its tests: the terminal sits
+    // directly beneath the supply list, since cockpit.css keys layout off DOM order (no grid areas).
+    // supply list → terminal → past sessions → agent list → agent detail.
     shell.appendChild(this.#listRegion);
-    if (this.#pastRegion !== undefined) shell.appendChild(this.#pastRegion);
     shell.appendChild(this.#terminalPanel);
+    if (this.#pastRegion !== undefined) shell.appendChild(this.#pastRegion);
+    if (this.#agentRegion !== undefined) shell.appendChild(this.#agentRegion);
+    if (this.#agentDetailRegion !== undefined) shell.appendChild(this.#agentDetailRegion);
     env.host.appendChild(shell);
   }
 
@@ -292,6 +350,10 @@ class SupplyCockpit implements SupplyCockpitHandle {
     return this.#shownStream;
   }
 
+  get currentAgentInstanceKey(): string | undefined {
+    return this.#shownAgentInstanceKey;
+  }
+
   get currentMode(): TerminalMode | undefined {
     return this.#mode;
   }
@@ -350,6 +412,10 @@ class SupplyCockpit implements SupplyCockpitHandle {
     // transcripts endpoint that hangs (not just rejects) would otherwise stall #refresh() forever and
     // wedge the live worker list. #refreshPast is single-flight, so a slow fetch can't pile up either.
     void this.#refreshPast(this.#route.kind === "worker" ? this.#route.instance : undefined);
+    // Same fire-and-forget discipline for the engine agent-history list: a slow/hung read endpoint must
+    // never gate the supply poll's next tick. #refreshAgentHistory is single-flight + bounded. The list
+    // is engine-global (not route-filtered), so it takes no route instance — call it with no argument.
+    void this.#refreshAgentHistory();
   }
 
   #renderRoute(): void {
@@ -413,6 +479,73 @@ class SupplyCockpit implements SupplyCockpitHandle {
     }
   }
 
+  /** Fetch + render the engine-native SETTLED agent-history list, when the read endpoints are wired.
+   * Single-flight + bounded (mirrors {@link #refreshPast}): an engine read fault/hang never blocks the
+   * live worker list. The list is engine-global (settled AgentInstances), so it is not route-filtered. */
+  async #refreshAgentHistory(): Promise<void> {
+    const fetchAgentInstances = this.#env.fetchAgentInstances;
+    if (fetchAgentInstances === undefined || this.#agentRegion === undefined) return;
+    if (this.#agentRefreshing) {
+      this.#agentRefreshPending = true;
+      return;
+    }
+    this.#agentRefreshing = true;
+    try {
+      let report: AgentInstanceListReport;
+      try {
+        report = await this.#bounded(() => fetchAgentInstances(), "agent-instances");
+      } catch (err) {
+        if (this.#disposed) return;
+        this.#env.onError?.(err);
+        return;
+      }
+      if (this.#disposed || this.#agentRegion === undefined) return;
+      try {
+        renderAgentSessions(this.#agentRegion, this.#env.doc, agentSessionsView(report), {
+          onSelect: (agentInstanceKey) => void this.viewAgentHistory(agentInstanceKey),
+          ...(this.#shownAgentInstanceKey !== undefined ? { activeInstanceKey: this.#shownAgentInstanceKey } : {}),
+        });
+      } catch (err) {
+        this.#env.onError?.(err);
+      }
+    } finally {
+      this.#agentRefreshing = false;
+      if (this.#agentRefreshPending && !this.#disposed) {
+        this.#agentRefreshPending = false;
+        void this.#refreshAgentHistory();
+      }
+    }
+  }
+
+  /**
+   * Fetch + render one engine-native agent instance's SETTLED conversation history (turns + per-turn /
+   * instance metrics) into the detail region, keyed by `agentInstanceKey` — the CONSUMER read path
+   * (issue #745/#747). Bounded so a hung engine read can't wedge the panel. Read-as-absence: an unknown
+   * key renders an explicit empty history, never an error.
+   */
+  async viewAgentHistory(agentInstanceKey: string): Promise<void> {
+    if (this.#disposed) return;
+    const fetchAgentHistory = this.#env.fetchAgentHistory;
+    if (fetchAgentHistory === undefined || this.#agentDetailRegion === undefined) return;
+    let report: AgentHistoryReport;
+    try {
+      report = await this.#bounded(() => fetchAgentHistory(agentInstanceKey), "agent-history");
+    } catch (err) {
+      if (this.#disposed) return;
+      this.#env.onError?.(err);
+      return;
+    }
+    if (this.#disposed || this.#agentDetailRegion === undefined) return;
+    try {
+      this.#shownAgentInstanceKey = agentInstanceKey;
+      renderAgentHistory(this.#agentDetailRegion, this.#env.doc, agentHistoryView(report));
+      // Re-render the list so the just-selected run shows as active (best-effort).
+      void this.#refreshAgentHistory();
+    } catch (err) {
+      this.#env.onError?.(err);
+    }
+  }
+
   /**
    * Race an injected fetch against a timeout so the returned promise ALWAYS settles, even if the fetch
    * HANGS (never settles, not merely rejects). Both single-flight callers below — the past-sessions list

package/app/agentic/cockpit/supply-view.ts

@@ -53,7 +53,7 @@ export interface SupplyLeafReport {
 export interface SupplyCorrelationReport {
   /** The Camunda-8 job key. */
   readonly jobKey: string;
-  /** The relay stream the job's terminal is on (`job:<jobKey>`). */
+  /** The relay stream the job's terminal is on (`composeStreamId(instance, jobKey)`, issue #738). */
   readonly stream: string;
   /** The owning process instance key, if known. */
   readonly processInstanceKey?: string;
@@ -113,8 +113,8 @@ export interface SupplyWorkerView {
   readonly jobs: number;
   /**
    * Whether this worker has a LIVE terminal to drill into. True only while it holds a current job:
-   * a worker relays its terminal on the jobKey-scoped `job:<jobKey>` stream, and the supply endpoint
-   * repoints {@link stream} at it. An IDLE worker (no jobs) has its `stream` default back to the bare
+   * a worker relays its terminal on the instance-scoped `composeStreamId(instance, jobKey)` stream
+   * (issue #738), and the supply endpoint repoints {@link stream} at it. An IDLE worker (no jobs) has its `stream` default back to the bare
    * instance id — a stream NO producer ever writes to — so drilling it opens a permanently blank
    * "live" terminal. The renderer suppresses the drill affordance when this is false.
    */

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

@@ -41,7 +41,7 @@ export interface TranscriptListReport {
 
 /** One past-session row in the renderable history view. */
 export interface TranscriptView {
-  /** The relay stream id to replay (`job:<jobKey>` for a job stream). */
+  /** The relay stream id to replay (`composeStreamId(instance, jobKey)` for a job stream, issue #738). */
   readonly stream: string;
   /** A single stable human label for the session's process instance / plan (falls back to the stream). */
   readonly label: string;

package/app/agentic/correlation-store.test.ts

@@ -10,9 +10,13 @@ import { test } from "node:test";
 import { fileURLToPath } from "node:url";
 import type { SqliteDb } from "@nanobpm/agentic/transcript";
 import { assert, assertEquals } from "#test-assert";
-import { jobStream } from "./correlation.ts";
+import { composeStreamId } from "@nanobpm/agentic/emit";
 import { AGENTIC_CORRELATION_SCHEMA_SQL, AgenticCorrelationStore } from "./correlation-store.ts";
 
+/** The instance-scoped transcript stream id a job's terminal is stored under (issue #738). The
+ *  worker instance is fixed here — `byStream` only recovers the jobKey (the stream part) from it. */
+const st = (jobKey: string): string => composeStreamId("worker-A", jobKey);
+
 const HERE = dirname(fileURLToPath(import.meta.url));
 
 function memoryDb(): SqliteDb {
@@ -85,7 +89,7 @@ test("record + get round-trips full attribution, and byStream decodes the jobKey
   const store = new AgenticCorrelationStore(memoryDb());
   store.record({
     jobKey: "job-1",
-    stream: jobStream("job-1"),
+    stream: st("job-1"),
     instance: "worker-A",
     identity: "leaf:token",
     host: "merlin.local",
@@ -105,7 +109,7 @@ test("record + get round-trips full attribution, and byStream decodes the jobKey
   assertEquals(got?.planKey, "owner/repo#142");
   assertEquals(got?.completedAt, "2026-08-23T00:05:00.000Z");
   // The same row is reachable from the stream id.
-  assertEquals(store.byStream(jobStream("job-1"))?.instance, "worker-A");
+  assertEquals(store.byStream(st("job-1"))?.instance, "worker-A");
 });
 
 test("byElementInstance keys per-occupancy, distinguishing a looping/retried activity's iterations", () => {
@@ -115,7 +119,7 @@ test("byElementInstance keys per-occupancy, distinguishing a looping/retried act
   // element-instance key each resolves to its own attribution (the whole point of #544).
   store.record({
     jobKey: "job-iter-1",
-    stream: jobStream("job-iter-1"),
+    stream: st("job-iter-1"),
     instance: "worker-A",
     processInstanceKey: "pi-9",
     elementId: "agent",
@@ -124,7 +128,7 @@ test("byElementInstance keys per-occupancy, distinguishing a looping/retried act
   });
   store.record({
     jobKey: "job-iter-2",
-    stream: jobStream("job-iter-2"),
+    stream: st("job-iter-2"),
     instance: "worker-A",
     processInstanceKey: "pi-9",
     elementId: "agent",
@@ -147,7 +151,7 @@ test("optional context columns are omitted (not null) when unknown", () => {
   const store = new AgenticCorrelationStore(memoryDb());
   store.record({
     jobKey: "job-2",
-    stream: jobStream("job-2"),
+    stream: st("job-2"),
     instance: "worker-B",
     completedAt: "2026-08-23T01:00:00.000Z",
   });
@@ -159,7 +163,7 @@ test("optional context columns are omitted (not null) when unknown", () => {
 
 test("record is an upsert: re-recording a jobKey is last-write-wins", () => {
   const store = new AgenticCorrelationStore(memoryDb());
-  const base = { jobKey: "job-3", stream: jobStream("job-3"), completedAt: "2026-08-23T02:00:00.000Z" };
+  const base = { jobKey: "job-3", stream: st("job-3"), completedAt: "2026-08-23T02:00:00.000Z" };
   store.record({ ...base, instance: "worker-C" });
   store.record({ ...base, instance: "worker-C", host: "second.local", completedAt: "2026-08-23T02:10:00.000Z" });
   const got = store.get("job-3");
@@ -169,7 +173,7 @@ test("record is an upsert: re-recording a jobKey is last-write-wins", () => {
 
 test("record preserves an existing element_instance_key when a later re-record omits it (monotonic)", () => {
   const store = new AgenticCorrelationStore(memoryDb());
-  const base = { jobKey: "job-4", stream: jobStream("job-4"), completedAt: "2026-08-23T02:00:00.000Z" };
+  const base = { jobKey: "job-4", stream: st("job-4"), completedAt: "2026-08-23T02:00:00.000Z" };
   // The durable backfill path (or a first record that carried the resolved key).
   store.record({ ...base, instance: "worker-D", elementInstanceKey: "ei-777" });
   // A later best-effort re-record that does NOT know the key must not wipe it back to NULL.
@@ -178,9 +182,9 @@ test("record preserves an existing element_instance_key when a later re-record o
   assertEquals(got?.host, "later.local");
   assertEquals(got?.elementInstanceKey, "ei-777");
   // setElementInstanceKey backfill then a bare re-record likewise survives.
-  store.record({ jobKey: "job-5", stream: jobStream("job-5"), completedAt: "2026-08-23T03:00:00.000Z", instance: "worker-E" });
+  store.record({ jobKey: "job-5", stream: st("job-5"), completedAt: "2026-08-23T03:00:00.000Z", instance: "worker-E" });
   store.setElementInstanceKey("job-5", "ei-888");
-  store.record({ jobKey: "job-5", stream: jobStream("job-5"), completedAt: "2026-08-23T03:05:00.000Z", instance: "worker-E" });
+  store.record({ jobKey: "job-5", stream: st("job-5"), completedAt: "2026-08-23T03:05:00.000Z", instance: "worker-E" });
   assertEquals(store.get("job-5")?.elementInstanceKey, "ei-888");
 });
 

package/app/agentic/correlation-store.ts

@@ -19,8 +19,9 @@
 // `element_instance_key`). A drift-guard test (`correlation-store.test.ts`) applies those migrations to
 // one DB and the canonical DDL to another and asserts the two schemas are identical, so they can never
 // diverge (the migrations, once merged, are immutable — the canonical DDL is what evolves).
+
+import { parseStreamId } from "@nanobpm/agentic/emit";
 import type { SqliteDb } from "@nanobpm/agentic/transcript";
-import { jobKeyOfStream } from "./correlation.ts";
 
 /**
  * The canonical DDL for the durable correlation table. The `078_*` + `086_*` migrations reproduce this
@@ -183,9 +184,9 @@ export class AgenticCorrelationStore {
     return rows.length > 0 ? fromRow(rows[0]) : undefined;
   }
 
-  /** The durable attribution for a `job:<jobKey>` stream id, or undefined for a non-job stream. */
+  /** The durable attribution for an instance-scoped job stream id, or undefined for a non-job stream. */
   byStream(stream: string): DurableCorrelation | undefined {
-    const jobKey = jobKeyOfStream(stream);
+    const jobKey = parseStreamId(stream)?.stream;
     return jobKey === undefined ? undefined : this.get(jobKey);
   }
 

package/app/agentic/correlation.test.ts

@@ -1,32 +1,36 @@
 // Unit tests for the jobKey ⇄ process/plan correlation registry (ADR 0056, H6 / #149).
 //
 // The registry is the single canonical join the cockpit uses to line a worker's terminal up with the
-// process instance / plan it belongs to. These tests pin: the `job:<jobKey>` stream convention; the
-// two derived-from-one-write projections (instance→jobKeys and jobKey→context) staying consistent
-// across link / re-link (move) / releaseJob / releaseInstance; the presence `jobKeysFor` seam; the
-// drill `primaryStreamFor`; and the sorted snapshot.
+// process instance / plan it belongs to. These tests pin: the instance-scoped `composeStreamId`
+// transcript-stream convention (issue #738); the two derived-from-one-write projections
+// (instance→jobKeys and jobKey→context) staying consistent across link / re-link (move) / releaseJob /
+// releaseInstance; the presence `jobKeysFor` seam; the drill `primaryStreamFor`; and the sorted snapshot.
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
+import { composeStreamId, parseStreamId } from "@nanobpm/agentic/emit";
 import {
   CorrelationRegistry,
   currentCorrelation,
   JOB_STREAM_PREFIX,
-  jobKeyOfStream,
   jobStream,
   setCurrentCorrelation,
 } from "./correlation.ts";
 
-test("jobStream / jobKeyOfStream are inverse over the job: convention", () => {
+test("jobStream builds the bare, slash-free job: id retained for the aux (Explorer/permission) surfaces", () => {
   assert.equal(jobStream("6494"), `${JOB_STREAM_PREFIX}6494`);
-  assert.equal(jobKeyOfStream(jobStream("6494")), "6494");
-  assert.equal(jobKeyOfStream("wk-a"), undefined);
-  // A bare `job:` prefix carries no jobKey, so it maps to undefined (not "") — an empty jobKey is
-  // invalid (link() ignores it), so callers never mistake it for a valid key.
-  assert.equal(jobKeyOfStream("job:"), undefined);
+  assert.equal(JOB_STREAM_PREFIX, "job:");
 });
 
-test("link records context and both projections; resolve carries the job: stream", () => {
+test("the transcript stream is the instance-scoped composeStreamId id, round-tripped by parseStreamId (#738)", () => {
+  const stream = composeStreamId("wk-a", "6494");
+  const ref = parseStreamId(stream);
+  assert.ok(ref);
+  assert.equal(ref.instance, "wk-a");
+  assert.equal(ref.stream, "6494");
+});
+
+test("link records context and both projections; resolve carries the instance-scoped stream", () => {
   const reg = new CorrelationRegistry();
   reg.link("wk-a", "6494", { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", planKey: "o/r#142" });
 
@@ -34,7 +38,7 @@ test("link records context and both projections; resolve carries the job: stream
   const c = reg.resolve("6494");
   assert.ok(c);
   assert.equal(c.jobKey, "6494");
-  assert.equal(c.stream, "job:6494");
+  assert.equal(c.stream, composeStreamId("wk-a", "6494"));
   assert.equal(c.processInstanceKey, "4612");
   assert.equal(c.bpmnProcessId, "plan-fanout");
   assert.equal(c.elementId, "implement-task");
@@ -54,7 +58,7 @@ test("attachElementInstance enriches a linked job's context, preserving every ot
   assert.equal(c.elementId, "agent");
   assert.equal(c.planKey, "o/r#142");
   assert.equal(c.jobKey, "6494");
-  assert.equal(c.stream, "job:6494");
+  assert.equal(c.stream, composeStreamId("wk-a", "6494"));
 });
 
 test("attachElementInstance is a no-op for a released (or never-linked) job or an empty key (#544)", () => {
@@ -145,7 +149,7 @@ test("primaryStreamFor picks the lowest-sorted job's stream; undefined when none
   assert.equal(reg.primaryStreamFor("wk-a"), undefined);
   reg.link("wk-a", "50");
   reg.link("wk-a", "10");
-  assert.equal(reg.primaryStreamFor("wk-a"), "job:10");
+  assert.equal(reg.primaryStreamFor("wk-a"), composeStreamId("wk-a", "10"));
 });
 
 test("snapshot returns every job sorted by jobKey", () => {
@@ -156,7 +160,11 @@ test("snapshot returns every job sorted by jobKey", () => {
   const snap = reg.snapshot();
   assert.equal(snap.count, 3);
   assert.deepEqual(snap.correlations.map((c) => c.jobKey), ["10", "20", "30"]);
-  assert.deepEqual(snap.correlations.map((c) => c.stream), ["job:10", "job:20", "job:30"]);
+  assert.deepEqual(snap.correlations.map((c) => c.stream), [
+    composeStreamId("wk-b", "10"),
+    composeStreamId("wk-c", "20"),
+    composeStreamId("wk-a", "30"),
+  ]);
 });
 
 test("link with no context leaves optional fields unset (no undefined holes)", () => {