@nanobpm/nano-workforce 0.139.4 → 0.141.0

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";
@@ -33,6 +33,8 @@ interface CorrelationFields {
   processInstanceKey?: string;
   bpmnProcessId?: string;
   elementId?: string;
+  /** The engine element-instance key the job's token occupied (#544) — per-occupancy, unlike elementId. */
+  elementInstanceKey?: string;
   planKey?: string;
   /** The worker instance that ran the job (durable — survives release / restart). */
   instance?: string;
@@ -63,6 +65,7 @@ export function correlationFieldsFor(
     if (context.processInstanceKey !== undefined) fields.processInstanceKey = context.processInstanceKey;
     if (context.bpmnProcessId !== undefined) fields.bpmnProcessId = context.bpmnProcessId;
     if (context.elementId !== undefined) fields.elementId = context.elementId;
+    if (context.elementInstanceKey !== undefined) fields.elementInstanceKey = context.elementInstanceKey;
     if (context.planKey !== undefined) fields.planKey = context.planKey;
   }
   // Durable fallback: fill any field the live registry did not supply (a released past session, or a
@@ -74,6 +77,9 @@ export function correlationFieldsFor(
     }
     if (fields.bpmnProcessId === undefined && row.bpmnProcessId !== undefined) fields.bpmnProcessId = row.bpmnProcessId;
     if (fields.elementId === undefined && row.elementId !== undefined) fields.elementId = row.elementId;
+    if (fields.elementInstanceKey === undefined && row.elementInstanceKey !== undefined) {
+      fields.elementInstanceKey = row.elementInstanceKey;
+    }
     if (fields.planKey === undefined && row.planKey !== undefined) fields.planKey = row.planKey;
     if (row.instance !== undefined) fields.instance = row.instance;
     if (row.identity !== undefined) fields.identity = row.identity;
@@ -106,6 +112,7 @@ export function toTranscript(
   if (fields.processInstanceKey !== undefined) out.processInstanceKey = fields.processInstanceKey;
   if (fields.bpmnProcessId !== undefined) out.bpmnProcessId = fields.bpmnProcessId;
   if (fields.elementId !== undefined) out.elementId = fields.elementId;
+  if (fields.elementInstanceKey !== undefined) out.elementInstanceKey = fields.elementInstanceKey;
   if (fields.planKey !== undefined) out.planKey = fields.planKey;
   if (fields.instance !== undefined) out.instance = fields.instance;
   if (fields.identity !== undefined) out.identity = fields.identity;
@@ -117,6 +124,8 @@ export function toTranscript(
 export interface TranscriptFilter {
   readonly jobKey?: string;
   readonly processInstanceKey?: string;
+  /** The engine element-instance key (#544) — resolves a session to one occupancy of a looping activity. */
+  readonly elementInstanceKey?: string;
   readonly planKey?: string;
   /** The worker instance that ran the session (durable attribution) — powers the worker-history view. */
   readonly instance?: string;
@@ -145,6 +154,7 @@ export function listTranscripts(
     .filter((t) => {
       if (filter.jobKey !== undefined && t.jobKey !== filter.jobKey) return false;
       if (filter.processInstanceKey !== undefined && t.processInstanceKey !== filter.processInstanceKey) return false;
+      if (filter.elementInstanceKey !== undefined && t.elementInstanceKey !== filter.elementInstanceKey) return false;
       if (filter.planKey !== undefined && t.planKey !== filter.planKey) return false;
       if (filter.instance !== undefined && t.instance !== filter.instance) return false;
       const createdMs = Date.parse(t.createdAt);
@@ -163,37 +173,69 @@ 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;
   if (fields.elementId !== undefined) out.elementId = fields.elementId;
+  if (fields.elementInstanceKey !== undefined) out.elementInstanceKey = fields.elementInstanceKey;
   if (fields.planKey !== undefined) out.planKey = fields.planKey;
   if (fields.instance !== undefined) out.instance = fields.instance;
   if (fields.identity !== undefined) out.identity = fields.identity;

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/db/migrations/086_agentic_correlation_element_instance.sql

@@ -0,0 +1,21 @@
+-- Key the durable agent correlation on the ELEMENT INSTANCE, not just the static BPMN element id
+-- (#544, Stage 1 of transcript↔process-run correlation; ADR 0006 §4b intersection, #464).
+--
+-- `078_agentic_correlation.sql` records `element_id` — the STATIC BPMN id — which is ambiguous across
+-- a looping / retried job: the same activity id occupies many distinct element instances over a
+-- process instance's life, so a transcript keyed only by `element_id` cannot say WHICH occupancy a
+-- token was in. `element_instance_key` is the engine's per-occupancy handle (the same one Nano
+-- Explorer addresses runtime position by, and the one Camunda keys its agent model on), resolved from
+-- the agent job's `jobKey` via the engine element-instance wait-state read (nano-ide#473's binding).
+--
+-- Expand-and-contract: this is the EXPAND step — a nullable, additive column alongside the retained
+-- `element_id` (kept during the transition, never dropped here). NULL for pre-#544 rows and whenever
+-- the (advisory, best-effort) resolution did not land, so it never gates a BPMN sequence flow.
+--
+-- Single source of truth: the durable table's canonical DDL is `AGENTIC_CORRELATION_SCHEMA_SQL` in
+-- `app/agentic/correlation-store.ts` (applied idempotently at store construction). This migration
+-- brings an already-078-migrated DB up to that same effective shape; a drift-guard test
+-- (`correlation-store.test.ts`) pins the migrated schema (078 + 086) to the canonical DDL so the two
+-- can never diverge.
+ALTER TABLE agentic_correlation ADD COLUMN element_instance_key TEXT;
+CREATE INDEX IF NOT EXISTS ix_agentic_correlation_element_instance ON agentic_correlation (element_instance_key);

package/main.ts

@@ -20,6 +20,7 @@
 import { Server } from "node:http";
 import { createNanoSdkEngineClient, runFromEnv, selectHost } from "@nanobpm/urban";
 import { type AgenticChannelHandle, mountAgenticChannel } from "./app/agentic/channel.ts";
+import { makeElementInstanceResolver } from "./app/agentic/element-instance.ts";
 import { announceEngine, resolveEngineAddress } from "./app/enginePreflight.ts";
 import { MAX_ROUNDS, pollOnce } from "./app/service.ts";
 import { envVar } from "./app/version.ts";
@@ -79,6 +80,11 @@ if (httpServer instanceof Server) {
       secret: agenticSecret ?? "",
       secure,
       data: app.data,
+      // #544: advisory, read-only element-instance resolution over the shared engine's wait-state
+      // read model, so the relay slice can key a captured agent session on the element INSTANCE it
+      // occupied (unambiguous across a looping / retried job), not just the static element id. A
+      // narrow closure — the agentic families never hold the engine handle itself.
+      resolveElementInstance: makeElementInstanceResolver(engine),
       log: app.log,
     });
     if (!secure) {

package/openapi.yaml

@@ -643,6 +643,11 @@ components:
         elementId:
           type: string
           description: The BPMN element id (activity/task) the job was for, when still known (advisory).
+        elementInstanceKey:
+          type: string
+          description: The engine element-instance key the job's token occupied (#544) — the per-occupancy
+            handle, unambiguous across a looping / retried activity where many instances share one elementId.
+            Resolved from the job's element-instance wait-state; advisory, present when resolution landed.
         planKey:
           type: string
           description: The plan / epic key this job was part of (e.g. owner/repo#142), when still known (advisory).
@@ -749,6 +754,10 @@ components:
         elementId:
           type: string
           description: The BPMN element id, when still known (advisory).
+        elementInstanceKey:
+          type: string
+          description: The engine element-instance key the job's token occupied (#544) — per-occupancy,
+            unambiguous across a looping / retried activity; advisory, present when resolution landed.
         planKey:
           type: string
           description: The plan / epic key, when still known (advisory).
@@ -2802,6 +2811,13 @@ paths:
           schema:
             type: string
           description: Return only transcripts whose (still-known) correlation names this process instance.
+        - name: elementInstanceKey
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Return only transcripts whose correlation names this engine element-instance key (#544) —
+            resolves a session to one occupancy of a looping / retried activity, unlike the static elementId.
         - name: planKey
           in: query
           required: false

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/operations/listAgenticTranscripts.ts

@@ -46,6 +46,7 @@ export default defineOperation("listAgenticTranscripts", async ({ query, req },
   const filter: TranscriptFilter = {
     ...(query.jobKey !== undefined ? { jobKey: query.jobKey } : {}),
     ...(query.processInstanceKey !== undefined ? { processInstanceKey: query.processInstanceKey } : {}),
+    ...(query.elementInstanceKey !== undefined ? { elementInstanceKey: query.elementInstanceKey } : {}),
     ...(query.planKey !== undefined ? { planKey: query.planKey } : {}),
     ...(query.instance !== undefined ? { instance: query.instance } : {}),
     ...(query.since !== undefined ? { since: query.since } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.139.4",
+  "version": "0.141.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",
@@ -59,7 +59,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.4.0",
-    "@nanobpm/urban": "^0.82.0",
+    "@nanobpm/urban": "^0.83.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {

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>