@nanobpm/nano-workforce 0.183.1 → 0.184.0

package/app/agentic/families/relay.family.ts

@@ -21,6 +21,7 @@
 // is untouched — the agentic channel is the only new conversation; advisory semantics preserved (the
 // relay/transcript never hard-lock or gate a BPMN sequence flow).
 import type { ConnectionRegistry } from "@nanobpm/agentic/channel";
+import { parseStreamId } from "@nanobpm/agentic/emit";
 import type { Frame } from "@nanobpm/agentic/protocol";
 import { RELAY_FAMILY, RelayHub, type RelayHubOptions } from "@nanobpm/agentic/relay";
 import {
@@ -37,7 +38,7 @@ import {
   type TranscriptVocab,
 } from "@nanobpm/agentic/transcript";
 import type { Logger } from "@nanobpm/urban";
-import { currentCorrelation, type JobContext, type JobCorrelation, jobKeyOfStream } from "../correlation.ts";
+import { currentCorrelation, type JobContext, type JobCorrelation } from "../correlation.ts";
 import { AgenticCorrelationStore } from "../correlation-store.ts";
 import type { ElementInstanceResolver } from "../element-instance.ts";
 import type { AgenticContext, AgenticFamily } from "../registry.ts";
@@ -194,7 +195,7 @@ interface StreamState {
   /** Set once an ephemeral stream has been flushed & completed (so it is not re-completed). */
   completed: boolean;
   /**
-   * Set once a `job:<jobKey>` stream has been linked into the correlation registry (H6, #149), so
+   * Set once an instance-scoped job stream has been linked into the correlation registry (H6, #149), so
    * the link is attempted at most once per stream. It stays `false` while the producer's presence
    * instance is not yet resolvable (a register/produce race), so a later `produce` frame retries.
    */
@@ -208,14 +209,14 @@ interface StreamState {
    */
   createdAt: string;
   /**
-   * The worker instance a `job:<jobKey>` stream was linked under (H6). Recorded so a stream's release
+   * The worker instance an instance-scoped job stream was linked under (H6). Recorded so a stream's release
    * (completion / disconnect) can tidy the {@link RelayTranscriptService.#jobStreamByInstance}
    * supersede index, and so the "one job at a time per worker" supersede rule can identify the
    * instance's prior job stream.
    */
   instance?: string;
   /**
-   * The engine element-instance key this `job:<jobKey>` stream's job occupies (#544), once the
+   * The engine element-instance key this instance-scoped job stream's job occupies (#544), once the
    * asynchronous link-time resolution ({@link RelayTranscriptService.#resolveElementInstance}) lands.
    * Stashed on the stream so job completion can persist it even if the live correlation was already
    * enriched-and-released, and so a resolution that returns after completion can still be recognised.
@@ -275,7 +276,7 @@ export interface RelayTranscriptServiceOptions {
   readonly ensureSchema?: boolean;
   /**
    * The correlation write-side seam (H6, #149). When present, a first `produce` frame for a
-   * `job:<jobKey>` stream links the producing worker instance → jobKey here, and the stream's
+   * instance-scoped job stream links the producing worker instance → jobKey here, and the stream's
    * completion / producer disconnect releases it. Defaults to the process-wide correlation registry
    * ({@link currentCorrelation}); absent (`() => undefined`) → no linking (advisory, never an error).
    */
@@ -317,7 +318,7 @@ export interface RelayTranscriptServiceOptions {
    */
   readonly correlationStore?: AgenticCorrelationStore;
   /**
-   * Resolve the engine element-instance key a `job:<jobKey>` stream's job occupies (#544). Called
+   * Resolve the engine element-instance key an instance-scoped job stream's job occupies (#544). Called
    * fire-and-forget on the first `produce` (while the job's JOB park is still live), and its result
    * enriches the live correlation context / durable attribution so a captured session is keyed on the
    * element INSTANCE (unambiguous across a looping / retried job), not just the static element id.
@@ -357,7 +358,7 @@ export class RelayTranscriptService {
   readonly #log: Logger;
   readonly #streams = new Map<string, StreamState>();
   /**
-   * The `job:<jobKey>` relay stream each worker instance is CURRENTLY relaying (H6, #149). A worker
+   * The instance-scoped job relay stream each worker instance is CURRENTLY relaying (H6, #149). A worker
    * relays every job it runs over one long-lived channel connection, one job at a time
    * (`../correlation.ts`), so that connection never disconnects between jobs — the disconnect-driven
    * `#reconcile` release never fires. This index lets a NEW job's first `produce` supersede the
@@ -609,17 +610,18 @@ export class RelayTranscriptService {
   }
 
   /**
-   * H6 write-side (#149): on the first `produce` for a `job:<jobKey>` stream, link the producing
-   * worker instance → jobKey in the correlation registry, from data already crossing the wire (the
-   * jobKey is decoded from the stream id; the instance is resolved from the producing connection).
-   * That lights up the worker's `jobKeys` in the supply feed and repoints its drill stream at the
-   * jobKey-scoped relay stream. Idempotent per stream; retries on a later frame while the producer's
-   * presence instance is not yet resolvable (a register/produce race). Advisory — never throws into
-   * the frame handler.
+   * H6 write-side (#149): on the first `produce` for an instance-scoped job stream
+   * (`composeStreamId(instance, jobKey)`), link the producing worker instance → jobKey in the
+   * correlation registry, from data already crossing the wire (the jobKey is decoded from the stream
+   * id via `parseStreamId`; the instance is resolved from the producing connection). That lights up
+   * the worker's `jobKeys` in the supply feed and repoints its drill stream at the instance-scoped
+   * relay stream the producer actually writes under (issue #738). Idempotent per stream; retries on a
+   * later frame while the producer's presence instance is not yet resolvable (a register/produce
+   * race). Advisory — never throws into the frame handler.
    */
   #link(stream: string, connectionId: string, state: StreamState): void {
     if (state.linked) return;
-    const jobKey = jobKeyOfStream(stream);
+    const jobKey = parseStreamId(stream)?.stream;
     if (jobKey === undefined) return;
     const instance = this.#instanceForConnection(connectionId);
     if (instance === undefined || instance === "") return;
@@ -697,10 +699,11 @@ export class RelayTranscriptService {
       });
   }
 
-  /** H6 write-side (#149): release a `job:<jobKey>` stream's correlation on completion / disconnect. */
+  /** H6 write-side (#149): release an instance-scoped job stream's (`composeStreamId(instance, jobKey)`)
+   *  correlation on completion / disconnect. */
   #unlink(stream: string, state: StreamState): void {
     if (!state.linked) return;
-    const jobKey = jobKeyOfStream(stream);
+    const jobKey = parseStreamId(stream)?.stream;
     if (jobKey === undefined) return;
     try {
       // Persist the completed job's durable worker attribution + (best-effort) engine context BEFORE
@@ -791,7 +794,7 @@ export class RelayTranscriptService {
         // relay-connection layer (the old presence heuristic, #690) conflates two independent liveness
         // signals (engine lease vs. WS connection); the authoritative one is the engine job-state the
         // poller already reconciles (#691).
-        if (this.#resolveElementInstance !== undefined && jobKeyOfStream(stream) !== undefined) {
+        if (this.#resolveElementInstance !== undefined && parseStreamId(stream)?.stream !== undefined) {
           // Engine/poller-owned completion (#691): drop the dead producer so `#reconcile` does not
           // re-trigger on every subsequent frame, then reconcile THIS stream against the engine's view
           // of its job (fire-and-forget — the sync frame handler must not await an engine read). A
@@ -858,7 +861,7 @@ export class RelayTranscriptService {
     const streams: string[] = [];
     for (const [stream, state] of this.#streams) {
       if (state.completed) continue;
-      if (jobKeyOfStream(stream) === undefined) continue;
+      if (parseStreamId(stream)?.stream === undefined) continue;
       // Include UNLINKED job streams too (#708). The disconnect path (#691) routes an unlinked
       // job stream through the engine reconcile and clears `state.producer`, so if the engine
       // reports "still parked" at disconnect (or the read faults transiently) and the worker never
@@ -871,7 +874,7 @@ export class RelayTranscriptService {
   }
 
   /**
-   * Reconcile ONE `job:<jobKey>` stream against the engine's view of its job (the poller-owned
+   * Reconcile ONE instance-scoped job stream against the engine's view of its job (the poller-owned
    * completion authority, #691). Asks the engine read model (the {@link ElementInstanceResolver} the
    * #544 link path uses) whether the job is still parked: still parked → genuinely active, kept live;
    * gone → ended (a clean completion whose terminal lifecycle event was missed, or an unclean exit) →
@@ -895,7 +898,7 @@ export class RelayTranscriptService {
     if (resolve === undefined) return;
     const before = this.#streams.get(stream);
     if (before === undefined || before.completed) return;
-    const jobKey = jobKeyOfStream(stream);
+    const jobKey = parseStreamId(stream)?.stream;
     if (jobKey === undefined) return;
     const processInstanceKey = this.#correlation()?.resolve?.(jobKey)?.processInstanceKey;
     let activeKey: string | undefined;

package/app/agentic/transcript-read.test.ts

@@ -8,9 +8,16 @@ import { test } from "node:test";
 import { DatabaseSync } from "node:sqlite";
 import type { SqliteDb, TranscriptRing, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
 import { assert, assertEquals } from "#test-assert";
+import { composeStreamId } from "@nanobpm/agentic/emit";
 import { AgenticCorrelationStore } from "./correlation-store.ts";
-import { CorrelationRegistry } from "./correlation.ts";
-import { correlationFieldsFor, listTranscripts, readTranscriptFrom } from "./transcript-read.ts";
+import { CorrelationRegistry, jobStream } from "./correlation.ts";
+import type { RelayTranscriptService } from "./families/relay.family.ts";
+import { correlationFieldsFor, listTranscripts, readSingleTranscript, readTranscriptFrom } from "./transcript-read.ts";
+
+/** The instance-scoped transcript stream id a job's terminal is stored under (issue #738); the jobKey
+ *  is the stream part `parseStreamId` recovers. The worker instance is fixed here where it is immaterial
+ *  to the assertion (the durable filters key off the recorded row's instance, not the stream's). */
+const s = (jobKey: string): string => composeStreamId("w", jobKey);
 
 /** A read-only TranscriptStore double: list() returns the seeded metas; read() has no retained chunks. */
 function fakeStore(metas: TranscriptStream[]): TranscriptStore {
@@ -90,7 +97,7 @@ test("durable fallback: a released (past) job is attributed from the durable sto
   const durable = new AgenticCorrelationStore(memoryStore());
   durable.record({
     jobKey: "k1",
-    stream: "job:k1",
+    stream: s("k1"),
     instance: "worker-A",
     identity: "gpu-box-7",
     host: "us-east-1a",
@@ -99,7 +106,7 @@ test("durable fallback: a released (past) job is attributed from the durable sto
     completedAt: mid,
   });
 
-  const fields = correlationFieldsFor("job:k1", undefined, durable);
+  const fields = correlationFieldsFor(s("k1"), undefined, durable);
   assertEquals(fields.jobKey, "k1");
   assertEquals(fields.instance, "worker-A");
   assertEquals(fields.identity, "gpu-box-7");
@@ -111,16 +118,16 @@ test("durable fallback: a released (past) job is attributed from the durable sto
 test("#544: the durable element-instance key surfaces on the read projection and its filter", () => {
   const durable = new AgenticCorrelationStore(memoryStore());
   // Two iterations of the SAME static element (`agent`) — distinct element instances, distinct jobKeys.
-  durable.record({ jobKey: "k1", stream: "job:k1", instance: "worker-A", elementId: "agent", elementInstanceKey: "ei-1", completedAt: early });
-  durable.record({ jobKey: "k2", stream: "job:k2", instance: "worker-A", elementId: "agent", elementInstanceKey: "ei-2", completedAt: late });
+  durable.record({ jobKey: "k1", stream: s("k1"), instance: "worker-A", elementId: "agent", elementInstanceKey: "ei-1", completedAt: early });
+  durable.record({ jobKey: "k2", stream: s("k2"), instance: "worker-A", elementId: "agent", elementInstanceKey: "ei-2", completedAt: late });
 
   // The key surfaces on the correlation fields (durable fallback, live registry empty).
-  assertEquals(correlationFieldsFor("job:k1", undefined, durable).elementInstanceKey, "ei-1");
+  assertEquals(correlationFieldsFor(s("k1"), undefined, durable).elementInstanceKey, "ei-1");
 
-  const store = fakeStore([meta("job:k1", early), meta("job:k2", late)]);
+  const store = fakeStore([meta(s("k1"), early), meta(s("k2"), late)]);
   // The elementInstanceKey filter resolves a session to ONE occupancy, where the elementId cannot.
   const out = listTranscripts(store, undefined, { elementInstanceKey: "ei-2" }, durable);
-  assertEquals(out.map((t) => t.stream), ["job:k2"], "only the ei-2 occupancy matches");
+  assertEquals(out.map((t) => t.stream), [s("k2")], "only the ei-2 occupancy matches");
   assertEquals(out[0].elementInstanceKey, "ei-2", "the projection carries the element-instance key");
 });
 
@@ -129,22 +136,22 @@ test("#544: the live correlation's element-instance key takes precedence over th
   registry.link("worker-A", "k1", { elementId: "agent" });
   registry.attachElementInstance("k1", "ei-live");
   const durable = new AgenticCorrelationStore(memoryStore());
-  durable.record({ jobKey: "k1", stream: "job:k1", instance: "worker-A", elementInstanceKey: "ei-old", completedAt: mid });
+  durable.record({ jobKey: "k1", stream: s("k1"), instance: "worker-A", elementInstanceKey: "ei-old", completedAt: mid });
 
-  assertEquals(correlationFieldsFor("job:k1", registry, durable).elementInstanceKey, "ei-live");
+  assertEquals(correlationFieldsFor(s("k1"), registry, durable).elementInstanceKey, "ei-live");
 });
 
 test("listTranscripts: the instance filter returns only sessions the durable store attributes to that worker", () => {
-  const store = fakeStore([meta("job:k1", early), meta("job:k2", mid), meta("job:k3", late)]);
+  const store = fakeStore([meta(s("k1"), early), meta(s("k2"), mid), meta(s("k3"), late)]);
   const durable = new AgenticCorrelationStore(memoryStore());
-  durable.record({ jobKey: "k1", stream: "job:k1", instance: "worker-A", completedAt: early });
-  durable.record({ jobKey: "k2", stream: "job:k2", instance: "worker-B", completedAt: mid });
-  durable.record({ jobKey: "k3", stream: "job:k3", instance: "worker-A", completedAt: late });
+  durable.record({ jobKey: "k1", stream: s("k1"), instance: "worker-A", completedAt: early });
+  durable.record({ jobKey: "k2", stream: s("k2"), instance: "worker-B", completedAt: mid });
+  durable.record({ jobKey: "k3", stream: s("k3"), instance: "worker-A", completedAt: late });
 
   const out = listTranscripts(store, undefined, { instance: "worker-A" }, durable);
   assertEquals(
     out.map((t) => t.stream),
-    ["job:k3", "job:k1"],
+    [s("k3"), s("k1")],
     "only worker-A's sessions, newest-first",
   );
   assert(out.every((t) => t.instance === "worker-A"), "each row is attributed to worker-A");
@@ -183,7 +190,7 @@ test("readTranscriptFrom: falls back to the live ring when the durable store has
     { offset: 0, chunk: "hello " },
     { offset: 1, chunk: "world" },
   ]);
-  const out = readTranscriptFrom("job:live1", 0, getStore(undefined), undefined, undefined, {
+  const out = readTranscriptFrom(s("live1"), 0, getStore(undefined), undefined, undefined, {
     ring,
     createdAt: mid,
   });
@@ -242,3 +249,87 @@ test("readTranscriptFrom: returns undefined when neither the store nor a live ri
   const out = readTranscriptFrom("job:gone", 0, getStore(undefined), undefined, undefined, undefined);
   assertEquals(out, undefined);
 });
+
+// --- #738: the Stage-0 `job:<jobKey>` transcript URL still resolves after the data-plane moved to the
+//     instance-scoped `composeStreamId(instance, jobKey)` stream ---
+//
+// The Explorer Stage-0 `transcriptUrl` (app/agentic/transcript-url.ts, #543) addresses a job by the bare
+// `job:<jobKey>` alias — the worker cannot know its own instance at output-mapping time. The transcript is
+// now STORED under the instance-scoped id, so a Stage-0 read must map the alias back to that id (via the
+// live registry while linked, else the durable store) or it would 404 the URL it just emitted.
+
+/** A keyed TranscriptStore double: `get`/`since` resolve only for the exact stream id seeded (unlike
+ *  {@link getStore}, which returns its row for ANY id) — so a test can prove the alias was RESOLVED. */
+function keyedStore(rows: Record<string, { meta: TranscriptStream; entries: { offset: number; chunk: string }[] }>): TranscriptStore {
+  return {
+    get: (stream: string) => rows[stream]?.meta,
+    since: (stream: string, from: number) => ({
+      entries: (rows[stream]?.entries ?? []).filter((e) => e.offset >= from),
+      gap: false,
+      nextOffset: rows[stream]?.meta.nextOffset ?? 0,
+    }),
+    list: () => Object.values(rows).map((r) => r.meta),
+    read: () => [],
+  } as unknown as TranscriptStore;
+}
+
+/** A RelayTranscriptService double exposing only the surface {@link readSingleTranscript} reads. */
+function fakeService(
+  store: TranscriptStore | undefined,
+  correlationStore: AgenticCorrelationStore | undefined,
+  rings: Record<string, { ring: TranscriptRing; createdAt: string }> = {},
+): RelayTranscriptService {
+  return {
+    store,
+    correlationStore,
+    liveFallback: (stream: string) => rings[stream],
+  } as unknown as RelayTranscriptService;
+}
+
+test("readSingleTranscript: a Stage-0 job:<jobKey> alias resolves to the instance-scoped stored stream via the durable store (#738)", () => {
+  const durable = new AgenticCorrelationStore(memoryStore());
+  durable.record({ jobKey: "j1", stream: s("j1"), instance: "w", planKey: "acme/repo#1", completedAt: mid });
+  const store = keyedStore({
+    [s("j1")]: {
+      meta: { stream: s("j1"), lifecycle: "ephemeral", status: "completed", createdAt: early, completedAt: late, nextOffset: 1 },
+      entries: [{ offset: 0, chunk: "durable-bytes" }],
+    },
+  });
+  const res = readSingleTranscript(jobStream("j1"), 0, fakeService(store, durable), undefined);
+  assertEquals(res.status, 200, "the alias resolves to the instance-scoped row, not a 404");
+  assert(res.status === 200);
+  assertEquals(res.body.stream, s("j1"), "served under the instance-scoped id the bytes are stored on");
+  assertEquals(res.body.entries.map((e) => e.chunk).join(""), "durable-bytes");
+  assertEquals(res.body.jobKey, "j1");
+  assertEquals(res.body.planKey, "acme/repo#1", "durable attribution still surfaces through the alias read");
+});
+
+test("readSingleTranscript: a Stage-0 job:<jobKey> alias resolves via the LIVE registry while the job is still linked (#738)", () => {
+  const registry = new CorrelationRegistry();
+  registry.link("w", "j2", { planKey: "acme/repo#2" });
+  const store = keyedStore({
+    [s("j2")]: {
+      meta: { stream: s("j2"), lifecycle: "ephemeral", status: "open", createdAt: mid, nextOffset: 1 },
+      entries: [{ offset: 0, chunk: "live-row" }],
+    },
+  });
+  const res = readSingleTranscript(jobStream("j2"), 0, fakeService(store, undefined), registry);
+  assertEquals(res.status, 200);
+  assert(res.status === 200);
+  assertEquals(res.body.entries.map((e) => e.chunk).join(""), "live-row");
+  assertEquals(res.body.planKey, "acme/repo#2");
+});
+
+test("readSingleTranscript: an unresolvable job:<jobKey> alias still 404s (no correlation anywhere)", () => {
+  const res = readSingleTranscript(jobStream("ghost"), 0, fakeService(keyedStore({}), undefined), undefined);
+  assertEquals(res.status, 404);
+});
+
+test("correlationFieldsFor: decodes the jobKey from a bare job:<jobKey> Stage-0 alias too (#738)", () => {
+  const durable = new AgenticCorrelationStore(memoryStore());
+  durable.record({ jobKey: "j3", stream: s("j3"), instance: "worker-Z", planKey: "acme/repo#3", completedAt: mid });
+  const fields = correlationFieldsFor(jobStream("j3"), undefined, durable);
+  assertEquals(fields.jobKey, "j3", "the alias decodes its jobKey rather than yielding an empty projection");
+  assertEquals(fields.instance, "worker-Z");
+  assertEquals(fields.planKey, "acme/repo#3");
+});

package/app/agentic/transcript-read.ts

@@ -9,14 +9,17 @@
 // Correlation is BEST-EFFORT and advisory: the correlation registry is in-memory and only holds
 // currently-linked jobs, so a completed session's process-instance / plan context is present only
 // while the job is still live. The jobKey itself is always recoverable — it is encoded in the stream
-// id (`job:<jobKey>`), so a past session is never anonymous even once its correlation has been released.
+// id (`composeStreamId(instance, jobKey)`, decoded with `parseStreamId`), so a past session is never
+// anonymous even once its correlation has been released.
 //
 // Pure and side-effect-free apart from reading the store: no I/O beyond the injected store, so it is
 // unit-testable on the injected env (Node, no browser), and never touches the engine or a BPMN flow.
 
+import { parseStreamId } from "@nanobpm/agentic/emit";
 import type { TranscriptChunk, TranscriptRing, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
 import type { AgenticTranscript, AgenticTranscriptData, ErrorBody } from "../../nano-generated/api-io.d.ts";
-import { type CorrelationRegistry, jobKeyOfStream } from "./correlation.ts";
+import type { CorrelationRegistry } from "./correlation.ts";
+import { jobKeyOfJobStream } from "./correlation.ts";
 import type { AgenticCorrelationStore } from "./correlation-store.ts";
 import type { RelayTranscriptService } from "./families/relay.family.ts";
 import { utf8ByteLength } from "./transcript-events.ts";
@@ -46,8 +49,10 @@ interface CorrelationFields {
 }
 
 /**
- * Resolve a stream id to its correlation fields. The jobKey is always decoded from a `job:<jobKey>`
- * stream id. Engine context (process instance / plan) + worker attribution (instance / identity /
+ * Resolve a stream id to its correlation fields. The jobKey is decoded from the instance-scoped
+ * stream id (`composeStreamId(instance, jobKey)`) via {@link parseStreamId}, falling back to the bare
+ * `job:<jobKey>` Stage-0 alias ({@link jobKeyOfJobStream}) so a session addressed by either scheme stays
+ * attributable. Engine context (process instance / plan) + worker attribution (instance / identity /
  * host) come from the LIVE registry while the job is still linked, and fall back to the DURABLE store
  * (`AgenticCorrelationStore`) once the job has completed and its live correlation was released — so a
  * PAST session stays attributable to its worker after the worker exits or the process restarts.
@@ -58,7 +63,7 @@ export function correlationFieldsFor(
   correlation: CorrelationRegistry | undefined,
   durable?: AgenticCorrelationStore | undefined,
 ): CorrelationFields {
-  const jobKey = jobKeyOfStream(stream);
+  const jobKey = parseStreamId(stream)?.stream ?? jobKeyOfJobStream(stream);
   if (jobKey === undefined) return {};
   const fields: CorrelationFields = { jobKey };
   const context = correlation?.resolve(jobKey);
@@ -251,6 +256,30 @@ export type SingleTranscriptResult =
   | { status: 400; body: ErrorBody }
   | { status: 404; body: ErrorBody };
 
+/**
+ * Resolve a requested stream id to the instance-scoped id the transcript is actually STORED under.
+ *
+ * The data plane keys every job transcript by `composeStreamId(instance, jobKey)` (issue #738), but the
+ * Explorer Stage-0 `transcriptUrl` (`app/agentic/transcript-url.ts`, #543) still addresses a job by the
+ * bare `job:<jobKey>` alias — the completing worker cannot know its own instance at output-mapping time.
+ * So a Stage-0 read arrives keyed by `job:<jobKey>` and would MISS the store (and 404) unless it is first
+ * mapped back to the instance-scoped id. The jobKey → instance-scoped stream is recovered from the LIVE
+ * correlation registry while the job is still linked, else from the DURABLE store (which persists the
+ * instance-scoped `stream` keyed by jobKey at completion). An already-instance-scoped id, a non-job
+ * stream, or an unknown jobKey is returned unchanged (the caller then reads it as-is, 404-ing if absent).
+ */
+export function canonicalStreamFor(
+  stream: string,
+  correlation: CorrelationRegistry | undefined,
+  durable: AgenticCorrelationStore | undefined,
+): string {
+  // Already instance-scoped (or a non-alias id) — nothing to resolve.
+  if (parseStreamId(stream) !== undefined) return stream;
+  const jobKey = jobKeyOfJobStream(stream);
+  if (jobKey === undefined) return stream;
+  return correlation?.resolve(jobKey)?.stream ?? durable?.get(jobKey)?.stream ?? stream;
+}
+
 /**
  * The ONE canonical single-stream transcript read, shared by BOTH routes that serve it (#744):
  * `GET /agentic/transcripts?stream=<id>&from=<n>` (the proxy-safe QUERY form the cockpit clients
@@ -259,6 +288,10 @@ export type SingleTranscriptResult =
  * `GET /agentic/transcripts/{stream}` (the legacy path form the worker-emitted `transcriptUrl`
  * resolves — safe there because `job:<jobKey>` ids structurally never contain a slash). One
  * implementation so the two addressings can never answer differently for the same stream/from.
+ *
+ * A Stage-0 `job:<jobKey>` alias is first resolved to the instance-scoped id the bytes are stored under
+ * ({@link canonicalStreamFor}), so both the durable store read AND the live-ring fallback address the
+ * stream the producer actually wrote (issue #738) rather than 404-ing the alias.
  */
 export function readSingleTranscript(
   stream: string,
@@ -274,13 +307,14 @@ export function readSingleTranscript(
     // No relay/transcript service mounted at all - nothing to replay.
     return { status: 404, body: { error: "no transcript for stream" } };
   }
+  const readStream = canonicalStreamFor(stream, correlation, service.correlationStore);
   const data = readTranscriptFrom(
-    stream,
+    readStream,
     offset,
     service.store,
     correlation,
     service.correlationStore,
-    service.liveFallback(stream),
+    service.liveFallback(readStream),
   );
   if (data === undefined) {
     return { status: 404, body: { error: "no transcript for stream" } };

package/app/contracts.ts

@@ -468,7 +468,7 @@ export const WIRE_CONTRACTS = {
     name: "transcript.lifecycleClose",
     owner: "app/agentic/families/relay.family.ts",
     semantics:
-      "The harness's job-end `phase:\"close\"` transcript `lifecycle` event (issue #710, harness half jwulf/c8ctl-plugin-nano#150) — the closing twin of the `phase:\"open\"` RELAY_OPEN_CHUNK the harness emits at relay-session open. The harness emits it on the `job:<jobKey>` relay stream through agentic's own `encodeTranscriptEvent` (never hand-rolled), right before `job.complete`/`job.fail` and AFTER draining its outbound relay buffer, so it is the deterministic \"all this job's bytes are here, it is done\" signal. The app recognizes it in `isTerminalLifecycleChunk` (relay.family.ts) to `completeStream()` — flush the durable past-session transcript and release job⇄instance correlation — at job-completion time, fixing the truncated-tail defect where the flush waited for a supersede/disconnect. `close` is NOT a core agentic `LifecycleEvent` phase (the contract's phases are open|completed|exited); the app decodes it via an ADDITIVE `mergeTranscriptVocab` extension (`RELAY_TERMINAL_VOCAB`) that maps it onto the terminal `completed` phase — never a forked wire shape, and scoped to the relay job-end detector so the cockpit derive (CORE vocab) keeps the close chunk byte-faithful. The `close` trigger is ADDITIVE: supersede + disconnect remain as fallbacks and the `state.completed` guard keeps a close-then-disconnect (or duplicate close) idempotent. Consume this ONE marker — do not re-declare a synonym or a second job-end signal.",
+      "The harness's job-end `phase:\"close\"` transcript `lifecycle` event (issue #710, harness half jwulf/c8ctl-plugin-nano#150) — the closing twin of the `phase:\"open\"` RELAY_OPEN_CHUNK the harness emits at relay-session open. The harness emits it on the job's instance-scoped `composeStreamId(instance, jobKey)` relay stream (issue #738) through agentic's own `encodeTranscriptEvent` (never hand-rolled), right before `job.complete`/`job.fail` and AFTER draining its outbound relay buffer, so it is the deterministic \"all this job's bytes are here, it is done\" signal. The app recognizes it in `isTerminalLifecycleChunk` (relay.family.ts) to `completeStream()` — flush the durable past-session transcript and release job⇄instance correlation — at job-completion time, fixing the truncated-tail defect where the flush waited for a supersede/disconnect. `close` is NOT a core agentic `LifecycleEvent` phase (the contract's phases are open|completed|exited); the app decodes it via an ADDITIVE `mergeTranscriptVocab` extension (`RELAY_TERMINAL_VOCAB`) that maps it onto the terminal `completed` phase — never a forked wire shape, and scoped to the relay job-end detector so the cockpit derive (CORE vocab) keeps the close chunk byte-faithful. The `close` trigger is ADDITIVE: supersede + disconnect remain as fallbacks and the `state.completed` guard keeps a close-then-disconnect (or duplicate close) idempotent. Consume this ONE marker — do not re-declare a synonym or a second job-end signal.",
     shape: '{ nwfTranscriptEvent: 1, kind: "lifecycle", phase: "close" }',
   },
   "transcript.readUrl": {
@@ -484,9 +484,17 @@ export const WIRE_CONTRACTS = {
     name: "agentTask.agentDefinition",
     owner: "resources/processes/*.bpmn",
     semantics:
-      "The engine-native AgentTask marker (issue #745, umbrella #746 — Camunda 8.10 parity). Every `senior:*` agent service task carries `<zeebe:agentDefinition agentType=\"external\" />` INSIDE its `<bpmn:extensionElements>`, COEXISTING with the existing `<zeebe:taskDefinition type=\"senior:*\"/>` dispatch verb (the verb stays, per #464). The marker makes the element eligible for engine-native AgentInstance minting by the worker harness (jwulf/c8ctl-plugin-nano#194): the harness mints Create/Update/Complete AgentInstance/AgentHistory records against the pinned engine (`@nanobpm/engine-wasm` 0.8.6, broker REST, SDK) while the element still emits its NORMAL `senior:*` job. `agentType=\"external\"` means the agent runs OUTSIDE the engine (a remote fleet worker), not an engine-embedded model call. This is the PRODUCER half; the durable AgentInstance/AgentHistory it mints is read back by the Cockpit historical view via `searchAgentInstanceHistory` (the CONSUMER half, deferred until the broker read API is reachable from the app's EngineClient). It is authored in the hand-written BPMN semantic model, NOT the generated `<bpmndi:…>` DI, and survives `npm run layout` untouched. Add the marker to a NEW `senior:*` agent task — never a second/synonym marker element.",
+      "The engine-native AgentTask marker (issue #745, umbrella #746 — Camunda 8.10 parity). Every `senior:*` agent service task carries `<zeebe:agentDefinition agentType=\"external\" />` INSIDE its `<bpmn:extensionElements>`, COEXISTING with the existing `<zeebe:taskDefinition type=\"senior:*\"/>` dispatch verb (the verb stays, per #464). The marker makes the element eligible for engine-native AgentInstance minting by the worker harness (jwulf/c8ctl-plugin-nano#194): the harness mints Create/Update/Complete AgentInstance/AgentHistory records against the pinned engine (`@nanobpm/engine-wasm` 0.8.6, broker REST, SDK) while the element still emits its NORMAL `senior:*` job. `agentType=\"external\"` means the agent runs OUTSIDE the engine (a remote fleet worker), not an engine-embedded model call. This is the PRODUCER half; the durable AgentInstance/AgentHistory it mints is read back by the Cockpit historical view via `searchAgentInstanceHistory` (the CONSUMER half — see the `agentTask.historyRead` contract; the read path landed on `@nanobpm/urban`'s EngineClient in urban 0.93 / nanobpm/nano-ide#563). It is authored in the hand-written BPMN semantic model, NOT the generated `<bpmndi:…>` DI, and survives `npm run layout` untouched. Add the marker to a NEW `senior:*` agent task — never a second/synonym marker element.",
     shape: '<zeebe:agentDefinition agentType="external" /> (sibling of <zeebe:taskDefinition> in a senior:* service task\'s extensionElements)',
   },
+  "agentTask.historyRead": {
+    category: "wire",
+    name: "agentTask.historyRead",
+    owner: "app/agentic/agent-history.ts",
+    semantics:
+      "The engine-native AgentInstance/AgentHistory READ path (issue #745/#747, umbrella #746 — the CONSUMER half of the PRODUCER `agentTask.agentDefinition` marker). The Cockpit HISTORICAL transcript + per-turn/instance metrics are sourced from the engine read model through the SINGLE engine-read seam — `@nanobpm/urban`'s `EngineClient.searchAgentInstances`/`searchAgentInstanceHistory`/`getAgentInstance` (added in urban 0.93 / nanobpm/nano-ide#563; the escalation's option (a) — NO `orchestration-cluster-api-js` fork / no second broker-REST client, so the read path is exercised by the testkit WASM double, which records read-as-absence — an empty list / null — while a live engine validates the behavioural parity). ONE narrow reader (`AgentHistoryReader`) + ONE projection (`listAgentInstances`/`readAgentHistory`) in app/agentic/agent-history.ts, served by `GET /agentic/agent-instances` + `GET /agentic/agent-instances/{agentInstanceKey}/history`. Correlation keys are the AGENT-INSTANCE / PROCESS-INSTANCE / ELEMENT-INSTANCE keys (the same #544 per-occupancy element-instance handle the relay correlation uses) — NEVER the slash-bearing `job:<jobKey>` relay stream id, so the #744 gateway-proxy bug class is moot for settled history. The token-granular relay stays the LIVE overlay only (settled history = engine, live tail = relay). Advisory read-only (ADR 0056): it observes the engine read model, never activates/completes a job or gates a sequence flow. The wire shapes (`AgentInstance`/`AgentInstanceList`/`AgentHistoryRecord`/`AgentHistory` + the metrics shapes) are declared in openapi.yaml and reuse the `@nanobpm/agentic/transcript` parity conversation grammar the transcript store already models. Consume this ONE read path — do not add a second agent-history client or a synonym endpoint.",
+    shape: "GET /agentic/agent-instances[?processInstanceKey&rootProcessInstanceKey&elementId&status] → AgentInstanceList; GET /agentic/agent-instances/{agentInstanceKey}/history[?role&loopIteration&elementInstanceKey] → AgentHistory",
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {

package/app/mcpToolSurface.ts

@@ -98,8 +98,15 @@ export const MCP_TOOL_COUNT_BUDGET = 60;
  * each of the two transcript tools, keeping the `?stream=` form discoverable from the tool surface
  * alone (measured +219 bytes serialized, 83,824 → 84,043 — over the old ceiling's 176-byte
  * headroom). Deliberate, documented growth — not schema fat.
+ *
+ * RAISE PROVENANCE — 84_500 → 86_500 (#745/#747, umbrella #746): the engine-native agent-history
+ * read surface adds two GET tools — `listAgentInstances` and `getAgentInstanceHistory` — that read
+ * the durable AgentInstance / AgentHistory channels for wedge triage (kept on the surface per the
+ * `x-mcp` convention that read/orient doors stay exposed; only operator-only control doors are
+ * excluded, see app/mcpExclusions.test.ts). Measured +1,846 bytes serialized (84,043 → 85,889 —
+ * over the old ceiling's 457-byte headroom). Deliberate, documented growth — not schema fat.
  */
-export const MCP_SURFACE_BYTES_BUDGET = 84_500;
+export const MCP_SURFACE_BYTES_BUDGET = 86_500;
 
 /**
  * The eagerly-loaded curated subset MUST stay materially smaller than the full surface — otherwise it

package/db/migrations/101_agentic_history_read_expand.sql

@@ -0,0 +1,34 @@
+-- Engine-native AgentInstance/AgentHistory read path — EXPAND phase (issue #745/#747, umbrella #746).
+--
+-- The CONSUMER half of the durable-agent-transcript work. The Cockpit HISTORICAL transcript + per-turn
+-- and instance metrics are now sourced from the engine read model (`searchAgentInstances` /
+-- `searchAgentInstanceHistory` / `getAgentInstance` on `@nanobpm/urban`'s EngineClient — urban 0.93 /
+-- nanobpm/nano-ide#563), served by `GET /agentic/agent-instances` and
+-- `GET /agentic/agent-instances/{agentInstanceKey}/history` (app/agentic/agent-history.ts). Settled
+-- history now derives from engine truth, keyed by agent-instance / process-instance / element-instance
+-- keys — never the slash-bearing `job:<jobKey>` relay stream id.
+--
+-- EXPAND / CONTRACT DISCIPLINE (AGENTS.md — forward-only, additive expand; destructive contract later):
+--
+--   • EXPAND (this phase, no schema change): begin sourcing HISTORICAL reads from engine AgentHistory.
+--     The engine read path holds no app-side table (it reads the engine read model over the SDK/broker),
+--     so there is NO new DDL and NOTHING is dropped here. This migration records the transition in the
+--     schema history so the expand phase is an explicit, ordered ledger entry, mirroring the DDL-less
+--     documented-meaning precedent in 013_merge_train_waiting_lane.sql.
+--
+--   • RETAIN (unchanged): the relay transcript tables `agentic_transcript_stream` /
+--     `agentic_transcript_chunk` (024_agentic_transcript.sql) and the `transcript.readUrl` scheme STAY.
+--     They remain the LIVE OVERLAY — the token-granular tail of a still-running agent — which the engine
+--     settled-history read deliberately does NOT replace. Do not drop them here.
+--
+--   • CONTRACT (a LATER, separate phase — tracked, NOT executed here): once nothing reads the relay
+--     tables / the transcript-URL scheme for SETTLED history (i.e. the live overlay is the only remaining
+--     consumer, or it too has moved), a future forward-only migration DROPs `agentic_transcript_*` and
+--     retires the URL scheme. That destructive drop is intentionally deferred behind a release that has
+--     stopped reading the old shape (expand-and-contract), and is tracked as its own issue so the
+--     remainder is a filed, claimable work item rather than invisible prose.
+--     Deferred-to: nanobpm/nano-workforce#755
+--
+-- Additive and idempotent: no column/table is created, altered, or dropped, so it is safe to apply
+-- forward over any earlier schema and re-runs are no-ops.
+SELECT 1;