@nanobpm/nano-workforce 0.183.0 → 0.183.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.183.2](https://github.com/nanobpm/nano-workforce/compare/v0.183.1...v0.183.2) (2026-09-07)
+
+### Bug Fixes
+
+* **cockpit:** read transcripts on instance-scoped composeStreamId stream, not job:<jobKey> ([#754](https://github.com/nanobpm/nano-workforce/issues/754)) ([03fabb5](https://github.com/nanobpm/nano-workforce/commit/03fabb57c79c25ac0334bc0bd4a672348e5e507c)), closes [c8ctl-plugin-nano#186](https://github.com/nanobpm/c8ctl-plugin-nano/issues/186) [nano-ide#557](https://github.com/nanobpm/nano-ide/issues/557) [#543](https://github.com/nanobpm/nano-workforce/issues/543) [#738](https://github.com/nanobpm/nano-workforce/issues/738) [#738](https://github.com/nanobpm/nano-workforce/issues/738) [#738](https://github.com/nanobpm/nano-workforce/issues/738) [#543](https://github.com/nanobpm/nano-workforce/issues/543)
+
+## [0.183.1](https://github.com/nanobpm/nano-workforce/compare/v0.183.0...v0.183.1) (2026-09-07)
+
+### Bug Fixes
+
+* **reconcile:** cross-check engine truth before orphaning a vanished instance ([#753](https://github.com/nanobpm/nano-workforce/issues/753)) ([a363fdb](https://github.com/nanobpm/nano-workforce/commit/a363fdbec1fd14641f2c4a2ef2718034a11a1e92)), closes [#630](https://github.com/nanobpm/nano-workforce/issues/630) [#736](https://github.com/nanobpm/nano-workforce/issues/736) [#736](https://github.com/nanobpm/nano-workforce/issues/736) [#736](https://github.com/nanobpm/nano-workforce/issues/736)
+
 ## [0.183.0](https://github.com/nanobpm/nano-workforce/compare/v0.182.3...v0.183.0) (2026-09-07)
 
 ### Features

package/app/agentic/claim-registry.test.ts

@@ -9,6 +9,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
+import { composeStreamId } from "@nanobpm/agentic/emit";
 import {
   ClaimRegistry,
   currentClaimRegistry,
@@ -22,7 +23,7 @@ test("claim records both projections; jobKeysFor and primaryStreamFor resolve ag
   assert.deepEqual(reg.jobKeysFor("wk-a"), ["8420"]);
   assert.equal(reg.ownerOf("8420"), "wk-a");
   assert.equal(reg.isClaimed("8420"), true);
-  assert.equal(reg.primaryStreamFor("wk-a"), "job:8420");
+  assert.equal(reg.primaryStreamFor("wk-a"), composeStreamId("wk-a", "8420"));
   assert.equal(reg.count(), 1);
 });
 
@@ -62,7 +63,7 @@ test("a worker can hold several claims; jobKeysFor is sorted and primaryStreamFo
   reg.claim("wk-a", "8419");
   reg.claim("wk-a", "8421");
   assert.deepEqual(reg.jobKeysFor("wk-a"), ["8419", "8420", "8421"]);
-  assert.equal(reg.primaryStreamFor("wk-a"), "job:8419");
+  assert.equal(reg.primaryStreamFor("wk-a"), composeStreamId("wk-a", "8419"));
 });
 
 test("release clears one claim; a late / duplicate release is a no-op", () => {

package/app/agentic/claim-registry.ts

@@ -25,7 +25,7 @@
 // type on the job protocol; ADVISORY — the registry is a read-only visibility source and NEVER
 // hard-locks or gates a BPMN sequence flow.
 
-import { jobStream } from "./correlation.ts";
+import { composeStreamId } from "@nanobpm/agentic/emit";
 
 /** One ownership record: a worker instance's claim over a job. */
 export interface Claim {
@@ -138,14 +138,16 @@ export class ClaimRegistry {
 
   /**
    * The jobKey-scoped relay stream a worker's terminal should drill into: its lowest-sorted current
-   * claim's stream (`job:<jobKey>`). A worker runs one job at a time in this fleet, but sorting keeps
-   * it stable if it ever holds several. Undefined when the worker holds no claim — the caller then
-   * falls back to the instance-keyed stream. This is the "relay demoted to drill-in, keyed by the
-   * CLAIM (not by `instanceForConnection`)" seam.
+   * claim's stream (`composeStreamId(instance, jobKey)`). A worker runs one job at a time in this
+   * fleet, but sorting keeps it stable if it ever holds several. Undefined when the worker holds no
+   * claim — the caller then falls back to the instance-keyed stream. This is the "relay demoted to
+   * drill-in, keyed by the CLAIM (not by `instanceForConnection`)" seam. The instance-scoped stream id
+   * is the one canonical `@nanobpm/agentic/emit` codec the producer writes under (issue #738), so the
+   * cockpit drills the SAME stream the transcript bytes actually land on.
    */
   primaryStreamFor(instance: string): string | undefined {
     const [first] = this.jobKeysFor(instance);
-    return first === undefined ? undefined : jobStream(first);
+    return first === undefined ? undefined : composeStreamId(instance, first);
   }
 
   /** Whether any instance currently owns `jobKey`. */

package/app/agentic/cockpit/supply-view.ts

@@ -53,7 +53,7 @@ export interface SupplyLeafReport {
 export interface SupplyCorrelationReport {
   /** The Camunda-8 job key. */
   readonly jobKey: string;
-  /** The relay stream the job's terminal is on (`job:<jobKey>`). */
+  /** The relay stream the job's terminal is on (`composeStreamId(instance, jobKey)`, issue #738). */
   readonly stream: string;
   /** The owning process instance key, if known. */
   readonly processInstanceKey?: string;
@@ -113,8 +113,8 @@ export interface SupplyWorkerView {
   readonly jobs: number;
   /**
    * Whether this worker has a LIVE terminal to drill into. True only while it holds a current job:
-   * a worker relays its terminal on the jobKey-scoped `job:<jobKey>` stream, and the supply endpoint
-   * repoints {@link stream} at it. An IDLE worker (no jobs) has its `stream` default back to the bare
+   * a worker relays its terminal on the instance-scoped `composeStreamId(instance, jobKey)` stream
+   * (issue #738), and the supply endpoint repoints {@link stream} at it. An IDLE worker (no jobs) has its `stream` default back to the bare
    * instance id — a stream NO producer ever writes to — so drilling it opens a permanently blank
    * "live" terminal. The renderer suppresses the drill affordance when this is false.
    */

package/app/agentic/cockpit/transcript-view.ts

@@ -41,7 +41,7 @@ export interface TranscriptListReport {
 
 /** One past-session row in the renderable history view. */
 export interface TranscriptView {
-  /** The relay stream id to replay (`job:<jobKey>` for a job stream). */
+  /** The relay stream id to replay (`composeStreamId(instance, jobKey)` for a job stream, issue #738). */
   readonly stream: string;
   /** A single stable human label for the session's process instance / plan (falls back to the stream). */
   readonly label: string;

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

@@ -10,9 +10,13 @@ import { test } from "node:test";
 import { fileURLToPath } from "node:url";
 import type { SqliteDb } from "@nanobpm/agentic/transcript";
 import { assert, assertEquals } from "#test-assert";
-import { jobStream } from "./correlation.ts";
+import { composeStreamId } from "@nanobpm/agentic/emit";
 import { AGENTIC_CORRELATION_SCHEMA_SQL, AgenticCorrelationStore } from "./correlation-store.ts";
 
+/** The instance-scoped transcript stream id a job's terminal is stored under (issue #738). The
+ *  worker instance is fixed here — `byStream` only recovers the jobKey (the stream part) from it. */
+const st = (jobKey: string): string => composeStreamId("worker-A", jobKey);
+
 const HERE = dirname(fileURLToPath(import.meta.url));
 
 function memoryDb(): SqliteDb {
@@ -85,7 +89,7 @@ test("record + get round-trips full attribution, and byStream decodes the jobKey
   const store = new AgenticCorrelationStore(memoryDb());
   store.record({
     jobKey: "job-1",
-    stream: jobStream("job-1"),
+    stream: st("job-1"),
     instance: "worker-A",
     identity: "leaf:token",
     host: "merlin.local",
@@ -105,7 +109,7 @@ test("record + get round-trips full attribution, and byStream decodes the jobKey
   assertEquals(got?.planKey, "owner/repo#142");
   assertEquals(got?.completedAt, "2026-08-23T00:05:00.000Z");
   // The same row is reachable from the stream id.
-  assertEquals(store.byStream(jobStream("job-1"))?.instance, "worker-A");
+  assertEquals(store.byStream(st("job-1"))?.instance, "worker-A");
 });
 
 test("byElementInstance keys per-occupancy, distinguishing a looping/retried activity's iterations", () => {
@@ -115,7 +119,7 @@ test("byElementInstance keys per-occupancy, distinguishing a looping/retried act
   // 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"),
+    stream: st("job-iter-1"),
     instance: "worker-A",
     processInstanceKey: "pi-9",
     elementId: "agent",
@@ -124,7 +128,7 @@ test("byElementInstance keys per-occupancy, distinguishing a looping/retried act
   });
   store.record({
     jobKey: "job-iter-2",
-    stream: jobStream("job-iter-2"),
+    stream: st("job-iter-2"),
     instance: "worker-A",
     processInstanceKey: "pi-9",
     elementId: "agent",
@@ -147,7 +151,7 @@ test("optional context columns are omitted (not null) when unknown", () => {
   const store = new AgenticCorrelationStore(memoryDb());
   store.record({
     jobKey: "job-2",
-    stream: jobStream("job-2"),
+    stream: st("job-2"),
     instance: "worker-B",
     completedAt: "2026-08-23T01:00:00.000Z",
   });
@@ -159,7 +163,7 @@ test("optional context columns are omitted (not null) when unknown", () => {
 
 test("record is an upsert: re-recording a jobKey is last-write-wins", () => {
   const store = new AgenticCorrelationStore(memoryDb());
-  const base = { jobKey: "job-3", stream: jobStream("job-3"), completedAt: "2026-08-23T02:00:00.000Z" };
+  const base = { jobKey: "job-3", stream: st("job-3"), completedAt: "2026-08-23T02:00:00.000Z" };
   store.record({ ...base, instance: "worker-C" });
   store.record({ ...base, instance: "worker-C", host: "second.local", completedAt: "2026-08-23T02:10:00.000Z" });
   const got = store.get("job-3");
@@ -169,7 +173,7 @@ test("record is an upsert: re-recording a jobKey is last-write-wins", () => {
 
 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" };
+  const base = { jobKey: "job-4", stream: st("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.
@@ -178,9 +182,9 @@ test("record preserves an existing element_instance_key when a later re-record o
   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.record({ jobKey: "job-5", stream: st("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" });
+  store.record({ jobKey: "job-5", stream: st("job-5"), completedAt: "2026-08-23T03:05:00.000Z", instance: "worker-E" });
   assertEquals(store.get("job-5")?.elementInstanceKey, "ei-888");
 });
 

package/app/agentic/correlation-store.ts

@@ -19,8 +19,9 @@
 // `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 { parseStreamId } from "@nanobpm/agentic/emit";
 import type { SqliteDb } from "@nanobpm/agentic/transcript";
-import { jobKeyOfStream } from "./correlation.ts";
 
 /**
  * The canonical DDL for the durable correlation table. The `078_*` + `086_*` migrations reproduce this
@@ -183,9 +184,9 @@ export class AgenticCorrelationStore {
     return rows.length > 0 ? fromRow(rows[0]) : undefined;
   }
 
-  /** The durable attribution for a `job:<jobKey>` stream id, or undefined for a non-job stream. */
+  /** The durable attribution for an instance-scoped job stream id, or undefined for a non-job stream. */
   byStream(stream: string): DurableCorrelation | undefined {
-    const jobKey = jobKeyOfStream(stream);
+    const jobKey = parseStreamId(stream)?.stream;
     return jobKey === undefined ? undefined : this.get(jobKey);
   }
 

package/app/agentic/correlation.test.ts

@@ -1,32 +1,36 @@
 // Unit tests for the jobKey ⇄ process/plan correlation registry (ADR 0056, H6 / #149).
 //
 // The registry is the single canonical join the cockpit uses to line a worker's terminal up with the
-// process instance / plan it belongs to. These tests pin: the `job:<jobKey>` stream convention; the
-// two derived-from-one-write projections (instance→jobKeys and jobKey→context) staying consistent
-// across link / re-link (move) / releaseJob / releaseInstance; the presence `jobKeysFor` seam; the
-// drill `primaryStreamFor`; and the sorted snapshot.
+// process instance / plan it belongs to. These tests pin: the instance-scoped `composeStreamId`
+// transcript-stream convention (issue #738); the two derived-from-one-write projections
+// (instance→jobKeys and jobKey→context) staying consistent across link / re-link (move) / releaseJob /
+// releaseInstance; the presence `jobKeysFor` seam; the drill `primaryStreamFor`; and the sorted snapshot.
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
+import { composeStreamId, parseStreamId } from "@nanobpm/agentic/emit";
 import {
   CorrelationRegistry,
   currentCorrelation,
   JOB_STREAM_PREFIX,
-  jobKeyOfStream,
   jobStream,
   setCurrentCorrelation,
 } from "./correlation.ts";
 
-test("jobStream / jobKeyOfStream are inverse over the job: convention", () => {
+test("jobStream builds the bare, slash-free job: id retained for the aux (Explorer/permission) surfaces", () => {
   assert.equal(jobStream("6494"), `${JOB_STREAM_PREFIX}6494`);
-  assert.equal(jobKeyOfStream(jobStream("6494")), "6494");
-  assert.equal(jobKeyOfStream("wk-a"), undefined);
-  // A bare `job:` prefix carries no jobKey, so it maps to undefined (not "") — an empty jobKey is
-  // invalid (link() ignores it), so callers never mistake it for a valid key.
-  assert.equal(jobKeyOfStream("job:"), undefined);
+  assert.equal(JOB_STREAM_PREFIX, "job:");
 });
 
-test("link records context and both projections; resolve carries the job: stream", () => {
+test("the transcript stream is the instance-scoped composeStreamId id, round-tripped by parseStreamId (#738)", () => {
+  const stream = composeStreamId("wk-a", "6494");
+  const ref = parseStreamId(stream);
+  assert.ok(ref);
+  assert.equal(ref.instance, "wk-a");
+  assert.equal(ref.stream, "6494");
+});
+
+test("link records context and both projections; resolve carries the instance-scoped stream", () => {
   const reg = new CorrelationRegistry();
   reg.link("wk-a", "6494", { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", planKey: "o/r#142" });
 
@@ -34,7 +38,7 @@ test("link records context and both projections; resolve carries the job: stream
   const c = reg.resolve("6494");
   assert.ok(c);
   assert.equal(c.jobKey, "6494");
-  assert.equal(c.stream, "job:6494");
+  assert.equal(c.stream, composeStreamId("wk-a", "6494"));
   assert.equal(c.processInstanceKey, "4612");
   assert.equal(c.bpmnProcessId, "plan-fanout");
   assert.equal(c.elementId, "implement-task");
@@ -54,7 +58,7 @@ test("attachElementInstance enriches a linked job's context, preserving every ot
   assert.equal(c.elementId, "agent");
   assert.equal(c.planKey, "o/r#142");
   assert.equal(c.jobKey, "6494");
-  assert.equal(c.stream, "job:6494");
+  assert.equal(c.stream, composeStreamId("wk-a", "6494"));
 });
 
 test("attachElementInstance is a no-op for a released (or never-linked) job or an empty key (#544)", () => {
@@ -145,7 +149,7 @@ test("primaryStreamFor picks the lowest-sorted job's stream; undefined when none
   assert.equal(reg.primaryStreamFor("wk-a"), undefined);
   reg.link("wk-a", "50");
   reg.link("wk-a", "10");
-  assert.equal(reg.primaryStreamFor("wk-a"), "job:10");
+  assert.equal(reg.primaryStreamFor("wk-a"), composeStreamId("wk-a", "10"));
 });
 
 test("snapshot returns every job sorted by jobKey", () => {
@@ -156,7 +160,11 @@ test("snapshot returns every job sorted by jobKey", () => {
   const snap = reg.snapshot();
   assert.equal(snap.count, 3);
   assert.deepEqual(snap.correlations.map((c) => c.jobKey), ["10", "20", "30"]);
-  assert.deepEqual(snap.correlations.map((c) => c.stream), ["job:10", "job:20", "job:30"]);
+  assert.deepEqual(snap.correlations.map((c) => c.stream), [
+    composeStreamId("wk-b", "10"),
+    composeStreamId("wk-c", "20"),
+    composeStreamId("wk-a", "30"),
+  ]);
 });
 
 test("link with no context leaves optional fields unset (no undefined holes)", () => {

package/app/agentic/correlation.ts

@@ -12,9 +12,10 @@
 //     asks for, so a worker's current jobKeys light up in the supply feed / cockpit.
 //   - `resolve(jobKey)` gives the cockpit the process-instance / plan a terminal belongs to, so the
 //     drilled bytes line up with "that process instance / this plan".
-//   - the relay terminal for a job is the jobKey-scoped stream {@link jobStream} — a stable naming
-//     convention (`job:<jobKey>`) so the report can repoint a worker's drill stream at its live job
-//     without a second lookup table.
+//   - the relay terminal for a job is the instance-scoped stream `composeStreamId(instance, jobKey)`
+//     from `@nanobpm/agentic/emit` (issue #738) — the ONE codec the producer also writes with, so the
+//     report can repoint a worker's drill stream at the exact live stream the producer emits without a
+//     second, divergent naming scheme.
 //
 // Who populates it: the orchestrator that dispatches an agentic job to a worker (it holds the whole
 // job payload — jobKey, processInstanceKey, bpmnProcessId, and the plan/epic it belongs to) calls
@@ -26,20 +27,32 @@
 // is untouched — correlation is an app-side observation, not a new wire type; ADVISORY — it is a
 // read-only join for visibility and NEVER hard-locks or gates a BPMN sequence flow.
 
-/** The relay-stream prefix for a jobKey-scoped terminal stream. */
+import { composeStreamId } from "@nanobpm/agentic/emit";
+
+/**
+ * The relay-stream prefix for a jobKey-scoped terminal stream. Retained ONLY for the two surfaces
+ * that still address a job by a bare, slash-free stream id — the Explorer Stage-0 transcript URL
+ * (`app/agentic/transcript-url.ts`, #543) and the permission control-lane resolution default
+ * (`app/agentic/permission-bridge.ts`). The cockpit transcript DATA plane no longer uses it: a job
+ * transcript stream is the instance-scoped `composeStreamId(instance, jobKey)` (issue #738), so that
+ * producer and consumer share ONE codec (`@nanobpm/agentic/emit`) and never diverge again.
+ */
 export const JOB_STREAM_PREFIX = "job:";
 
-/** The stable relay stream id a worker relays a job's terminal on: `job:<jobKey>`. */
+/** The bare, slash-free jobKey-scoped stream id `job:<jobKey>` — see {@link JOB_STREAM_PREFIX}. */
 export function jobStream(jobKey: string): string {
   return `${JOB_STREAM_PREFIX}${jobKey}`;
 }
 
 /**
- * The jobKey encoded in a jobKey-scoped relay stream id, or undefined for any other stream.
- * A bare `job:` prefix with no suffix carries no jobKey, so it maps to undefined too — keeping
- * the "empty jobKey is invalid" invariant (`link()` ignores empty jobKeys) consistent for callers.
+ * The jobKey encoded in a bare `job:<jobKey>` alias — the Stage-0 transcript URL / permission-lane
+ * scheme retained by {@link JOB_STREAM_PREFIX}. Returns undefined for ANY other stream, including an
+ * instance-scoped `composeStreamId(instance, jobKey)` data-plane id (decode THAT with `parseStreamId`)
+ * and a bare `job:` with no jobKey — keeping the "empty jobKey is invalid" invariant (`link()` ignores
+ * empty jobKeys) consistent for callers. This is the READ-path alias decoder ONLY: the write/relay side
+ * addresses jobs solely by the instance-scoped id, so it must never route through this.
  */
-export function jobKeyOfStream(stream: string): string | undefined {
+export function jobKeyOfJobStream(stream: string): string | undefined {
   if (!stream.startsWith(JOB_STREAM_PREFIX)) return undefined;
   const jobKey = stream.slice(JOB_STREAM_PREFIX.length);
   return jobKey === "" ? undefined : jobKey;
@@ -64,7 +77,7 @@ export interface JobCorrelation {
   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>`). */
+  /** The relay stream id the job's terminal is relayed on (`composeStreamId(instance, jobKey)`). */
   readonly stream: string;
 }
 
@@ -120,7 +133,7 @@ export class CorrelationRegistry {
     this.#context.set(jobKey, {
       ...existing,
       jobKey,
-      stream: jobStream(jobKey),
+      stream: composeStreamId(instance, jobKey),
       ...stripUndefined(context),
     });
   }
@@ -183,7 +196,7 @@ export class CorrelationRegistry {
    */
   primaryStreamFor(instance: string): string | undefined {
     const [first] = this.jobKeysFor(instance);
-    return first === undefined ? undefined : jobStream(first);
+    return first === undefined ? undefined : composeStreamId(instance, first);
   }
 
   /** The number of currently-linked jobs. */

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

@@ -12,6 +12,7 @@ import { AgenticHub } from "@nanobpm/agentic/channel";
 import type { Authenticator, ChannelConnection, ChannelTransport } from "@nanobpm/agentic/channel";
 import { encodeFrame, type Frame } from "@nanobpm/agentic/protocol";
 import { assert, assertEquals } from "#test-assert";
+import { composeStreamId } from "@nanobpm/agentic/emit";
 import { noopLog } from "../../../test/log.ts";
 import { currentClaimRegistry } from "../claim-registry.ts";
 import type { AgenticContext } from "../registry.ts";
@@ -91,7 +92,7 @@ test("a claim populates the worker's jobKeys with ZERO transcript (visibility no
     const reg = currentClaimRegistry();
     assert(reg, "registry mounted");
     assertEquals(reg.jobKeysFor("wk-a"), ["8420"]);
-    assertEquals(reg.primaryStreamFor("wk-a"), "job:8420", "the drill stream repoints at the claimed job");
+    assertEquals(reg.primaryStreamFor("wk-a"), composeStreamId("wk-a", "8420"), "the drill stream repoints at the claimed job");
   } finally {
     family.teardown?.();
   }