@nanobpm/nano-workforce 0.140.0 → 0.141.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.141.0](https://github.com/nanobpm/nano-workforce/compare/v0.140.0...v0.141.0) (2026-08-25)
+
+### Features
+
+* **agentic:** key agentic_correlation on elementInstanceKey ([#544](https://github.com/nanobpm/nano-workforce/issues/544)) ([#549](https://github.com/nanobpm/nano-workforce/issues/549)) ([3399597](https://github.com/nanobpm/nano-workforce/commit/33995973f4d207612ba62d6d9c421c40de1bcfba)), closes [nano-ide#473](https://github.com/nanobpm/nano-ide/issues/473)
+
 ## [0.140.0](https://github.com/nanobpm/nano-workforce/compare/v0.139.4...v0.140.0) (2026-08-25)
 
 ### Features

package/app/agentic/channel.ts

@@ -22,6 +22,7 @@ import {
   WebSocketChannelTransport,
 } from "@nanobpm/agentic/channel";
 import type { DataLayer, Logger } from "@nanobpm/urban";
+import type { ElementInstanceResolver } from "./element-instance.ts";
 import { loadAgenticFamilies } from "./loader.ts";
 import { AgenticFamilyRegistry } from "./registry.ts";
 
@@ -83,6 +84,12 @@ export interface MountAgenticChannelOptions {
   readonly secure?: boolean;
   /** The app's SQLite data layer, threaded to family modules (may be absent when data isn't mounted). */
   readonly data: DataLayer | undefined;
+  /**
+   * An advisory, read-only element-instance resolver (#544), threaded to family modules via
+   * {@link AgenticContext.resolveElementInstance}. `main.ts` closes it over the shared engine's
+   * element-instance wait-state read; absent → families run without element-instance enrichment.
+   */
+  readonly resolveElementInstance?: ElementInstanceResolver;
   /** A structured logger for lifecycle lines. */
   readonly log: Logger;
   /**
@@ -193,7 +200,14 @@ export async function mountAgenticChannel(
   let registry: AgenticFamilyRegistry | undefined;
   try {
     registry = await (opts.families ? opts.families() : discoverRegistry(log));
-    await registry.mountAll({ hub, registry: hub.registry, transport, data, log });
+    await registry.mountAll({
+      hub,
+      registry: hub.registry,
+      transport,
+      data,
+      resolveElementInstance: opts.resolveElementInstance,
+      log,
+    });
   } catch (err) {
     await registry?.teardownAll(log);
     await hub.close();

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

@@ -1,6 +1,7 @@
 // Unit tests for the durable worker-attribution store (app/agentic/correlation-store.ts, #485).
-//   - drift guard: db/migrations/078 mirrors AGENTIC_CORRELATION_SCHEMA_SQL;
+//   - drift guard: migrations 078 + 086 reproduce AGENTIC_CORRELATION_SCHEMA_SQL's effective schema;
 //   - record/get/byStream round-trips, including the optional (nullable) engine-context columns;
+//   - byElementInstance read axis (#544) and its per-occupancy uniqueness;
 //   - upsert semantics (re-recording a jobKey is last-write-wins).
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -24,20 +25,60 @@ function memoryDb(): SqliteDb {
   };
 }
 
-test("drift guard: migration 078 mirrors AGENTIC_CORRELATION_SCHEMA_SQL", async () => {
-  const migrationPath = join(HERE, "..", "..", "db", "migrations", "078_agentic_correlation.sql");
-  const raw = await readFile(migrationPath, "utf8");
-  const ddl = raw
-    .split("\n")
-    .filter((line) => !line.trimStart().startsWith("--"))
+/**
+ * The effective schema of `agentic_correlation` as SQLite reports it: the ordered column list
+ * (name/type/nullability/default/pk) plus the set of indexes (name + normalised definition). This is
+ * derivation-over-duplication: comparing the *observed* schema rather than raw DDL text means the
+ * migration path and the canonical DDL are pinned to each other regardless of formatting, so the two
+ * cannot silently drift even though (post expand-and-contract) they are no longer byte-identical text.
+ */
+function effectiveSchema(db: DatabaseSync): string {
+  const columns = db
+    .prepare("PRAGMA table_info(agentic_correlation)")
+    .all()
+    .map((c) => {
+      const col = c as { name: string; type: string; notnull: number; dflt_value: unknown; pk: number };
+      return `${col.name}|${col.type}|${col.notnull}|${col.dflt_value ?? ""}|${col.pk}`;
+    })
     .join("\n");
-  const normalise = (s: string) => s.trim().replace(/\s+/g, " ");
+  const indexes = db
+    .prepare(
+      "SELECT name, sql FROM sqlite_master WHERE type = 'index' AND tbl_name = 'agentic_correlation' ORDER BY name",
+    )
+    .all()
+    .map((i) => {
+      const idx = i as { name: string; sql: string | null };
+      return `${idx.name}|${(idx.sql ?? "").trim().replace(/\s+/g, " ")}`;
+    })
+    .join("\n");
+  return `COLUMNS\n${columns}\nINDEXES\n${indexes}`;
+}
+
+test("drift guard: migrations 078 + 086 reproduce AGENTIC_CORRELATION_SCHEMA_SQL's effective schema", async () => {
+  const migrationsDir = join(HERE, "..", "..", "db", "migrations");
+  const base = await readFile(join(migrationsDir, "078_agentic_correlation.sql"), "utf8");
+  const expand = await readFile(join(migrationsDir, "086_agentic_correlation_element_instance.sql"), "utf8");
+
+  const migrated = new DatabaseSync(":memory:");
+  migrated.exec(base);
+  migrated.exec(expand);
+
+  const canonical = new DatabaseSync(":memory:");
+  canonical.exec(AGENTIC_CORRELATION_SCHEMA_SQL);
+
   assertEquals(
-    normalise(ddl),
-    normalise(AGENTIC_CORRELATION_SCHEMA_SQL),
-    "078_agentic_correlation.sql drifted from AGENTIC_CORRELATION_SCHEMA_SQL",
+    effectiveSchema(migrated),
+    effectiveSchema(canonical),
+    "migrations 078 + 086 drifted from AGENTIC_CORRELATION_SCHEMA_SQL",
+  );
+  // The #544 column and its index are present in both paths.
+  assert(effectiveSchema(canonical).includes("element_instance_key"), "canonical DDL has element_instance_key");
+  assert(
+    effectiveSchema(canonical).includes("ix_agentic_correlation_element_instance"),
+    "canonical DDL indexes element_instance_key",
   );
-  assert(ddl.includes("agentic_correlation"));
+  migrated.close();
+  canonical.close();
 });
 
 test("record + get round-trips full attribution, and byStream decodes the jobKey", () => {
@@ -67,6 +108,41 @@ test("record + get round-trips full attribution, and byStream decodes the jobKey
   assertEquals(store.byStream(jobStream("job-1"))?.instance, "worker-A");
 });
 
+test("byElementInstance keys per-occupancy, distinguishing a looping/retried activity's iterations", () => {
+  const store = new AgenticCorrelationStore(memoryDb());
+  // Two runs of the SAME static element (`agent`) in the same process instance — a loop / retry —
+  // occupy DISTINCT element instances. Keyed on element_id they'd be indistinguishable; keyed on the
+  // element-instance key each resolves to its own attribution (the whole point of #544).
+  store.record({
+    jobKey: "job-iter-1",
+    stream: jobStream("job-iter-1"),
+    instance: "worker-A",
+    processInstanceKey: "pi-9",
+    elementId: "agent",
+    elementInstanceKey: "ei-100",
+    completedAt: "2026-08-23T00:05:00.000Z",
+  });
+  store.record({
+    jobKey: "job-iter-2",
+    stream: jobStream("job-iter-2"),
+    instance: "worker-A",
+    processInstanceKey: "pi-9",
+    elementId: "agent",
+    elementInstanceKey: "ei-200",
+    completedAt: "2026-08-23T00:10:00.000Z",
+  });
+
+  assertEquals(store.get("job-iter-1")?.elementInstanceKey, "ei-100");
+  const first = store.byElementInstance("ei-100");
+  assertEquals(first.length, 1);
+  assertEquals(first[0].jobKey, "job-iter-1");
+  const second = store.byElementInstance("ei-200");
+  assertEquals(second.length, 1);
+  assertEquals(second[0].jobKey, "job-iter-2");
+  assertEquals(store.byElementInstance("ei-nope").length, 0);
+  assertEquals(store.byElementInstance("").length, 0);
+});
+
 test("optional context columns are omitted (not null) when unknown", () => {
   const store = new AgenticCorrelationStore(memoryDb());
   store.record({
@@ -91,6 +167,23 @@ test("record is an upsert: re-recording a jobKey is last-write-wins", () => {
   assertEquals(got?.completedAt, "2026-08-23T02:10:00.000Z");
 });
 
+test("record preserves an existing element_instance_key when a later re-record omits it (monotonic)", () => {
+  const store = new AgenticCorrelationStore(memoryDb());
+  const base = { jobKey: "job-4", stream: jobStream("job-4"), completedAt: "2026-08-23T02:00:00.000Z" };
+  // The durable backfill path (or a first record that carried the resolved key).
+  store.record({ ...base, instance: "worker-D", elementInstanceKey: "ei-777" });
+  // A later best-effort re-record that does NOT know the key must not wipe it back to NULL.
+  store.record({ ...base, instance: "worker-D", host: "later.local" });
+  const got = store.get("job-4");
+  assertEquals(got?.host, "later.local");
+  assertEquals(got?.elementInstanceKey, "ei-777");
+  // setElementInstanceKey backfill then a bare re-record likewise survives.
+  store.record({ jobKey: "job-5", stream: jobStream("job-5"), completedAt: "2026-08-23T03:00:00.000Z", instance: "worker-E" });
+  store.setElementInstanceKey("job-5", "ei-888");
+  store.record({ jobKey: "job-5", stream: jobStream("job-5"), completedAt: "2026-08-23T03:05:00.000Z", instance: "worker-E" });
+  assertEquals(store.get("job-5")?.elementInstanceKey, "ei-888");
+});
+
 test("get is undefined for an unknown jobKey and byStream undefined for a non-job stream", () => {
   const store = new AgenticCorrelationStore(memoryDb());
   assertEquals(store.get("nope"), undefined);

package/app/agentic/correlation-store.ts

@@ -12,14 +12,21 @@
 // by jobKey, so the transcript read path can recover a past session's worker + context after the
 // worker has exited. Advisory / read-only (ADR 0056) — it NEVER gates a BPMN sequence flow.
 //
-// Single source of truth: {@link AGENTIC_CORRELATION_SCHEMA_SQL} is the canonical DDL. It is applied
-// idempotently on store construction (so unit tests over an in-memory DB have the table) AND mirrored
-// byte-for-byte by the forward-only migration `db/migrations/078_agentic_correlation.sql`, which a
-// drift-guard test (`correlation-store.test.ts`) pins so the two can never diverge.
+// Single source of truth: {@link AGENTIC_CORRELATION_SCHEMA_SQL} is the canonical DDL, applied
+// idempotently on store construction (so unit tests over an in-memory DB have the table). Its
+// EFFECTIVE shape is reproduced by the forward-only migrations `db/migrations/078_agentic_correlation.sql`
+// (base table) + `086_agentic_correlation_element_instance.sql` (#544 expand: the additive, nullable
+// `element_instance_key`). A drift-guard test (`correlation-store.test.ts`) applies those migrations to
+// one DB and the canonical DDL to another and asserts the two schemas are identical, so they can never
+// diverge (the migrations, once merged, are immutable — the canonical DDL is what evolves).
 import type { SqliteDb } from "@nanobpm/agentic/transcript";
 import { jobKeyOfStream } from "./correlation.ts";
 
-/** The canonical DDL for the durable correlation table. The `078_*` migration mirrors this exactly. */
+/**
+ * The canonical DDL for the durable correlation table. The `078_*` + `086_*` migrations reproduce this
+ * effective shape (see the drift-guard test); `element_instance_key` is appended LAST to match the
+ * order SQLite gives a column added via `ALTER TABLE ... ADD COLUMN`.
+ */
 export const AGENTIC_CORRELATION_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS agentic_correlation (
   job_key TEXT PRIMARY KEY,
   stream TEXT NOT NULL,
@@ -31,11 +38,13 @@ export const AGENTIC_CORRELATION_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS agenti
   element_id TEXT,
   plan_key TEXT,
   linked_at TEXT,
-  completed_at TEXT NOT NULL
+  completed_at TEXT NOT NULL,
+  element_instance_key TEXT
 );
 CREATE INDEX IF NOT EXISTS ix_agentic_correlation_instance ON agentic_correlation (instance);
 CREATE INDEX IF NOT EXISTS ix_agentic_correlation_process_instance ON agentic_correlation (process_instance_key);
 CREATE INDEX IF NOT EXISTS ix_agentic_correlation_plan ON agentic_correlation (plan_key);
+CREATE INDEX IF NOT EXISTS ix_agentic_correlation_element_instance ON agentic_correlation (element_instance_key);
 `;
 
 /** One durable attribution row: which worker ran a job, plus its (best-effort) engine context. */
@@ -53,6 +62,12 @@ export interface DurableCorrelation {
   readonly linkedAt?: string;
   /** When the job completed (was flushed / released), ISO-8601. */
   readonly completedAt: string;
+  /**
+   * The engine element-instance key the job's token occupies (#544). Unlike {@link elementId} (the
+   * STATIC BPMN id, ambiguous across a looping / retried job), this identifies the specific occupancy.
+   * Best-effort: undefined for pre-#544 rows and whenever resolution did not land.
+   */
+  readonly elementInstanceKey?: string;
 }
 
 /** A row as stored (nullable columns come back as `null`). */
@@ -68,6 +83,7 @@ interface Row {
   plan_key: string | null;
   linked_at: string | null;
   completed_at: string;
+  element_instance_key: string | null;
 }
 
 function fromRow(r: Row): DurableCorrelation {
@@ -86,6 +102,7 @@ function fromRow(r: Row): DurableCorrelation {
     ...(r.element_id !== null ? { elementId: r.element_id } : {}),
     ...(r.plan_key !== null ? { planKey: r.plan_key } : {}),
     ...(r.linked_at !== null ? { linkedAt: r.linked_at } : {}),
+    ...(r.element_instance_key !== null ? { elementInstanceKey: r.element_instance_key } : {}),
   };
 }
 
@@ -104,12 +121,17 @@ export class AgenticCorrelationStore {
     this.#db.exec(AGENTIC_CORRELATION_SCHEMA_SQL);
   }
 
-  /** Upsert a completed job's attribution (last write wins on jobKey). */
+  /**
+   * Upsert a completed job's attribution (last write wins on jobKey). One exception: the async
+   * `element_instance_key` (#544) is written MONOTONICALLY — a re-record that omits it (a common
+   * best-effort enrichment, or a value already set via {@link setElementInstanceKey}) preserves the
+   * stored key via COALESCE rather than clobbering it back to NULL.
+   */
   record(entry: DurableCorrelation): void {
     this.#db.run(
       `INSERT INTO agentic_correlation
-         (job_key, stream, instance, identity, host, process_instance_key, bpmn_process_id, element_id, plan_key, linked_at, completed_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         (job_key, stream, instance, identity, host, process_instance_key, bpmn_process_id, element_id, plan_key, linked_at, completed_at, element_instance_key)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(job_key) DO UPDATE SET
          stream = excluded.stream,
          instance = excluded.instance,
@@ -120,7 +142,8 @@ export class AgenticCorrelationStore {
          element_id = excluded.element_id,
          plan_key = excluded.plan_key,
          linked_at = excluded.linked_at,
-         completed_at = excluded.completed_at`,
+         completed_at = excluded.completed_at,
+         element_instance_key = COALESCE(excluded.element_instance_key, agentic_correlation.element_instance_key)`,
       [
         entry.jobKey,
         entry.stream,
@@ -133,10 +156,26 @@ export class AgenticCorrelationStore {
         entry.planKey ?? null,
         entry.linkedAt ?? null,
         entry.completedAt,
+        entry.elementInstanceKey ?? null,
       ],
     );
   }
 
+  /**
+   * Backfill the element-instance key onto an ALREADY-RECORDED row (#544), for the race where the
+   * asynchronous element-instance resolution returns AFTER the job completed and its attribution was
+   * persisted (the live correlation is gone, so it can no longer be enriched in memory). A no-op when
+   * no row exists yet (the resolution won the race — {@link record} will carry the key) or the key is
+   * empty. Advisory, like the rest of the store — never keyed on for control flow.
+   */
+  setElementInstanceKey(jobKey: string, elementInstanceKey: string): void {
+    if (jobKey === "" || elementInstanceKey === "") return;
+    this.#db.run("UPDATE agentic_correlation SET element_instance_key = ? WHERE job_key = ?", [
+      elementInstanceKey,
+      jobKey,
+    ]);
+  }
+
   /** The durable attribution for a jobKey, or undefined when none was recorded. */
   get(jobKey: string): DurableCorrelation | undefined {
     if (jobKey === "") return undefined;
@@ -159,4 +198,19 @@ export class AgenticCorrelationStore {
     );
     return rows.map(fromRow);
   }
+
+  /**
+   * Every durable attribution recorded for an engine element-instance key (#544), newest completion
+   * first. This is the #544 read axis: unlike a static {@link DurableCorrelation.elementId}, an
+   * element-instance key names one specific occupancy, so a looping / retried activity's distinct
+   * iterations resolve to distinct rows here.
+   */
+  byElementInstance(elementInstanceKey: string): DurableCorrelation[] {
+    if (elementInstanceKey === "") return [];
+    const rows = this.#db.all<Row>(
+      "SELECT * FROM agentic_correlation WHERE element_instance_key = ? ORDER BY completed_at DESC, job_key DESC",
+      [elementInstanceKey],
+    );
+    return rows.map(fromRow);
+  }
 }

package/app/agentic/correlation.test.ts

@@ -42,6 +42,38 @@ test("link records context and both projections; resolve carries the job: stream
   assert.equal(reg.count(), 1);
 });
 
+test("attachElementInstance enriches a linked job's context, preserving every other field (#544)", () => {
+  const reg = new CorrelationRegistry();
+  reg.link("wk-a", "6494", { processInstanceKey: "4612", elementId: "agent", planKey: "o/r#142" });
+  reg.attachElementInstance("6494", "ei-77");
+  const c = reg.resolve("6494");
+  assert.ok(c);
+  assert.equal(c.elementInstanceKey, "ei-77");
+  // Enrichment is additive — it must not clobber the fields the link established.
+  assert.equal(c.processInstanceKey, "4612");
+  assert.equal(c.elementId, "agent");
+  assert.equal(c.planKey, "o/r#142");
+  assert.equal(c.jobKey, "6494");
+  assert.equal(c.stream, "job:6494");
+});
+
+test("attachElementInstance is a no-op for a released (or never-linked) job or an empty key (#544)", () => {
+  const reg = new CorrelationRegistry();
+  // Never linked.
+  reg.attachElementInstance("nope", "ei-1");
+  assert.equal(reg.resolve("nope"), undefined);
+  // Released before the resolution landed (the completion-race path).
+  reg.link("wk-a", "6494");
+  reg.releaseJob("6494");
+  reg.attachElementInstance("6494", "ei-1");
+  assert.equal(reg.resolve("6494"), undefined);
+  // Empty inputs are ignored, and never materialise a context.
+  reg.link("wk-b", "7000");
+  reg.attachElementInstance("7000", "");
+  assert.equal(reg.resolve("7000")?.elementInstanceKey, undefined);
+  reg.attachElementInstance("", "ei-1");
+});
+
 test("link ignores empty instance or jobKey", () => {
   const reg = new CorrelationRegistry();
   reg.link("", "6494");
@@ -70,6 +102,20 @@ test("re-linking a jobKey to a new instance MOVES it (drops the stale reverse ed
   assert.equal(reg.count(), 1);
 });
 
+test("re-linking a jobKey preserves an already-attached elementInstanceKey (no clobber)", () => {
+  const reg = new CorrelationRegistry();
+  reg.link("wk-a", "6494");
+  reg.attachElementInstance("6494", "ei-42");
+  // A subsequent bare re-link (worker reconnect mid-job) must not wipe the async-resolved key.
+  reg.link("wk-a", "6494");
+  assert.equal(reg.resolve("6494")?.elementInstanceKey, "ei-42");
+  // A move to a new worker connection likewise keeps the element-instance the job occupies.
+  reg.link("wk-b", "6494", { planKey: "o/r#7" });
+  assert.equal(reg.resolve("6494")?.elementInstanceKey, "ei-42");
+  assert.equal(reg.resolve("6494")?.planKey, "o/r#7");
+});
+
+
 test("releaseJob removes one job from both projections", () => {
   const reg = new CorrelationRegistry();
   reg.link("wk-a", "6494");

package/app/agentic/correlation.ts

@@ -55,6 +55,13 @@ export interface JobCorrelation {
   readonly bpmnProcessId?: string;
   /** The BPMN element id (activity/task) the job is for, if known. */
   readonly elementId?: string;
+  /**
+   * The engine element-instance key the job's token occupies (#544), if resolved. Unlike
+   * {@link elementId} (the static id, ambiguous across a looping / retried activity) this names the
+   * specific occupancy. Best-effort: it is enriched asynchronously via {@link CorrelationRegistry.attachElementInstance}
+   * after the link, so it may be absent for a just-linked job and stays absent if resolution never lands.
+   */
+  readonly elementInstanceKey?: string;
   /** The plan / epic key this job is part of (e.g. `owner/repo#142`), if known. */
   readonly planKey?: string;
   /** The relay stream id the job's terminal is relayed on (`job:<jobKey>`). */
@@ -86,8 +93,12 @@ export class CorrelationRegistry {
 
   /**
    * Link a worker instance to a job it is now processing, recording the job's engine context. A
-   * re-link of the same jobKey to a different instance moves it (dropping the old reverse edge); a
-   * re-link with fresh context overwrites the context (last write wins). Both args must be non-empty.
+   * re-link of the same jobKey to a different instance moves it (dropping the old reverse edge). The
+   * context is MERGED over any existing attribution, not replaced: explicitly provided fields win
+   * (last write wins per field), but fields omitted from `context` are preserved — so a bare re-link
+   * cannot clear or clobber context another path already attached (e.g. an async-resolved
+   * `elementInstanceKey`). `jobKey`/`stream` are always re-derived canonically. Both args must be
+   * non-empty.
    */
   link(instance: string, jobKey: string, context: JobContext = {}): void {
     if (instance === "" || jobKey === "") return;
@@ -100,7 +111,32 @@ export class CorrelationRegistry {
     const jobs = this.#jobsOf.get(instance) ?? new Set<string>();
     jobs.add(jobKey);
     this.#jobsOf.set(instance, jobs);
-    this.#context.set(jobKey, { jobKey, stream: jobStream(jobKey), ...stripUndefined(context) });
+    // Merge over any existing attribution rather than clobbering it: a jobKey is engine-unique, so a
+    // re-link (e.g. a worker reconnecting mid-job, or a richer orchestrator context arriving later)
+    // must not drop context another path already attached — notably the #544 `elementInstanceKey`,
+    // which is resolved asynchronously and could otherwise be wiped by a subsequent bare `link`.
+    // Explicitly provided fields still win; `jobKey`/`stream` are always re-derived canonically.
+    const existing = this.#context.get(jobKey);
+    this.#context.set(jobKey, {
+      ...existing,
+      jobKey,
+      stream: jobStream(jobKey),
+      ...stripUndefined(context),
+    });
+  }
+
+  /**
+   * Enrich a still-linked job's context with the engine element-instance key it occupies (#544),
+   * resolved asynchronously after the link (the element-instance read is an engine round-trip the
+   * synchronous link path cannot await). Best-effort and idempotent: a no-op if the job is no longer
+   * linked (it completed and released before resolution returned — the durable backfill covers that
+   * case instead) or if the key is empty. Preserves every other context field.
+   */
+  attachElementInstance(jobKey: string, elementInstanceKey: string): void {
+    if (jobKey === "" || elementInstanceKey === "") return;
+    const existing = this.#context.get(jobKey);
+    if (existing === undefined) return;
+    this.#context.set(jobKey, { ...existing, elementInstanceKey });
   }
 
   /** Release one job (it finished / moved on). No-op if it was never linked. */
@@ -170,11 +206,12 @@ export class CorrelationRegistry {
 
 /** Drop `undefined`-valued keys so the stored context never materializes an explicit `{ key: undefined }` hole. */
 function stripUndefined(context: JobContext): JobContext {
-  const { processInstanceKey, bpmnProcessId, elementId, planKey } = context;
+  const { processInstanceKey, bpmnProcessId, elementId, elementInstanceKey, planKey } = context;
   return {
     ...(processInstanceKey !== undefined ? { processInstanceKey } : {}),
     ...(bpmnProcessId !== undefined ? { bpmnProcessId } : {}),
     ...(elementId !== undefined ? { elementId } : {}),
+    ...(elementInstanceKey !== undefined ? { elementInstanceKey } : {}),
     ...(planKey !== undefined ? { planKey } : {}),
   };
 }

package/app/agentic/element-instance.test.ts

@@ -0,0 +1,111 @@
+// Acceptance test for the #544 element-instance resolver (app/agentic/element-instance.ts).
+//
+// The load-bearing case is the one the issue names: correlation must resolve the CORRECT element
+// instance across a RETRIED / LOOPING job — where the same static BPMN `elementId` occupies several
+// distinct element instances, each with its own jobKey. Keying on `elementId` would be ambiguous;
+// keying on `jobKey` (engine-unique per activation) is not. These tests drive the resolver against a
+// fake wait-state reader and assert each jobKey resolves to its own occupancy's `elementInstanceKey`.
+import { test } from "node:test";
+import type { ElementInstanceWaitState, ElementInstanceWaitStateFilter } from "@nanobpm/urban";
+import { assertEquals } from "#test-assert";
+import {
+  type ElementInstanceWaitStateReader,
+  resolveElementInstanceKey,
+} from "./element-instance.ts";
+
+/** A fake engine wait-state read model: returns the configured parks, honouring the filter. */
+function fakeReader(
+  parks: readonly ElementInstanceWaitState[],
+): ElementInstanceWaitStateReader & { calls: ElementInstanceWaitStateFilter[] } {
+  const calls: ElementInstanceWaitStateFilter[] = [];
+  return {
+    calls,
+    searchElementInstanceWaitStates: (filter: ElementInstanceWaitStateFilter = {}) => {
+      calls.push(filter);
+      const matched = parks.filter((p) => {
+        if (filter.waitStateType !== undefined && p.waitStateType !== filter.waitStateType) return false;
+        if (filter.processInstanceKey !== undefined && p.processInstanceKey !== filter.processInstanceKey) {
+          return false;
+        }
+        if (filter.elementId !== undefined && p.elementId !== filter.elementId) return false;
+        return true;
+      });
+      return Promise.resolve(matched);
+    },
+  };
+}
+
+/** Build a JOB wait-state park (a service task awaiting a worker). */
+function jobPark(over: {
+  elementInstanceKey: string;
+  jobKey: string;
+  processInstanceKey?: string;
+  elementId?: string;
+}): ElementInstanceWaitState {
+  return {
+    elementInstanceKey: over.elementInstanceKey,
+    processInstanceKey: over.processInstanceKey ?? "pi-1",
+    elementId: over.elementId ?? "agent",
+    waitStateType: "JOB",
+    jobType: "senior:feature",
+    jobKey: over.jobKey,
+  };
+}
+
+test("resolves the element instance whose JOB park carries the matching jobKey", async () => {
+  const reader = fakeReader([jobPark({ elementInstanceKey: "ei-100", jobKey: "job-abc" })]);
+  assertEquals(await resolveElementInstanceKey(reader, "job-abc"), "ei-100");
+});
+
+test("looping/retried job: same elementId across iterations resolves each jobKey to its own instance", async () => {
+  // Three live parks for the SAME static element `agent` in the SAME process instance — the shape a
+  // retried / looping activity produces: distinct element instances, distinct jobKeys, one elementId.
+  const reader = fakeReader([
+    jobPark({ elementInstanceKey: "ei-1", jobKey: "job-iter-1", elementId: "agent" }),
+    jobPark({ elementInstanceKey: "ei-2", jobKey: "job-iter-2", elementId: "agent" }),
+    jobPark({ elementInstanceKey: "ei-3", jobKey: "job-iter-3", elementId: "agent" }),
+  ]);
+
+  // Keying on elementId would be ambiguous (all three share `agent`); keying on jobKey is exact.
+  assertEquals(await resolveElementInstanceKey(reader, "job-iter-1"), "ei-1");
+  assertEquals(await resolveElementInstanceKey(reader, "job-iter-2"), "ei-2");
+  assertEquals(await resolveElementInstanceKey(reader, "job-iter-3"), "ei-3");
+});
+
+test("scopes the engine search to JOB parks, and to the process instance when known", async () => {
+  const reader = fakeReader([
+    jobPark({ elementInstanceKey: "ei-a", jobKey: "job-a", processInstanceKey: "pi-1" }),
+    jobPark({ elementInstanceKey: "ei-b", jobKey: "job-b", processInstanceKey: "pi-2" }),
+  ]);
+  assertEquals(await resolveElementInstanceKey(reader, "job-b", { processInstanceKey: "pi-2" }), "ei-b");
+  assertEquals(reader.calls.length, 1);
+  assertEquals(reader.calls[0].waitStateType, "JOB");
+  assertEquals(reader.calls[0].processInstanceKey, "pi-2");
+});
+
+test("unscoped resolution still matches on jobKey across process instances", async () => {
+  const reader = fakeReader([
+    jobPark({ elementInstanceKey: "ei-a", jobKey: "job-a", processInstanceKey: "pi-1" }),
+    jobPark({ elementInstanceKey: "ei-b", jobKey: "job-b", processInstanceKey: "pi-2" }),
+  ]);
+  assertEquals(await resolveElementInstanceKey(reader, "job-b"), "ei-b");
+  assertEquals(reader.calls[0].processInstanceKey, undefined);
+});
+
+test("returns undefined when the job is not parked (completed / released) or jobKey is empty", async () => {
+  const reader = fakeReader([jobPark({ elementInstanceKey: "ei-1", jobKey: "job-live" })]);
+  assertEquals(await resolveElementInstanceKey(reader, "job-gone"), undefined);
+  assertEquals(await resolveElementInstanceKey(reader, ""), undefined);
+});
+
+test("ignores a non-JOB park that happens to share the process instance", async () => {
+  const parks: ElementInstanceWaitState[] = [
+    { elementInstanceKey: "ei-msg", processInstanceKey: "pi-1", elementId: "wait", waitStateType: "MESSAGE", messageName: "m" },
+    jobPark({ elementInstanceKey: "ei-job", jobKey: "job-x", processInstanceKey: "pi-1" }),
+  ];
+  // Even if the engine ignored the JOB filter, only the JOB park's jobKey can match.
+  const reader: ElementInstanceWaitStateReader = {
+    searchElementInstanceWaitStates: () => Promise.resolve(parks),
+  };
+  assertEquals(await resolveElementInstanceKey(reader, "job-x"), "ei-job");
+});

package/app/agentic/element-instance.ts

@@ -0,0 +1,97 @@
+// nano-workforce — resolve an agent job's ENGINE ELEMENT-INSTANCE KEY from its jobKey (#544).
+//
+// The durable correlation store (`./correlation-store.ts`) has historically keyed an agent session's
+// engine context on the STATIC BPMN `element_id`. That id is ambiguous across a looping / retried
+// activity: every re-activation of the same task id is a DISTINCT element instance sharing one id, so
+// a transcript keyed on `element_id` alone cannot say WHICH occupancy produced it. #544 keys on the
+// engine's per-occupancy handle instead — the `elementInstanceKey` — which is exactly what Nano
+// Explorer addresses runtime position by and what Camunda keys its agent model on.
+//
+// The engine does not offer a `getJob(jobKey)` lookup, but it DOES surface every parked element
+// instance via the element-instance wait-state read (`POST /v2/element-instances/wait-states/search`,
+// bound onto the `@nanobpm/urban` EngineClient by nano-ide#473). A service task awaiting a worker is a
+// `JOB` park, and that park carries BOTH its `jobKey` AND its owning `elementInstanceKey`. So the join
+// is: list the live JOB parks, find the one whose `jobKey` matches the agent job, and read off its
+// `elementInstanceKey`. Because a park is keyed to a specific element instance, this is unambiguous
+// even when many iterations of the same static element are (or have been) live — each iteration is a
+// separate park with a separate jobKey (see the looping/retried-job test).
+//
+// Invariant fit (ADR 0056): this is an ADVISORY, READ-ONLY engine query — it observes the engine's
+// read model to enrich a visibility record. It NEVER activates/completes a job, publishes a message,
+// or gates a BPMN sequence flow; the Camunda-8 job protocol (worker⇄engine) is untouched. It is
+// deliberately expressed against a narrow reader shape (not the whole EngineClient) so the callers
+// that drive it stay structurally decoupled from the engine.
+import type { ElementInstanceWaitState, ElementInstanceWaitStateFilter } from "@nanobpm/urban";
+
+/**
+ * The narrow slice of the engine read model this resolver needs: the element-instance wait-state
+ * search. `@nanobpm/urban`'s `EngineClient` satisfies it structurally; a test supplies a fake.
+ */
+export interface ElementInstanceWaitStateReader {
+  searchElementInstanceWaitStates(
+    filter?: ElementInstanceWaitStateFilter,
+  ): Promise<readonly ElementInstanceWaitState[]>;
+}
+
+/** Optional scoping for {@link resolveElementInstanceKey} (a performance narrowing, never required). */
+export interface ResolveElementInstanceOptions {
+  /**
+   * The owning process instance, when the caller already knows it. Passed to the engine as a search
+   * filter so the read is scoped to one process instance rather than every live JOB park. It is a pure
+   * OPTIMISATION: the `jobKey` is the match key and is engine-unique, so an unscoped search resolves
+   * the same element instance — just over a larger candidate set.
+   */
+  readonly processInstanceKey?: string;
+}
+
+/**
+ * Resolve the `elementInstanceKey` the agent job identified by `jobKey` occupies, by matching the
+ * job against the engine's live `JOB` wait-state parks. Returns `undefined` when the job is not (or no
+ * longer) parked — e.g. it already completed and released its park, or the jobKey is empty — which the
+ * advisory callers treat as "not resolved", never an error.
+ *
+ * The resolution keys on `jobKey`, NOT `elementId`: that is the whole point of #544. A retried /
+ * looping activity has many parks sharing one `elementId` but each with its own `jobKey` and its own
+ * `elementInstanceKey`, so matching on `jobKey` returns the correct per-occupancy instance.
+ */
+export async function resolveElementInstanceKey(
+  reader: ElementInstanceWaitStateReader,
+  jobKey: string,
+  options: ResolveElementInstanceOptions = {},
+): Promise<string | undefined> {
+  if (jobKey === "") return undefined;
+  const filter: ElementInstanceWaitStateFilter = { waitStateType: "JOB" };
+  if (options.processInstanceKey !== undefined && options.processInstanceKey !== "") {
+    filter.processInstanceKey = options.processInstanceKey;
+  }
+  const parks = await reader.searchElementInstanceWaitStates(filter);
+  for (const park of parks) {
+    // Narrow to the JOB variant (the discriminant guards `jobKey`); a non-JOB park never carries the
+    // jobKey field even if the engine ignored the filter. Match on the engine-unique jobKey.
+    if (park.waitStateType === "JOB" && park.jobKey === jobKey) {
+      return park.elementInstanceKey;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The narrow, advisory element-instance resolution seam the relay slice fires at link time (#544):
+ * given an agent `jobKey` (and its owning `processInstanceKey` when known), resolve the engine
+ * element-instance key it occupies, or `undefined` when it is not resolvable. A function shape — NOT
+ * an `EngineClient` — so the agentic families depend on a capability, not the engine itself; the
+ * composition root ({@link file://main.ts}) closes it over the real engine, a test over a fake.
+ */
+export type ElementInstanceResolver = (
+  jobKey: string,
+  processInstanceKey?: string,
+) => Promise<string | undefined>;
+
+/**
+ * Build an {@link ElementInstanceResolver} bound to an engine wait-state reader — the closure the
+ * composition root threads into the agentic channel so the relay slice can resolve an agent job's
+ * element instance without holding an engine reference of its own.
+ */
+export function makeElementInstanceResolver(reader: ElementInstanceWaitStateReader): ElementInstanceResolver {
+  return (jobKey, processInstanceKey) => resolveElementInstanceKey(reader, jobKey, { processInstanceKey });
+}

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

@@ -134,6 +134,12 @@ function mkService(registry: ConnectionRegistry, db: SqliteDb | undefined): {
   return { service, hub };
 }
 
+/** Flush the microtask/macrotask queue so a fire-and-forget promise chain (the async #544 element-
+ * instance resolution) settles before the test asserts on its effects. */
+function tick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
 /** Build a service with the H6 correlation write-side wired (a real registry + a connection→instance map). */
 function mkCorrelatedService(
   registry: ConnectionRegistry,
@@ -143,6 +149,7 @@ function mkCorrelatedService(
   extra: {
     attributionForInstance?: (instance: string) => { identity?: string; host?: string } | undefined;
     correlationStore?: AgenticCorrelationStore;
+    resolveElementInstance?: (jobKey: string, processInstanceKey?: string) => Promise<string | undefined>;
     now?: () => string;
   } = {},
 ): { service: RelayTranscriptService; hub: CapturingHub } {
@@ -156,6 +163,7 @@ function mkCorrelatedService(
     instanceForConnection: (id) => byConnection.get(id),
     attributionForInstance: extra.attributionForInstance,
     correlationStore: extra.correlationStore,
+    resolveElementInstance: extra.resolveElementInstance,
     now: extra.now,
   });
   return { service, hub };
@@ -452,6 +460,88 @@ test("H6 durable attribution: completing/superseding a job persists the worker's
   service.teardown();
 });
 
+test("#544 element-instance enrichment: link-time resolution keys the completed session on the element instance", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const db = memoryDb();
+  const store = new AgenticCorrelationStore(db);
+  const byConnection = new Map([["prod", "worker-A"]]);
+  // The engine resolves job k1's live JOB park to element instance ei-1 (resolution wins the race,
+  // i.e. it returns while the job is still live — the common case for a long-lived agent job).
+  const resolveElementInstance = (jobKey: string) =>
+    Promise.resolve(jobKey === "k1" ? "ei-1" : undefined);
+  const { service, hub } = mkCorrelatedService(registry, db, correlation, byConnection, {
+    correlationStore: store,
+    resolveElementInstance,
+    now: () => "2024-01-02T03:04:05.000Z",
+  });
+  const p = connect("prod", registry);
+
+  // First produce links the job and fires the (async) element-instance resolution.
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  await tick();
+  // The live correlation context is enriched while the job runs.
+  assertEquals(correlation.resolve("k1")?.elementInstanceKey, "ei-1", "the live context carries the element instance");
+
+  // Superseding with a new job completes k1 → its attribution persists WITH the element-instance key.
+  hub.handler?.(produce(jobStream("k2"), 1, "job-2 line"), p.conn);
+  const durable = store.get("k1");
+  assertEquals(durable?.elementInstanceKey, "ei-1", "the completed session is keyed on the element instance");
+  service.teardown();
+});
+
+test("#544 element-instance enrichment: a resolution that lands AFTER completion backfills the durable row", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const db = memoryDb();
+  const store = new AgenticCorrelationStore(db);
+  const byConnection = new Map([["prod", "worker-A"]]);
+  // A deferred resolution the test releases MANUALLY, to force the race where the element-instance
+  // key arrives only after the job already completed and released its live correlation.
+  let release: (key: string | undefined) => void = () => {};
+  const pending = new Promise<string | undefined>((resolve) => {
+    release = resolve;
+  });
+  const { service, hub } = mkCorrelatedService(registry, db, correlation, byConnection, {
+    correlationStore: store,
+    resolveElementInstance: () => pending,
+  });
+  const p = connect("prod", registry);
+
+  // Link job k1 (fires the still-pending resolution), then supersede it → k1 completes and persists
+  // its attribution BEFORE the element instance is known.
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  hub.handler?.(produce(jobStream("k2"), 1, "job-2 line"), p.conn);
+  assertEquals(store.get("k1")?.elementInstanceKey, undefined, "persisted before the element instance resolved");
+  assertEquals(correlation.resolve("k1"), undefined, "k1's live correlation was already released");
+
+  // The resolution finally lands — it backfills the durable row directly (the live context is gone).
+  release("ei-late");
+  await tick();
+  assertEquals(store.get("k1")?.elementInstanceKey, "ei-late", "the durable row is backfilled after the fact");
+  service.teardown();
+});
+
+test("#544 element-instance enrichment: an unresolved job (never parked) leaves the session un-keyed, not erroring", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const db = memoryDb();
+  const store = new AgenticCorrelationStore(db);
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, db, correlation, byConnection, {
+    correlationStore: store,
+    resolveElementInstance: () => Promise.resolve(undefined),
+  });
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  await tick();
+  hub.handler?.(produce(jobStream("k2"), 1, "job-2 line"), p.conn);
+  const durable = store.get("k1");
+  assert(durable !== undefined, "the session is still attributed");
+  assertEquals(durable?.elementInstanceKey, undefined, "no element-instance key when the job was not resolvable");
+  service.teardown();
+});
+
 /**
  * A {@link CorrelationLink} wrapper that delegates to a real registry but can be flipped to throw on
  * `link()`/`releaseJob()`, exercising the advisory-resilience contract: `#link`/`#unlink` are

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

@@ -35,6 +35,7 @@ import {
 import type { Logger } from "@nanobpm/urban";
 import { currentCorrelation, type JobContext, type JobCorrelation, jobKeyOfStream } from "../correlation.ts";
 import { AgenticCorrelationStore } from "../correlation-store.ts";
+import type { ElementInstanceResolver } from "../element-instance.ts";
 import type { AgenticContext, AgenticFamily } from "../registry.ts";
 import { currentPresenceRegistry } from "./presence.family.ts";
 
@@ -105,6 +106,13 @@ interface StreamState {
    * instance's prior job stream.
    */
   instance?: string;
+  /**
+   * The engine element-instance key this `job:<jobKey>` 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.
+   */
+  elementInstanceKey?: string;
 }
 
 /**
@@ -115,6 +123,12 @@ interface StreamState {
 export interface CorrelationLink {
   link(instance: string, jobKey: string, context?: JobContext): void;
   releaseJob(jobKey: string): void;
+  /**
+   * Enrich a still-linked job's context with the engine element-instance key it occupies (#544),
+   * resolved asynchronously after the link. Optional so the minimal double in tests need not implement
+   * it; the real {@link CorrelationRegistry} does. A no-op once the job is released.
+   */
+  attachElementInstance?(jobKey: string, elementInstanceKey: string): void;
   /**
    * The (still-live) engine context for a jobKey, when the write-side exposes it. Optional so the
    * minimal double in tests need not implement it; the real {@link CorrelationRegistry} does, and the
@@ -178,6 +192,15 @@ export interface RelayTranscriptServiceOptions {
    * no durable attribution). Injectable so a test can supply an in-memory store.
    */
   readonly correlationStore?: AgenticCorrelationStore;
+  /**
+   * Resolve the engine element-instance key a `job:<jobKey>` 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.
+   * Advisory and READ-ONLY — never awaited in a frame handler, never gates a flow. {@link createRelayFamily}
+   * wires it to the channel's {@link AgenticContext.resolveElementInstance}; omitted → no enrichment.
+   */
+  readonly resolveElementInstance?: ElementInstanceResolver;
   /** "Now" as an ISO-8601 instant, injectable for deterministic completion timestamps. */
   readonly now?: () => string;
 }
@@ -226,6 +249,8 @@ export class RelayTranscriptService {
   readonly #attributionForInstance: (instance: string) => WorkerAttribution | undefined;
   /** The durable worker-attribution store, or undefined when unpersisted (#485). */
   readonly #correlationStore: AgenticCorrelationStore | undefined;
+  /** Resolve the engine element-instance key a job occupies (#544), or undefined when not wired. */
+  readonly #resolveElementInstance: ElementInstanceResolver | undefined;
   /** "Now" as an ISO-8601 instant (injectable for deterministic tests). */
   readonly #now: () => string;
 
@@ -235,6 +260,7 @@ export class RelayTranscriptService {
     this.#correlation = options.correlation ?? currentCorrelation;
     this.#instanceForConnection = options.instanceForConnection ?? (() => undefined);
     this.#attributionForInstance = options.attributionForInstance ?? (() => undefined);
+    this.#resolveElementInstance = options.resolveElementInstance;
     this.#now = options.now ?? (() => new Date().toISOString());
     // Persistence is advisory: a store that can't be constructed or whose schema can't be applied
     // (locked/permission-denied/unavailable SQLite) must NOT fail the family mount — fall back to
@@ -448,6 +474,10 @@ export class RelayTranscriptService {
       state.linked = true;
       state.instance = instance;
       this.#jobStreamByInstance.set(instance, stream);
+      // #544: resolve the element INSTANCE this job occupies while its JOB park is still live (the
+      // park is gone once the job completes, so this must fire at link time, not completion time).
+      // Advisory and asynchronous — fire-and-forget so it never blocks the synchronous frame handler.
+      this.#enrichElementInstance(stream, jobKey, state);
     } catch (err) {
       // Advisory — never throws into the frame handler. Swallow a throwing injectable correlation and
       // leave the stream UNLINKED so a later `produce` retries the link.
@@ -459,6 +489,51 @@ export class RelayTranscriptService {
     }
   }
 
+  /**
+   * #544: asynchronously resolve the engine element-instance key this job occupies and record it, from
+   * the first `produce` while the JOB park is still live. Fire-and-forget: it is invoked from the
+   * synchronous frame handler but never awaited, and every failure is swallowed (advisory). On success
+   * it enriches BOTH the live correlation context (so a still-running job's reads see it) AND stashes
+   * it on the stream state (so completion persists it); it ALSO backfills the durable row directly, to
+   * cover the race where resolution returns AFTER the job completed and released its live correlation.
+   */
+  #enrichElementInstance(stream: string, jobKey: string, state: StreamState): void {
+    const resolve = this.#resolveElementInstance;
+    if (resolve === undefined) return;
+    const processInstanceKey = this.#correlation()?.resolve?.(jobKey)?.processInstanceKey;
+    // Self-contained advisory: a synchronous throw (a misbehaving resolver) is swallowed here rather
+    // than surfacing in `#link`'s catch as a misleading "link failed", and the async rejection path is
+    // handled by `.catch`. Either way this never throws into the synchronous frame handler.
+    let pending: Promise<string | undefined>;
+    try {
+      pending = resolve(jobKey, processInstanceKey);
+    } catch (err) {
+      this.#log.warn("agentic relay element-instance resolution failed — session left un-keyed", {
+        stream,
+        jobKey,
+        err: String(err),
+      });
+      return;
+    }
+    void pending
+      .then((elementInstanceKey) => {
+        if (elementInstanceKey === undefined || elementInstanceKey === "") return;
+        state.elementInstanceKey = elementInstanceKey;
+        // Enrich the live context if still linked (a no-op once released), and backfill the durable
+        // row if it was already persisted (a no-op before completion) — the two are complementary, so
+        // exactly one lands depending on whether resolution beat completion.
+        this.#correlation()?.attachElementInstance?.(jobKey, elementInstanceKey);
+        this.#correlationStore?.setElementInstanceKey(jobKey, elementInstanceKey);
+      })
+      .catch((err: unknown) => {
+        this.#log.warn("agentic relay element-instance resolution failed — session left un-keyed", {
+          stream,
+          jobKey,
+          err: String(err),
+        });
+      });
+  }
+
   /** H6 write-side (#149): release a `job:<jobKey>` stream's correlation on completion / disconnect. */
   #unlink(stream: string, state: StreamState): void {
     if (!state.linked) return;
@@ -505,6 +580,10 @@ export class RelayTranscriptService {
     try {
       const attribution = this.#attributionForInstance(instance) ?? {};
       const context = this.#correlation()?.resolve?.(jobKey);
+      // #544: prefer the live context's element-instance key; fall back to the stream state (the
+      // resolution may have landed after the context was released, or the context write-side may not
+      // carry it). Either source is the same resolved value.
+      const elementInstanceKey = context?.elementInstanceKey ?? state.elementInstanceKey;
       store.record({
         jobKey,
         stream,
@@ -516,6 +595,7 @@ export class RelayTranscriptService {
         ...(context?.bpmnProcessId !== undefined ? { bpmnProcessId: context.bpmnProcessId } : {}),
         ...(context?.elementId !== undefined ? { elementId: context.elementId } : {}),
         ...(context?.planKey !== undefined ? { planKey: context.planKey } : {}),
+        ...(elementInstanceKey !== undefined ? { elementInstanceKey } : {}),
       });
     } catch (err) {
       this.#log.warn("agentic correlation attribution persist failed — past session left unattributed", {
@@ -618,6 +698,10 @@ export function createRelayFamily(options: {
         // records instance only.
         attributionForInstance: (instance) => currentPresenceRegistry()?.attributionOf(instance),
         correlation: currentCorrelation,
+        // #544: the advisory element-instance resolver the composition root closed over the engine.
+        // Absent (engine-less host, or a test that mounts without it) → sessions are keyed on the
+        // static element id only, exactly as before this slice.
+        resolveElementInstance: ctx.resolveElementInstance,
       });
       setCurrentRelayTranscriptService(service);
 

package/app/agentic/registry.ts

@@ -23,11 +23,16 @@
 //   - `db/migrations/024_agentic_transcript.sql` → H3 (#146)
 //   - `db/migrations/025_agentic_blackboard.sql` → H4 (#147), only if it needs a schema change
 //
-// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
-// is untouched — the agentic channel is the only new conversation; advisory semantics are preserved
-// (a family NEVER hard-locks or gates a BPMN sequence flow).
+// Invariants (ADR 0056): app-tier only — a family NEVER participates in or gates the Camunda-8 job
+// protocol (worker⇄engine): it does not activate/complete jobs, publish messages, or gate a BPMN
+// sequence flow; the agentic channel is the only new conversation, and its semantics are advisory. An
+// ADVISORY, READ-ONLY query against the engine's read model (e.g. resolving the element instance a job
+// occupies, #544) is permitted — it observes state to enrich a visibility record, never drives it — and
+// is offered to families as the narrow {@link AgenticContext.resolveElementInstance} seam so a family
+// depends on a capability, not the engine handle.
 import type { AgenticHub, ConnectionRegistry, WebSocketChannelTransport } from "@nanobpm/agentic/channel";
 import type { DataLayer, Logger } from "@nanobpm/urban";
+import type { ElementInstanceResolver } from "./element-instance.ts";
 
 /**
  * The reusable handle the seam threads to every family module at mount time. A sibling family uses
@@ -43,6 +48,15 @@ export interface AgenticContext {
   readonly transport: WebSocketChannelTransport;
   /** The app's SQLite data layer — the same store the advisory blackboard uses (may be absent). */
   readonly data: DataLayer | undefined;
+  /**
+   * An ADVISORY, READ-ONLY element-instance resolver (#544), when the composition root supplies one.
+   * A family may call it to enrich a visibility record with the engine element-instance key a job
+   * occupies. It is a narrow function shape (not an engine handle) closed over the engine's element-
+   * instance wait-state read — so a family can query the engine's READ MODEL for advisory enrichment
+   * WITHOUT participating in or gating the Camunda-8 job protocol (the invariant above forbids the
+   * latter, not the former). Absent when no engine is wired (tests, engine-less hosts).
+   */
+  readonly resolveElementInstance?: ElementInstanceResolver;
   /** A structured logger for boot/shutdown lifecycle lines. */
   readonly log: Logger;
 }

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

@@ -9,6 +9,7 @@ import { DatabaseSync } from "node:sqlite";
 import type { SqliteDb, TranscriptRing, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
 import { assert, assertEquals } from "#test-assert";
 import { AgenticCorrelationStore } from "./correlation-store.ts";
+import { CorrelationRegistry } from "./correlation.ts";
 import { correlationFieldsFor, listTranscripts, readTranscriptFrom } from "./transcript-read.ts";
 
 /** A read-only TranscriptStore double: list() returns the seeded metas; read() has no retained chunks. */
@@ -107,6 +108,32 @@ test("durable fallback: a released (past) job is attributed from the durable sto
   assertEquals(fields.planKey, "acme/repo#42");
 });
 
+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 });
+
+  // The key surfaces on the correlation fields (durable fallback, live registry empty).
+  assertEquals(correlationFieldsFor("job:k1", undefined, durable).elementInstanceKey, "ei-1");
+
+  const store = fakeStore([meta("job:k1", early), meta("job: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[0].elementInstanceKey, "ei-2", "the projection carries the element-instance key");
+});
+
+test("#544: the live correlation's element-instance key takes precedence over the durable row on read", () => {
+  const registry = new CorrelationRegistry();
+  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 });
+
+  assertEquals(correlationFieldsFor("job: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 durable = new AgenticCorrelationStore(memoryStore());

package/app/agentic/transcript-read.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);
@@ -225,6 +235,7 @@ export function readTranscriptFrom(
   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/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/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.140.0",
+  "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": {