@nanobpm/nano-workforce 0.139.4 → 0.140.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.140.0](https://github.com/nanobpm/nano-workforce/compare/v0.139.4...v0.140.0) (2026-08-25)
+
+### Features
+
+* **agentic:** emit transcriptUrl as a job-output variable (Stage 0, [#543](https://github.com/nanobpm/nano-workforce/issues/543)) ([#547](https://github.com/nanobpm/nano-workforce/issues/547)) ([26b8410](https://github.com/nanobpm/nano-workforce/commit/26b84105405f283acad35ea4026e247fc92d607c)), closes [#544](https://github.com/nanobpm/nano-workforce/issues/544) [#486](https://github.com/nanobpm/nano-workforce/issues/486) [#486](https://github.com/nanobpm/nano-workforce/issues/486)
+
 ## [0.139.4](https://github.com/nanobpm/nano-workforce/compare/v0.139.3...v0.139.4) (2026-08-25)
 
 ### Bug Fixes

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

@@ -292,6 +292,37 @@ test("retention: a disconnected producer auto-completes its ephemeral stream on
   service.teardown();
 });
 
+test("#486 live fallback: an uncompleted stream's ring is served pre-flush, then yields to the durable store", () => {
+  const registry = new ConnectionRegistry();
+  const hub = capturingHub();
+  const service = new RelayTranscriptService({
+    hub,
+    registry,
+    db: memoryDb(),
+    log: noopLog(),
+    now: () => "2026-03-04T05:06:07.000Z",
+  });
+  const p = connect("prod", registry);
+  for (let i = 0; i < 3; i++) hub.handler?.(produce(jobStream("Lk1"), 1, `r${i}`), p.conn);
+
+  // The job has completed and emitted its transcriptUrl, but this multiplexing worker is still live so
+  // no disconnect/supersede flushed the ring — the durable store still 404s (#486). The live fallback
+  // exposes the captured ring + its opened-at instant so the read path can serve it immediately.
+  assertEquals(service.transcriptOf(jobStream("Lk1")), undefined, "not yet flushed while the worker is live");
+  const live = service.liveFallback(jobStream("Lk1"));
+  assert(live !== undefined, "a live, unflushed stream has a serveable ring");
+  assertEquals(live.createdAt, "2026-03-04T05:06:07.000Z", "createdAt is the stream's opened-at instant");
+  assertEquals(live.ring.since(0).entries.length, 3, "the whole captured window is available");
+  assertEquals(live.ring.nextOffset, 3);
+
+  // Once the stream completes (flushed to durable), the durable store is the source of truth and the
+  // live fallback steps aside so a completed transcript is never double-sourced.
+  service.completeStream(jobStream("Lk1"));
+  assertEquals(service.transcriptOf(jobStream("Lk1"))?.status, "completed");
+  assertEquals(service.liveFallback(jobStream("Lk1")), undefined, "a completed stream no longer falls back to the ring");
+  service.teardown();
+});
+
 test("H6 correlation write-side: a produce on job:<k> links instance→[k]; stream completion releases it", () => {
   const registry = new ConnectionRegistry();
   const correlation = new CorrelationRegistry();

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

@@ -90,6 +90,14 @@ interface StreamState {
    * instance is not yet resolvable (a register/produce race), so a later `produce` frame retries.
    */
   linked: boolean;
+  /**
+   * When this stream's in-memory state was first opened, ISO-8601 (stamped from the service clock).
+   * The durable transcript row carries its own `created_at` (stamped at flush/`open`), but a
+   * still-live ephemeral stream has no durable row yet (#486): its ring holds the captured bytes but
+   * the store 404s until a producer disconnect / supersede flushes it. This is the authoritative
+   * "when opened" for {@link RelayTranscriptService.liveFallback} to serve the pre-flush ring.
+   */
+  createdAt: string;
   /**
    * The worker instance a `job:<jobKey>` stream was linked under (H6). Recorded so a stream's release
    * (completion / disconnect) can tidy the {@link RelayTranscriptService.#jobStreamByInstance}
@@ -536,10 +544,30 @@ export class RelayTranscriptService {
     }
   }
 
+  /**
+   * The still-live relay ring for a stream, for the read path to serve BEFORE a durable flush (#486).
+   *
+   * A multiplexing worker relays every job over one long-lived connection, one job at a time, so an
+   * ephemeral job stream is only flushed to the durable store when the worker disconnects or a NEW
+   * job supersedes it — NOT when the job itself completes. In the window between "job completed
+   * (`transcriptUrl` emitted)" and that flush, {@link TranscriptStore.get} returns undefined and the
+   * transcript endpoint would 404 the freshly-emitted URL. This exposes the live ring (+ its opened-at
+   * instant) so {@link readTranscriptFrom} can serve the captured bytes directly, making the URL
+   * readable the moment it is emitted. Returns undefined when there is no live ring, or once the
+   * stream has been completed (the durable store is then the source of truth).
+   */
+  liveFallback(stream: string): { ring: TranscriptRing; createdAt: string } | undefined {
+    const ring = this.relay.ring(stream);
+    if (ring === undefined) return undefined;
+    const state = this.#streams.get(stream);
+    if (state?.completed) return undefined;
+    return { ring, createdAt: state?.createdAt ?? this.#now() };
+  }
+
   #stateFor(stream: string): StreamState {
     let state = this.#streams.get(stream);
     if (state === undefined) {
-      state = { lifecycle: "ephemeral", completed: false, linked: false };
+      state = { lifecycle: "ephemeral", completed: false, linked: false, createdAt: this.#now() };
       this.#streams.set(stream, state);
     }
     return state;

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

@@ -6,10 +6,10 @@
 // interaction with a missing/invalid createdAt — where a hand-built store lets us fix exact timestamps.
 import { test } from "node:test";
 import { DatabaseSync } from "node:sqlite";
-import type { SqliteDb, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
+import type { SqliteDb, TranscriptRing, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
 import { assert, assertEquals } from "#test-assert";
 import { AgenticCorrelationStore } from "./correlation-store.ts";
-import { correlationFieldsFor, listTranscripts } from "./transcript-read.ts";
+import { correlationFieldsFor, listTranscripts, readTranscriptFrom } from "./transcript-read.ts";
 
 /** A read-only TranscriptStore double: list() returns the seeded metas; read() has no retained chunks. */
 function fakeStore(metas: TranscriptStream[]): TranscriptStore {
@@ -122,3 +122,96 @@ test("listTranscripts: the instance filter returns only sessions the durable sto
   );
   assert(out.every((t) => t.instance === "worker-A"), "each row is attributed to worker-A");
 });
+
+// --- #486: the still-live-ring read fallback that makes a freshly-emitted transcriptUrl readable ---
+//
+// A multiplexing worker relays every job over one long-lived connection and only flushes a job's ring
+// to the durable store when it disconnects or a NEW job supersedes it — NOT when the job completes. In
+// the window between "job completed (transcriptUrl emitted)" and that flush, the durable store has no
+// row, so the transcript endpoint must serve the live ring or it would 404 the URL it just emitted.
+
+/** A minimal live ring double satisfying {@link TranscriptRing}: the whole retained window from `from`. */
+function fakeRing(entries: { offset: number; chunk: string }[]): TranscriptRing {
+  const nextOffset = entries.length === 0 ? 0 : entries[entries.length - 1].offset + 1;
+  return {
+    since: (from: number) => ({ entries: entries.filter((e) => e.offset >= from) }),
+    nextOffset,
+  };
+}
+
+/** A store double whose `get` returns a seeded row (or undefined), with the matching `since` window. */
+function getStore(row: TranscriptStream | undefined, entries: { offset: number; chunk: string }[] = []): TranscriptStore {
+  return {
+    get: (_stream: string) => row,
+    since: (_stream: string, from: number) => ({
+      entries: entries.filter((e) => e.offset >= from),
+      gap: false,
+      nextOffset: row?.nextOffset ?? 0,
+    }),
+  } as unknown as TranscriptStore;
+}
+
+test("readTranscriptFrom: falls back to the live ring when the durable store has no row (#486)", () => {
+  const ring = fakeRing([
+    { offset: 0, chunk: "hello " },
+    { offset: 1, chunk: "world" },
+  ]);
+  const out = readTranscriptFrom("job:live1", 0, getStore(undefined), undefined, undefined, {
+    ring,
+    createdAt: mid,
+  });
+  assert(out !== undefined, "a live-but-unflushed stream is readable, not a 404");
+  assertEquals(out.status, "open", "an unflushed live stream reads as open");
+  assertEquals(out.lifecycle, "ephemeral");
+  assertEquals(out.createdAt, mid);
+  assertEquals(out.nextOffset, 2);
+  assertEquals(out.chunkCount, 2);
+  assertEquals(
+    out.entries.map((e) => e.chunk).join(""),
+    "hello world",
+    "the captured bytes are served straight from the ring",
+  );
+  assertEquals(out.jobKey, "live1", "the jobKey is still decoded from the stream id");
+});
+
+test("readTranscriptFrom: the live-ring fallback honours the resume-from offset", () => {
+  const ring = fakeRing([
+    { offset: 0, chunk: "a" },
+    { offset: 1, chunk: "b" },
+    { offset: 2, chunk: "c" },
+  ]);
+  const out = readTranscriptFrom("job:live2", 2, getStore(undefined), undefined, undefined, { ring, createdAt: mid });
+  assert(out !== undefined);
+  assertEquals(out.from, 2);
+  assertEquals(
+    out.entries.map((e) => e.chunk).join(""),
+    "c",
+    "only chunks at/after the requested offset are replayed",
+  );
+});
+
+test("readTranscriptFrom: prefers the durable store once the ring has been flushed", () => {
+  const row: TranscriptStream = {
+    stream: "job:flushed",
+    lifecycle: "ephemeral",
+    status: "completed",
+    createdAt: early,
+    completedAt: late,
+    nextOffset: 1,
+  };
+  const store = getStore(row, [{ offset: 0, chunk: "durable" }]);
+  // A live ring is ALSO provided, but the flushed durable row wins (it is the source of truth once flushed).
+  const out = readTranscriptFrom("job:flushed", 0, store, undefined, undefined, {
+    ring: fakeRing([{ offset: 0, chunk: "stale-ring" }]),
+    createdAt: mid,
+  });
+  assert(out !== undefined);
+  assertEquals(out.status, "completed", "the flushed durable row is served, not the live ring");
+  assertEquals(out.completedAt, late);
+  assertEquals(out.entries.map((e) => e.chunk).join(""), "durable");
+});
+
+test("readTranscriptFrom: returns undefined when neither the store nor a live ring has the stream", () => {
+  const out = readTranscriptFrom("job:gone", 0, getStore(undefined), undefined, undefined, undefined);
+  assertEquals(out, undefined);
+});

package/app/agentic/transcript-read.ts

@@ -14,7 +14,7 @@
 // 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 type { TranscriptChunk, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
+import type { TranscriptChunk, TranscriptRing, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
 import type { AgenticTranscript, AgenticTranscriptData } from "../../nano-generated/api-io.d.ts";
 import { type CorrelationRegistry, jobKeyOfStream } from "./correlation.ts";
 import type { AgenticCorrelationStore } from "./correlation-store.ts";
@@ -163,33 +163,64 @@ export function listTranscripts(
 /**
  * Fetch a stored transcript's bytes from offset `from` (inclusive), projected onto the range/offset
  * wire shape — the SAME resume-from-offset contract the live terminal renders, so the cockpit replays
- * a closed stream through its existing renderer. Returns undefined when the stream has no transcript.
+ * a closed stream through its existing renderer.
+ *
+ * Reads the durable {@link TranscriptStore} first; when the store has no row for the stream (it was
+ * never persisted, or — the #486 caveat — the job completed on a still-live multiplexing worker whose
+ * ring has not been flushed yet) it falls back to the injected live ring so a freshly-emitted
+ * `transcriptUrl` is readable the moment it is emitted. Returns undefined only when neither the store
+ * nor a live ring has the stream.
  */
 export function readTranscriptFrom(
   stream: string,
   from: number,
-  store: TranscriptStore,
+  store: TranscriptStore | undefined,
   correlation: CorrelationRegistry | undefined,
   durable?: AgenticCorrelationStore | undefined,
+  live?: { ring: TranscriptRing; createdAt: string } | undefined,
 ): AgenticTranscriptData | undefined {
-  const meta = store.get(stream);
-  if (meta === undefined) return undefined;
-  const slice = store.since(stream, from);
-  const entries = slice.entries.map((c) => ({ offset: c.offset, chunk: c.chunk }));
-  const out: AgenticTranscriptData = {
-    stream: meta.stream,
-    lifecycle: meta.lifecycle,
-    status: meta.status,
-    createdAt: meta.createdAt,
-    nextOffset: slice.nextOffset,
-    byteLength: byteLengthOf(slice.entries),
-    chunkCount: entries.length,
-    from,
-    gap: slice.gap,
-    entries,
-  };
-  if (meta.completedAt !== undefined) out.completedAt = meta.completedAt;
-  const fields = correlationFieldsFor(meta.stream, correlation, durable);
+  const meta = store?.get(stream);
+  let out: AgenticTranscriptData;
+  if (store !== undefined && meta !== undefined) {
+    const slice = store.since(stream, from);
+    const entries = slice.entries.map((c) => ({ offset: c.offset, chunk: c.chunk }));
+    out = {
+      stream: meta.stream,
+      lifecycle: meta.lifecycle,
+      status: meta.status,
+      createdAt: meta.createdAt,
+      nextOffset: slice.nextOffset,
+      byteLength: byteLengthOf(slice.entries),
+      chunkCount: entries.length,
+      from,
+      gap: slice.gap,
+      entries,
+    };
+    if (meta.completedAt !== undefined) out.completedAt = meta.completedAt;
+  } else if (live !== undefined) {
+    // #486: no durable row yet — the job completed on a still-live multiplexing worker whose ring has
+    // not been flushed. Serve the captured bytes straight from the live ring so a freshly-emitted
+    // `transcriptUrl` is readable immediately (an open ephemeral stream), rather than 404-ing until the
+    // worker disconnects. `gap` is derived structurally: the first returned entry sitting past `from`
+    // means retention already evicted the requested prefix.
+    const slice = live.ring.since(from);
+    const entries = slice.entries.map((c) => ({ offset: c.offset, chunk: c.chunk }));
+    out = {
+      stream,
+      lifecycle: "ephemeral",
+      status: "open",
+      createdAt: live.createdAt,
+      nextOffset: live.ring.nextOffset,
+      byteLength: byteLengthOf(slice.entries),
+      chunkCount: entries.length,
+      from,
+      gap: entries.length > 0 && entries[0].offset > from,
+      entries,
+    };
+  } else {
+    return undefined;
+  }
+  const fields = correlationFieldsFor(out.stream, correlation, durable);
   if (fields.jobKey !== undefined) out.jobKey = fields.jobKey;
   if (fields.processInstanceKey !== undefined) out.processInstanceKey = fields.processInstanceKey;
   if (fields.bpmnProcessId !== undefined) out.bpmnProcessId = fields.bpmnProcessId;

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

@@ -0,0 +1,35 @@
+// Unit coverage for the transcript-URL SSOT (#543): the base a worker prepends and the full per-job
+// URL it emits must derive from ONE path string and the ONE jobStream() encoder, so the seed the
+// dispatcher hands each agent job, the endpoint route, and the tests can never drift apart.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { jobStream } from "./correlation.ts";
+import {
+  TRANSCRIPT_URL_BASE_VAR,
+  TRANSCRIPT_URL_VAR,
+  transcriptUrlBaseFor,
+  transcriptUrlForJob,
+} from "./transcript-url.ts";
+
+const BASE = "https://nano.example.com";
+
+test("the variable names are the stable wire contract Explorer and the worker agree on", () => {
+  assertEquals(TRANSCRIPT_URL_VAR, "transcriptUrl");
+  assertEquals(TRANSCRIPT_URL_BASE_VAR, "transcriptUrlBase");
+});
+
+test("transcriptUrlBaseFor: the seeded base is the app mount's transcript endpoint, trailing-slashed", () => {
+  assertEquals(transcriptUrlBaseFor(BASE), `${BASE}/app/api/agentic/transcripts/`);
+});
+
+test("transcriptUrlForJob: the full URL is the base + the jobKey-scoped stream id", () => {
+  const jobKey = "2251799813685249";
+  assertEquals(transcriptUrlForJob(jobKey, BASE), `${BASE}/app/api/agentic/transcripts/${jobStream(jobKey)}`);
+});
+
+test("derivation: transcriptUrlForJob is exactly transcriptUrlBaseFor + jobStream — no second path source", () => {
+  // This is the anti-drift invariant: the value a worker emits and the base the dispatcher seeds share
+  // a single origin, so a route change in one place can never leave the other pointing at a 404.
+  const jobKey = "job-abc";
+  assertEquals(transcriptUrlForJob(jobKey, BASE), `${transcriptUrlBaseFor(BASE)}${jobStream(jobKey)}`);
+});

package/app/agentic/transcript-url.ts

@@ -0,0 +1,54 @@
+// nano-workforce — the agent-job transcript URL contract (ADR 0006 §4b, Stage 0 / #543).
+//
+// The zero-infra correlation slice: on agentic job completion the completing worker emits a
+// `transcriptUrl` output variable pointing at the durable HTTP transcript endpoint for its own
+// `jobKey`, so Nano Explorer's variables panel links a process run to its agent transcript with no
+// Explorer change and no new correlation infra (that sharper element-instance keying is Stage 1,
+// #544). This module is the SINGLE SOURCE OF TRUTH for that URL's shape: the seed the dispatcher hands
+// each agent job, the value the worker emits, and the tests all derive from it, so they cannot drift
+// from one another. It is authored to match the endpoint route the `getAgenticTranscript` operation
+// serves (`GET /app/api/agentic/transcripts/{stream}` in `openapi.yaml`) — see {@link TRANSCRIPT_STREAM_PATH}.
+//
+// The value is worker-supplied because only the completing worker knows its own `jobKey` (the engine
+// exposes no job/element/process key to an output-mapping FEEL context — it is job metadata, not a
+// variable). So the app SEEDS the base URL onto the agent job (`transcriptUrlBase`) and the worker
+// appends its jobKey-scoped stream id, keeping the fleet worker app-agnostic (a bare concatenation)
+// while this module owns every path segment.
+
+import { publicBaseUrl } from "../blackboard.ts";
+import { jobStream } from "./correlation.ts";
+
+/** The job-output variable a completed agent job carries its transcript URL on (rendered by Explorer). */
+export const TRANSCRIPT_URL_VAR = "transcriptUrl";
+
+/** The input variable the dispatcher seeds onto an agent job so the worker can build {@link TRANSCRIPT_URL_VAR}
+ *  by appending its own jobKey-scoped stream — the worker never needs to know the app's mount path. */
+export const TRANSCRIPT_URL_BASE_VAR = "transcriptUrlBase";
+
+/** The control-API path (under the app mount) the transcript stream endpoint is served at, ending in a
+ *  trailing slash so a `{stream}` id appends cleanly. This is the app-tier authoring used to BUILD the
+ *  transcript URL (the seed the dispatcher hands each agent job, the value the worker emits, and the
+ *  tests) — the single origin those derive from, so they cannot drift from one another. It is NOT the
+ *  sole authoring of the route string itself: the endpoint route is declared by the `getAgenticTranscript`
+ *  operation (`GET /app/api/agentic/transcripts/{stream}` in `openapi.yaml`), and the cockpit embed
+ *  carries its own module-anchored default (`pages/cockpit/mount.js`). Keep this value in step with that
+ *  route. */
+const TRANSCRIPT_STREAM_PATH = "/app/api/agentic/transcripts/";
+
+/**
+ * The externally-reachable base a worker prepends to its jobKey-scoped stream id to form the
+ * transcript URL: `<publicBaseUrl>/app/api/agentic/transcripts/`. The worker appends `job:<jobKey>`
+ * ({@link jobStream}). Trailing slash included so the concatenation is a bare append.
+ */
+export function transcriptUrlBaseFor(base: string = publicBaseUrl()): string {
+  return `${base}${TRANSCRIPT_STREAM_PATH}`;
+}
+
+/**
+ * The full durable transcript URL for a completed job's `jobKey` — the value a worker emits on
+ * {@link TRANSCRIPT_URL_VAR}. Derived from {@link transcriptUrlBaseFor} + {@link jobStream} so it can
+ * never disagree with the base the dispatcher seeds or the endpoint route it resolves to.
+ */
+export function transcriptUrlForJob(jobKey: string, base: string = publicBaseUrl()): string {
+  return `${transcriptUrlBaseFor(base)}${jobStream(jobKey)}`;
+}

package/app/deliveryGraphCompiler.test.ts

@@ -81,6 +81,33 @@ test("happy path: a well-formed graph compiles to a full preview with no side ef
   assertEquals(r.sideEffects.length, 2);
 });
 
+test("#543 transcript correlation: only an agent node seeds transcriptUrlBase and emits transcriptUrl", async () => {
+  const r = await compileOk(RELEASE_RUNBOOK);
+  // The agent node's subProcess ioMapping threads the seeded base IN (so the completing worker can
+  // build its own jobKey-scoped URL) and propagates the worker-set transcriptUrl OUT to the instance.
+  assert(
+    /<zeebe:input source="=if \(is defined\(transcriptUrlBase\)\) then transcriptUrlBase else null" target="transcriptUrlBase"/.test(
+      r.bpmn,
+    ),
+    "an agent node seeds transcriptUrlBase",
+  );
+  assert(
+    /<zeebe:output source="=if \(is defined\(transcriptUrl\)\) then transcriptUrl else null" target="transcriptUrl"/.test(r.bpmn),
+    "an agent node propagates the worker-emitted transcriptUrl up to the instance scope",
+  );
+  // RELEASE_RUNBOOK has exactly ONE agent node — wait/human/connector must NOT carry the mapping.
+  assertEquals(
+    (r.bpmn.match(/target="transcriptUrl"/g) ?? []).length,
+    1,
+    "only the agent node emits transcriptUrl (non-agent kinds do not)",
+  );
+  assertEquals(
+    (r.bpmn.match(/target="transcriptUrlBase"/g) ?? []).length,
+    1,
+    "only the agent node seeds transcriptUrlBase",
+  );
+});
+
 test("determinism: the same JSON always yields byte-identical bpmn/diagram/resolved", async () => {
   const a = await compileOk(RELEASE_RUNBOOK);
   const b = await compileOk(RELEASE_RUNBOOK);

package/app/deliveryGraphCompiler.ts

@@ -35,6 +35,7 @@ import type {
   ResolvedDeliveryEdge,
   ResolvedDeliveryNode,
 } from "../nano-generated/api-io.d.ts";
+import { TRANSCRIPT_URL_BASE_VAR, TRANSCRIPT_URL_VAR } from "./agentic/transcript-url.ts";
 import { DELIVERY_CONNECTOR_TASK_TYPE } from "./deliveryConnector.ts";
 import {
   analyzeExclusiveTopology,
@@ -815,6 +816,11 @@ function ioMappingLines(w: NodeWiring, boundInputs: readonly BoundInput[]): stri
       inputs.push({ source: cfg("jobType"), target: "jobType" });
       inputs.push({ source: cfg("appendPrompt"), target: "appendPrompt" });
       inputs.push({ source: cfg("timeout"), target: "nodeTimeout" });
+      // Stage 0 transcript correlation (#543): seed the transcript URL base so the completing fleet
+      // worker can append its own jobKey-scoped stream and emit `transcriptUrl` (below). `transcriptUrlBase`
+      // is a top-level launch variable (deliveryRunner) — guarded so a hand-seeded instance without it
+      // threads null rather than raising a FEEL error.
+      inputs.push({ source: guarded(TRANSCRIPT_URL_BASE_VAR), target: TRANSCRIPT_URL_BASE_VAR });
       break;
     case "wait":
       inputs.push({ source: cfg("gateKey"), target: "gateKey" });
@@ -862,6 +868,14 @@ function ioMappingLines(w: NodeWiring, boundInputs: readonly BoundInput[]): stri
     outputs.push({ source: guarded(factSourceVar(node.kind, fact)), target: `${el}_${fact.name}` });
   }
 
+  // Stage 0 transcript correlation (#543): propagate the completing worker's `transcriptUrl` (built
+  // from the seeded base + its jobKey) up to the process-instance scope, where Nano Explorer's
+  // variables panel renders it as the link from this run to the agent's transcript. Guarded so a job
+  // completed without it (an older fleet worker) threads null instead of raising a FEEL error.
+  if (node.kind === "agent") {
+    outputs.push({ source: guarded(TRANSCRIPT_URL_VAR), target: TRANSCRIPT_URL_VAR });
+  }
+
   const lines: string[] = ["        <zeebe:ioMapping>"];
   for (const i of inputs) lines.push(`          <zeebe:input ${attr("source", i.source)} target="${i.target}" />`);
   for (const o of outputs) lines.push(`          <zeebe:output ${attr("source", o.source)} target="${o.target}" />`);

package/app/deliveryGraphDeploy.test.ts

@@ -22,6 +22,13 @@ import { assert, assertEquals } from "#test-assert";
 import { DELIVERY_CONNECTOR_TASK_TYPE } from "./deliveryConnector.ts";
 import { compileDeliveryGraph } from "./deliveryGraphCompiler.ts";
 import { runDeliveryGraph } from "./deliveryRunner.ts";
+import { jobStream } from "./agentic/correlation.ts";
+import {
+  TRANSCRIPT_URL_BASE_VAR,
+  TRANSCRIPT_URL_VAR,
+  transcriptUrlBaseFor,
+  transcriptUrlForJob,
+} from "./agentic/transcript-url.ts";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
 
 /** A graph exercising the full node-kind matrix: `agent` (a named `senior:*` job), `wait` (the
@@ -208,6 +215,78 @@ function escapeRe(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+/** Read a running process instance's scope variables out of the wasm engine's raw snapshot, by key. */
+function instanceVariables(engine: { snapshot(): Record<string, unknown> }, key: string): Record<string, unknown> {
+  const snap = engine.snapshot();
+  const instances = snap.instances;
+  assert(Array.isArray(instances), "snapshot.instances is an array of instance rows");
+  const row = instances.find((i): i is { key: string; variables: Record<string, unknown> } => {
+    return typeof i === "object" && i !== null && (i as { key?: unknown }).key === key;
+  });
+  assert(row !== undefined, `no snapshot instance row for ${key}`);
+  return row.variables ?? {};
+}
+
+test("#543 transcript correlation: a completed agent job exposes a resolvable instance-scope transcriptUrl", async () => {
+  const engine = await createWasmEngineClient();
+  try {
+    // A minimal agent→human graph: the agent job completes (emitting its transcript URL the way the
+    // real fleet worker does — the seeded base + its own jobKey-scoped stream), then the instance parks
+    // on the human node so its scope variables are still inspectable (a bare agent graph would COMPLETE
+    // and drop them). The worker captures its jobKey so the test can assert the exact URL the SSOT
+    // builder yields for it.
+    let workerJobKey = "";
+    let seededBase: unknown;
+    await engine.registerWorker(
+      "senior:feature",
+      async (job) => {
+        workerJobKey = String(job.jobKey);
+        seededBase = job.variables?.transcriptUrlBase;
+        // Mirror the harness: append the jobKey-scoped stream id to the app-seeded base (#486/#543).
+        return { transcriptUrl: `${String(job.variables?.transcriptUrlBase)}${jobStream(workerJobKey)}` };
+      },
+      { fetchVariables: [TRANSCRIPT_URL_BASE_VAR] },
+    );
+
+    const graph: DeliveryGraph = {
+      name: "transcript correlation",
+      nodes: [
+        { id: "impl", kind: "agent", agent: { jobType: "senior:feature", prompt: "ship it" } },
+        { id: "review", kind: "human", human: { prompt: "review the run" } },
+      ],
+      edges: [{ from: "impl", to: "review" }],
+    };
+    const run = await runDeliveryGraph(engine, graph);
+    assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
+    const key = run.handle.processInstanceKey;
+
+    // Drive until the agent node has completed and the instance parks on the human user task.
+    let parked = false;
+    for (let round = 0; round < MAX_ROUNDS; round++) {
+      await engine.drain();
+      const open = await engine.searchUserTasks({ processInstanceKey: key, state: "CREATED" });
+      if (open.length > 0) {
+        parked = true;
+        break;
+      }
+    }
+    assert(parked, "the agent node must complete and the instance park on the human node");
+
+    // The app seeded the transcript endpoint base onto the agent job (input mapping)...
+    assertEquals(seededBase, transcriptUrlBaseFor(), "the agent job receives the seeded transcriptUrlBase");
+    // ...and the worker-emitted transcriptUrl propagated up to the process-instance scope (output
+    // mapping), resolving to EXACTLY the SSOT URL for that jobKey — the link Nano Explorer renders.
+    const vars = instanceVariables(engine, key);
+    assertEquals(
+      vars[TRANSCRIPT_URL_VAR],
+      transcriptUrlForJob(workerJobKey),
+      "the completed agent job exposes a resolvable, correct transcriptUrl on the instance",
+    );
+  } finally {
+    await engine.close();
+  }
+});
+
 // ── S7: guarded (conditional) routing DEPLOYS and ROUTES on the real engine (ADR 0005 S7) ──────────
 // The compiler tests prove a guarded split emits an exclusiveGateway with FEEL conditions; only a live
 // deploy proves the engine EVALUATES those conditions and takes exactly ONE branch. Here the `bump`

package/app/deliveryRunner.ts

@@ -16,6 +16,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import type { EngineClient } from "@nanobpm/urban";
 import type { DeliveryFact, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
+import { TRANSCRIPT_URL_BASE_VAR, transcriptUrlBaseFor } from "./agentic/transcript-url.ts";
 import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery, readinessTimeout } from "./readiness.ts";
 import { isoDuration } from "./reviewWait.ts";
@@ -147,7 +148,14 @@ export async function runDeliveryGraph(
   await engine.deployResources([{ name: `${processDefinitionId}.bpmn`, content: bpmn, contentType: "application/xml" }]);
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId,
-    variables: { nodeInputs },
+    variables: {
+      nodeInputs,
+      // Stage 0 transcript correlation (#543): the transcript-endpoint base every agent node's
+      // completing worker appends its jobKey-scoped stream to, to emit `transcriptUrl` (see the agent
+      // node ioMapping in deliveryGraphCompiler). Seeded once at the run root — the same value for
+      // every node — and read down into each agent job via `=transcriptUrlBase`.
+      [TRANSCRIPT_URL_BASE_VAR]: transcriptUrlBaseFor(),
+    },
   });
   // The engine can yield a numeric key; `DeliveryRunHandle.processInstanceKey` is typed `string` and
   // downstream consumers expect a string — coerce (codebase-wide `String(...)` pattern, e.g. app/plan.ts).

package/app/feature.ts

@@ -15,6 +15,7 @@
 // Data access goes through the record gateway (`data.table`), never hand-written
 // SQL — matching app/plan.ts and app/service.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { TRANSCRIPT_URL_BASE_VAR, transcriptUrlBaseFor } from "./agentic/transcript-url.ts";
 import { coalesceTitle, fetchIssueTitle } from "./github.ts";
 import { ESCALATION_SLA_TIMEOUT, normalizeBaseBranch, type ParsedIssue, renderBaseBranchBrief } from "./plan.ts";
 import type { ReadinessProbe } from "./readiness.ts";
@@ -400,6 +401,11 @@ export async function startFeature(
       probePollEvery: readinessProbes ? (readiness.probePollEvery ?? null) : null,
       gateKey: readinessProbes ? `feature-readiness:${parsed.planKey}` : null,
       resolvedArtifacts: null,
+      // Stage 0 transcript correlation (#543): the transcript-endpoint base the `implement-task` agent
+      // worker appends its jobKey-scoped stream to, to emit a `transcriptUrl` output variable that
+      // links this feature run to its agent transcript in Nano Explorer (feature.bpmn `implement-task`
+      // ioMapping). Read down into the job via `=transcriptUrlBase`.
+      [TRANSCRIPT_URL_BASE_VAR]: transcriptUrlBaseFor(),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/operations/getAgenticTranscript.ts

@@ -29,13 +29,21 @@ export default defineOperation("getAgenticTranscript", async ({ params, query, r
   }
 
   const service = currentRelayTranscriptService();
-  const store = service?.store;
-  if (!store) {
-    // No transcript store mounted (relay unmounted or unpersisted) - nothing to replay.
+  if (!service) {
+    // No relay/transcript service mounted at all - nothing to replay.
     return { status: 404, body: { error: "no transcript for stream" } };
   }
 
-  const data = readTranscriptFrom(params.stream, from, store, currentCorrelation(), service?.correlationStore);
+  // Read the durable store first, falling back to the still-live relay ring (#486) so a `transcriptUrl`
+  // emitted by a job on a still-live multiplexing worker is readable before its ring is flushed.
+  const data = readTranscriptFrom(
+    params.stream,
+    from,
+    service.store,
+    currentCorrelation(),
+    service.correlationStore,
+    service.liveFallback(params.stream),
+  );
   if (data === undefined) {
     return { status: 404, body: { error: "no transcript for stream" } };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.139.4",
+  "version": "0.140.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/resources/processes/feature.bpmn

@@ -177,8 +177,10 @@
         </zeebe:linkedResources>
         <zeebe:ioMapping>
           <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (baseBranchBrief = null) then &#34;&#34; else baseBranchBrief) + (if (resolvedArtifacts = null or count(resolvedArtifacts[item != null]) = 0) then &#34;&#34; else (&#34;&#10;&#10;---&#10;&#10;**Bound upstream readiness (intake gate).** This feature was scheduled to wait until an upstream landed and published. Build/install/clone against EXACTLY these resolved published versions (the ones first carrying the awaited capability), and bump the consumer dependency to them — never merely the newest:&#10;&#10;&#34; + string join(resolvedArtifacts[item != null], &#34;&#10;&#34;))) + (if (customInstructions = null) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;## Operator custom instructions&#10;&#10;The operator supplied these instructions for this run — follow them:&#10;&#10;&#34; + customInstructions)" target="appendPrompt" />
+          <zeebe:input source="=if (is defined(transcriptUrlBase)) then transcriptUrlBase else null" target="transcriptUrlBase" />
           <zeebe:output source="=status" target="status" />
           <zeebe:output source="=question" target="question" />
+          <zeebe:output source="=if (is defined(transcriptUrl)) then transcriptUrl else null" target="transcriptUrl" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toImplement</bpmn:incoming>