@nanobpm/nano-workforce 0.139.4 → 0.141.0

package/CHANGELOG.md

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

package/app/agentic/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");
+});