@nanobpm/nano-workforce 0.171.7 → 0.171.9

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.171.9](https://github.com/nanobpm/nano-workforce/compare/v0.171.8...v0.171.9) (2026-09-01)
+
+### Bug Fixes
+
+* **agentic:** spare a still-active job's relay stream on a mid-job reconnect ([#690](https://github.com/nanobpm/nano-workforce/issues/690)) ([e0bb51e](https://github.com/nanobpm/nano-workforce/commit/e0bb51e5cb4a2e1c92f3760a3a4e9c70b8ef3803)), closes [661/#688](https://github.com/661/nano-workforce/issues/688) [#reconcile](https://github.com/nanobpm/nano-workforce/issues/reconcile) [#689](https://github.com/nanobpm/nano-workforce/issues/689) [#689](https://github.com/nanobpm/nano-workforce/issues/689) [#689](https://github.com/nanobpm/nano-workforce/issues/689)
+
+## [0.171.8](https://github.com/nanobpm/nano-workforce/compare/v0.171.7...v0.171.8) (2026-09-01)
+
+### Bug Fixes
+
+* **agentic:** release job⇄worker correlation on terminal lifecycle event ([#688](https://github.com/nanobpm/nano-workforce/issues/688)) ([58dde6c](https://github.com/nanobpm/nano-workforce/commit/58dde6cf1c91f75828c8a38de52fef9409e3484c)), closes [#661](https://github.com/nanobpm/nano-workforce/issues/661) [#544](https://github.com/nanobpm/nano-workforce/issues/544) [#661](https://github.com/nanobpm/nano-workforce/issues/661)
+
 ## [0.171.7](https://github.com/nanobpm/nano-workforce/compare/v0.171.6...v0.171.7) (2026-09-01)
 
 ### Bug Fixes

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

@@ -138,6 +138,22 @@ test("instanceForConnection: resolves the worker instance owning a connection (H
   assertEquals(registry.instanceForConnection(""), undefined, "empty connection → undefined");
 });
 
+test("isInstanceLive: an instance is live while ANY of its connections is open — survives a reconnect (#689)", () => {
+  const store = createPresenceStore(memSqlite());
+  store.ensureSchema();
+  // worker-L reconnected: its OLD connection (cOld) is closed, a NEW one (cNew) is open. Presence is
+  // keyed by instance, so both rows exist; only cNew is live.
+  store.register({ instance: "worker-L", connectionId: "cOld", identity: "leaf", capability: {} });
+  store.register({ instance: "worker-L", connectionId: "cNew", identity: "leaf", capability: {} });
+  store.register({ instance: "worker-Gone", connectionId: "cGone", identity: "leaf", capability: {} });
+  const registry = new PresenceRegistry(store, () => new Set(["cNew"]));
+
+  assertEquals(registry.isInstanceLive("worker-L"), true, "live via its new connection despite the old one dropping");
+  assertEquals(registry.isInstanceLive("worker-Gone"), false, "no live connection → not live");
+  assertEquals(registry.isInstanceLive("unknown"), false, "unknown instance → not live");
+  assertEquals(registry.isInstanceLive(""), false, "empty instance → not live");
+});
+
 test("attributionOf: resolves a worker instance's durable identity + host for job attribution (#485)", () => {
   const store = createPresenceStore(memSqlite());
   store.ensureSchema();

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

@@ -148,6 +148,25 @@ export class PresenceRegistry {
     return undefined;
   }
 
+  /**
+   * Whether a worker instance currently has a LIVE hub connection — i.e. the worker is present now,
+   * on any connection. Used by the relay slice to distinguish a worker that merely RECONNECTED
+   * mid-job (its old producer connection dropped, a new one re-registered under the SAME instance,
+   * so the instance is still live) from a worker that truly EXITED (all its connections gone, so the
+   * instance is no longer live). The former must NOT complete/archive its still-active job stream on
+   * the stale-producer reconcile; the latter must. Presence is keyed by instance across reconnects,
+   * so this survives the connection churn that a single-connection liveness check cannot. An empty or
+   * unknown instance is not live.
+   */
+  isInstanceLive(instance: string): boolean {
+    if (instance === "") return false;
+    const live = this.#liveConnectionIds();
+    for (const row of this.#store.list()) {
+      if (row.instance === instance && live.has(row.connectionId)) return true;
+    }
+    return false;
+  }
+
   /**
    * Resolve a worker instance's durable identity attributes (presence identity + host) for job
    * attribution (#485). Returns the most recently registered matching row's attributes, or undefined

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

@@ -16,16 +16,19 @@ import { fileURLToPath } from "node:url";
 import { ConnectionRegistry } from "@nanobpm/agentic/channel";
 import type { Frame } from "@nanobpm/agentic/protocol";
 import { RELAY_FAMILY } from "@nanobpm/agentic/relay";
-import { type SqliteDb, TRANSCRIPT_SCHEMA_SQL } from "@nanobpm/agentic/transcript";
-import { assert, assertEquals } from "#test-assert";
+import { encodeTranscriptEvent, type SqliteDb, TRANSCRIPT_SCHEMA_SQL } from "@nanobpm/agentic/transcript";
+import { assert, assertEquals, assertThrows } from "#test-assert";
 import { noopLog } from "../../../test/log.ts";
 import { CorrelationRegistry, jobStream } from "../correlation.ts";
 import { AgenticCorrelationStore } from "../correlation-store.ts";
+import { createPresenceStore, PresenceRegistry } from "./presence.family.ts";
 import {
   type CorrelationLink,
   createRelayFamily,
   currentRelayTranscriptService,
+  engineReconcileMs,
   family as relayFamily,
+  guardOverlappingPasses,
   RELAY_FAMILY_NAME,
   RelayTranscriptService,
   sweepIntervalMs,
@@ -150,6 +153,7 @@ function mkCorrelatedService(
     attributionForInstance?: (instance: string) => { identity?: string; host?: string } | undefined;
     correlationStore?: AgenticCorrelationStore;
     resolveElementInstance?: (jobKey: string, processInstanceKey?: string) => Promise<string | undefined>;
+    isInstanceLive?: (instance: string) => boolean;
     now?: () => string;
   } = {},
 ): { service: RelayTranscriptService; hub: CapturingHub } {
@@ -164,6 +168,7 @@ function mkCorrelatedService(
     attributionForInstance: extra.attributionForInstance,
     correlationStore: extra.correlationStore,
     resolveElementInstance: extra.resolveElementInstance,
+    isInstanceLive: extra.isInstanceLive,
     now: extra.now,
   });
   return { service, hub };
@@ -542,6 +547,227 @@ test("#544 element-instance enrichment: an unresolved job (never parked) leaves
   service.teardown();
 });
 
+/** A `produce` frame whose chunk is a typed transcript LIFECYCLE event at `phase` (#661). */
+const lifecycle = (stream: string, incarnation: number, phase: "open" | "completed" | "exited"): Frame =>
+  produce(stream, incarnation, encodeTranscriptEvent({ kind: "lifecycle", phase, offset: 0 }));
+
+test("#661 primary release: a terminal lifecycle event clears an idle-but-connected worker's finished job", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  // The worker relays its job's terminal → linked as active.
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "the job is active while it runs");
+  assertEquals(correlation.count(), 1);
+
+  // The job ends: the worker emits the terminal `lifecycle` event on the SAME live connection and then
+  // goes idle — it does NOT disconnect and does NOT take a new job (no supersede). Before this fix that
+  // finished job lingered forever as a phantom active job; now the terminal event releases it.
+  hub.handler?.(lifecycle(jobStream("k1"), 1, "completed"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), [], "the finished job is released on the terminal event");
+  assertEquals(correlation.count(), 0, "count() drops — no phantom active job");
+
+  // Assert the RENDERED supply row clears too (not just the registry): the presence snapshot seeds
+  // per-worker jobKeys from the correlation registry, so an idle-but-connected worker shows no job.
+  const store = createPresenceStore(memoryDb());
+  store.ensureSchema();
+  store.register({ instance: "worker-A", connectionId: "prod", identity: "leaf", capability: {} });
+  const presence = new PresenceRegistry(store, () => new Set(["prod"]));
+  const row = presence.snapshot({ jobKeysFor: (i) => correlation.jobKeysFor(i) }).workers[0];
+  assertEquals(row.jobKeys, [], "the supply row shows no active job for the idle worker");
+  assert(row.live, "the worker is still connected — the connection persists across jobs");
+
+  // The terminal event itself is captured in the flushed transcript (release runs AFTER the ring append).
+  const meta = service.transcriptOf(jobStream("k1"));
+  assertEquals(meta?.status, "completed", "the finished job becomes a completed past session");
+  assertEquals(service.reattach(jobStream("k1"), 0)?.entries.length, 2, "the terminal event is part of the transcript");
+  service.teardown();
+});
+
+test("#661 primary release: an `exited` lifecycle also releases; a non-terminal `open` does not", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  // A `phase: "open"` lifecycle is NOT terminal — a genuinely active job must not be cleared.
+  hub.handler?.(lifecycle(jobStream("k1"), 1, "open"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "an open lifecycle keeps the active job");
+  assertEquals(correlation.count(), 1);
+
+  // An `exited` lifecycle (a crash/kill the worker still managed to report) IS terminal → released.
+  hub.handler?.(lifecycle(jobStream("k1"), 1, "exited"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), [], "an exited lifecycle releases the job");
+  assertEquals(correlation.count(), 0);
+  service.teardown();
+});
+
+test("#661 no-regression: an ordinary (non-lifecycle) chunk never clears a genuinely active job", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  // Ordinary terminal output (raw bytes, not a typed envelope) must NOT be read as a job-end signal.
+  for (let i = 0; i < 5; i++) hub.handler?.(produce(jobStream("k1"), 1, `output ${i}`), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "a running job stays active across ordinary output");
+  assertEquals(correlation.count(), 1);
+  assertEquals(service.transcriptOf(jobStream("k1")), undefined, "the live job is not completed");
+  service.teardown();
+});
+
+test("#661 defensive reconcile: an unclean exit (no lifecycle) whose engine job is gone is dropped by the reconcile pass", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  // The engine reports job k1 as a live JOB park (element instance ei-1) — until the worker exits
+  // UNCLEANLY (crash/kill): it emits no terminal lifecycle event, keeps no connection to reconcile,
+  // and the engine park is gone → the resolver returns undefined.
+  let parked = true;
+  const resolveElementInstance = (jobKey: string) =>
+    Promise.resolve(parked && jobKey === "k1" ? "ei-1" : undefined);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection, {
+    resolveElementInstance,
+  });
+  const p = connect("prod", registry);
+
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "the job links while it runs");
+
+  // While the engine still parks the job, the reconcile pass leaves a genuinely active job alone.
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "a genuinely active job is NOT cleared by the safety net");
+  assertEquals(correlation.count(), 1);
+
+  // The worker exits uncleanly (no lifecycle event) — its engine park vanishes. The next reconcile
+  // pass drops the stale correlation even though nothing on the wire signalled job end.
+  parked = false;
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-A"), [], "the reconcile pass drops the stale correlation");
+  assertEquals(correlation.count(), 0, "no phantom active job survives an unclean exit");
+  service.teardown();
+});
+
+test("#661 defensive reconcile: a transient engine read failure never falsely releases a job", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  // The engine read throws (unavailable) — a transient fault must be treated as "unknown, keep it",
+  // NEVER as "job gone", or a live job would be wrongly cleared on every engine blip.
+  const resolveElementInstance = () => Promise.reject(new Error("engine unavailable"));
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection, {
+    resolveElementInstance,
+  });
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "a transient engine failure leaves the job linked");
+  assertEquals(correlation.count(), 1);
+  service.teardown();
+});
+
+test("#661 defensive reconcile: a no-op when no engine resolver is wired", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+
+  // With no element-instance resolver (engine-less host), the safety net cannot query the engine —
+  // it must be an inert no-op, leaving the correlation exactly as the primary path manages it.
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "no resolver → the reconcile pass is inert");
+  service.teardown();
+});
+
+test("#661 engineReconcileMs: defaults, disables on a non-positive/non-finite value, caps at the timer max", () => {
+  assertEquals(engineReconcileMs(), 30_000, "an omitted config uses the default cadence");
+  assertEquals(engineReconcileMs(5_000), 5_000, "a finite positive value is honoured");
+  assertEquals(engineReconcileMs(0), undefined, "zero disables the pass");
+  assertEquals(engineReconcileMs(-1), undefined, "a negative value disables the pass");
+  assertEquals(engineReconcileMs(Number.NaN), undefined, "a non-finite value disables the pass");
+  assertEquals(engineReconcileMs(Number.POSITIVE_INFINITY), undefined, "infinity disables the pass");
+  assertEquals(engineReconcileMs(2 ** 32), 2_147_483_647, "a huge value is capped at the Node timer ceiling");
+  assertEquals(engineReconcileMs(0.5), 1, "a sub-millisecond positive value floors to 1ms, never 0 (no busy setInterval(0))");
+});
+
+test("#661 guardOverlappingPasses: a tick while a pass is in flight is skipped; only one pass runs at a time", async () => {
+  let starts = 0;
+  let active = 0;
+  let maxActive = 0;
+  let release!: () => void;
+  // A pass that blocks until we release it, so we can hold one "in flight" while further ticks fire.
+  const pass = () => {
+    starts++;
+    active++;
+    maxActive = Math.max(maxActive, active);
+    return new Promise<void>((resolve) => {
+      release = () => {
+        active--;
+        resolve();
+      };
+    });
+  };
+  const tick = guardOverlappingPasses(pass);
+
+  tick(); // first tick starts a pass — now in flight
+  tick(); // skipped while the first pass is still pending
+  tick(); // skipped
+  assertEquals(starts, 1, "overlapping ticks are dropped while a pass is in flight");
+  assertEquals(maxActive, 1, "never more than one pass runs concurrently");
+
+  release(); // let the first pass settle
+  await new Promise((r) => setImmediate(r)); // flush the `finally` that clears the in-flight flag
+
+  tick(); // a tick after the previous pass settled starts a fresh pass
+  assertEquals(starts, 2, "a tick after the in-flight pass settles starts a new pass");
+  assertEquals(maxActive, 1, "still only ever one pass at a time");
+  release();
+});
+
+test("#661 guardOverlappingPasses: a pass whose work rejects but is self-caught still re-arms the guard", async () => {
+  // The guard clears its in-flight flag via `.finally`, so it re-arms whether the pass resolves OR
+  // rejects — a rejection does NOT wedge the guard. The real hazard of a rejecting pass is an
+  // *unhandled rejection* (the tick voids the returned promise), which is why the mount wraps
+  // `reconcileEngineCorrelations()` in `.catch`. Here the pass's work rejects but is self-caught
+  // (mirroring that wrapper), so there is no unhandled rejection, and we assert the guard re-arms.
+  let starts = 0;
+  const tick = guardOverlappingPasses(() => {
+    starts++;
+    // Work that rejects but settles its own error — exactly like the mount's `.catch` wrapper.
+    return Promise.reject(new Error("pass work failed")).catch(() => {});
+  });
+  tick();
+  await new Promise((r) => setImmediate(r));
+  tick();
+  await new Promise((r) => setImmediate(r));
+  assertEquals(starts, 2, "a self-caught rejecting pass settles and re-arms the guard for the next tick");
+});
+
+test("#661 guardOverlappingPasses: a pass that throws SYNCHRONOUSLY re-arms the guard (no wedge) and stays loud", () => {
+  // A synchronous throw from `pass` escapes before `.finally` is attached, so the guard must catch it,
+  // re-arm, and re-throw — otherwise a future non-`async` caller/refactor would wedge the guard
+  // permanently in-flight. We assert both: the throw propagates (stays loud, not swallowed) AND the
+  // next tick starts a fresh pass (the guard re-armed rather than sticking at in-flight).
+  let starts = 0;
+  const tick = guardOverlappingPasses(() => {
+    starts++;
+    throw new Error("synchronous boom"); // violates the "must not throw synchronously" contract
+  });
+  assertThrows(() => tick(), Error, "synchronous boom");
+  assertThrows(() => tick(), Error, "synchronous boom");
+  assertEquals(starts, 2, "the guard re-armed after a synchronous throw, so the next tick ran the pass");
+});
+
 /**
  * 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
@@ -661,6 +887,75 @@ test("H6 correlation write-side: a producer disconnect releases its job correlat
   service.teardown();
 });
 
+test("#689 mid-job reconnect: a stale producer whose instance is still live keeps its job correlation", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["conn-old", "worker-L"]]);
+  // Derive liveness from REAL connections exactly as production's PresenceRegistry.isInstanceLive
+  // does — an instance is live iff some connection attributed to it is still open in the registry —
+  // rather than a static stub decoupled from the connection churn. This makes the test exercise the
+  // very reconnect race the seam guards: the instance is live only while a real live connection
+  // (conn-old, then conn-new) backs it.
+  const isInstanceLive = (instance: string): boolean => {
+    for (const [connId, inst] of byConnection) {
+      if (inst === instance && registry.has(connId)) return true;
+    }
+    return false;
+  };
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection, {
+    isInstanceLive,
+  });
+  const p = connect("conn-old", registry);
+  hub.handler?.(produce(jobStream("5749"), 1, "booting agent"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-L"), ["5749"], "the job is linked on first produce");
+
+  // The producer's WS connection blips (client reconnects). Model the reconnect faithfully: the new
+  // connection re-registers under the SAME instance BEFORE the reconcile frame, so there is never a
+  // gap where the instance is not live — presence keeps worker-L live across the churn. The old
+  // producer connection then drops. A subsequent frame drives #reconcile — which, seeing the instance
+  // still live via conn-new, must NOT archive the still-active job.
+  byConnection.set("conn-new", "worker-L");
+  const p2 = connect("conn-new", registry);
+  registry.remove("conn-old");
+  const other = connect("cons", registry);
+  hub.handler?.(grant(0), other.conn);
+  assertEquals(correlation.jobKeysFor("worker-L"), ["5749"], "a mid-job reconnect keeps the correlation");
+  assertEquals(service.transcriptOf(jobStream("5749")), undefined, "the still-active stream is NOT archived");
+
+  // The worker resumes producing on the SAME job over its already-open NEW connection → re-attributed,
+  // still one job, transcript still live (not terminal).
+  hub.handler?.(produce(jobStream("5749"), 1, "resumed output"), p2.conn);
+  assertEquals(correlation.jobKeysFor("worker-L"), ["5749"], "the resumed producer stays linked to the same job");
+  assertEquals(service.liveFallback(jobStream("5749"))?.ring !== undefined, true, "the transcript is still live, not completed");
+
+  // Only once the worker truly EXITS (all its connections gone → isInstanceLive false) does a later
+  // reconcile complete the stream and release the correlation.
+  registry.remove("conn-new");
+  hub.handler?.(grant(0), other.conn);
+  assertEquals(correlation.jobKeysFor("worker-L"), [], "a true worker-exit completes + releases the job");
+  assertEquals(service.transcriptOf(jobStream("5749"))?.status, "completed", "the exited worker's stream is archived");
+  service.teardown();
+});
+
+test("#689 mid-job reconnect: with no isInstanceLive wired, a producer disconnect completes as before", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-N"]]);
+  // Default seam (isInstanceLive omitted → () => false): a producer disconnect completes the stream,
+  // preserving the prior always-complete-on-disconnect behaviour for callers that don't wire presence.
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("kN"), 1, "x"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-N"), ["kN"]);
+
+  registry.remove("prod");
+  const other = connect("cons", registry);
+  hub.handler?.(grant(0), other.conn);
+  assertEquals(correlation.jobKeysFor("worker-N"), [], "disconnect completes + releases when liveness is unknown");
+  assertEquals(service.transcriptOf(jobStream("kN"))?.status, "completed");
+  service.teardown();
+});
+
 test("H6 correlation write-side: non-job streams are never linked; a link retries until the instance resolves", () => {
   const registry = new ConnectionRegistry();
   const correlation = new CorrelationRegistry();

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

@@ -24,6 +24,7 @@ import type { ConnectionRegistry } from "@nanobpm/agentic/channel";
 import type { Frame } from "@nanobpm/agentic/protocol";
 import { RELAY_FAMILY, RelayHub, type RelayHubOptions } from "@nanobpm/agentic/relay";
 import {
+  parseTranscriptEvent,
   type SqliteDb,
   type TranscriptLifecycle,
   type TranscriptRing,
@@ -50,6 +51,14 @@ const SWEEP_DIVISOR = 4;
  * 32-bit timer and Node silently clamps it to 1ms — turning a slow periodic tick into a busy loop. */
 const MAX_TIMER_MS = 2_147_483_647;
 
+/**
+ * Default cadence (ms) of the defensive engine-reconcile pass (#661) — the safety net that releases a
+ * correlation whose engine JOB park is gone but whose terminal `lifecycle` event never arrived (an
+ * unclean worker exit). 30s trades a small staleness bound for a light engine-read load; the precise,
+ * immediate release stays the terminal-lifecycle path, so this only ever mops up unclean exits.
+ */
+const DEFAULT_ENGINE_RECONCILE_MS = 30_000;
+
 /**
  * The retention-sweep cadence (ms) for a given ephemeral-retention window: a fraction of the window,
  * floored at 1ms and — crucially — capped at {@link MAX_TIMER_MS} so a large retention config (e.g.
@@ -64,12 +73,75 @@ export function sweepIntervalMs(ephemeralRetentionMs: number): number {
   return Math.min(MAX_TIMER_MS, Math.max(1, interval));
 }
 
+/**
+ * The defensive engine-reconcile cadence (ms) for a given config (#661), or `undefined` to DISABLE the
+ * pass. An omitted config uses {@link DEFAULT_ENGINE_RECONCILE_MS}; a non-finite or non-positive value
+ * (a broken config, or a deliberate opt-out) disables the pass rather than degrading into a 1ms busy
+ * loop; a finite positive value is floored at 1ms (so a sub-millisecond config like 0.5 cannot floor
+ * to 0 and degrade into a busy `setInterval(0)`) and capped at {@link MAX_TIMER_MS} so a large window
+ * cannot overflow Node's 32-bit timer.
+ */
+export function engineReconcileMs(configuredMs?: number): number | undefined {
+  const value = configuredMs ?? DEFAULT_ENGINE_RECONCILE_MS;
+  if (!Number.isFinite(value) || value <= 0) return undefined;
+  return Math.min(MAX_TIMER_MS, Math.max(1, Math.floor(value)));
+}
+
+/**
+ * Wrap an async pass in an in-flight guard so a periodic `setInterval` never fires OVERLAPPING runs
+ * (#661). A single pass of {@link RelayTranscriptService.reconcileEngineCorrelations} awaits an engine
+ * read per linked job, so a pass can outlast its interval (a small configured cadence, or a slow/large
+ * engine read-model); an unguarded `setInterval` would then stack concurrent passes, piling up engine
+ * reads and log volume. While a pass is still pending, every subsequent tick is skipped; the next tick
+ * after it settles — whether it resolves OR rejects, since the guard clears via `.finally` — starts a
+ * fresh pass. The guard clears on BOTH failure modes so it can never wedge in-flight: (1) a
+ * *synchronous* throw from `pass` escapes before `.finally` is attached, so it is caught here — the
+ * guard is re-armed and the fault is re-thrown so it stays loud rather than being silently swallowed;
+ * (2) an async rejection is cleared by `.finally`, but the tick `void`s (does not await) the returned
+ * promise, so `pass` must still settle its own rejections or an unhandled rejection results — which is
+ * why the mount wraps `reconcileEngineCorrelations()` in `.catch`. Making the guard resilient to (1)
+ * removes a subtle footgun for a future caller (or refactor) that returns a non-`async` `pass`. Mirrors
+ * the "one pass at a time" discipline the main poll loop enforces by self-scheduling. Returns the tick
+ * callback to hand to `setInterval`.
+ */
+export function guardOverlappingPasses(pass: () => Promise<void>): () => void {
+  let inFlight = false;
+  return () => {
+    if (inFlight) return;
+    inFlight = true;
+    try {
+      void pass().finally(() => {
+        inFlight = false;
+      });
+    } catch (err) {
+      // A synchronous throw never attaches the `.finally`; re-arm the guard so it does not wedge,
+      // then re-throw so a contract violation still surfaces instead of being silently swallowed.
+      inFlight = false;
+      throw err;
+    }
+  };
+}
+
 /** Read a property off an unknown value without an unsafe `as` cast (mirrors the loader's helper). */
 function readProp(value: unknown, key: string): unknown {
   if (!value || typeof value !== "object") return undefined;
   return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
 }
 
+/**
+ * Decode a single relay chunk through the ONE canonical transcript parser and report whether it is a
+ * TERMINAL `lifecycle` event (`phase` `completed`/`exited`) — the authoritative "job end" signal a
+ * clean agent run emits on its transcript stream (#661). Anything else — raw terminal bytes, a
+ * non-envelope JSON value, a `phase: "open"` lifecycle, any other event kind — is not terminal.
+ * Reusing {@link parseTranscriptEvent} keeps transcript-vocab knowledge out of the content-agnostic
+ * relay ring and off any forked decoder (Derivation Over Duplication): the ring still sees opaque
+ * bytes; only this narrow seam classifies them.
+ */
+function isTerminalLifecycleChunk(chunk: string): boolean {
+  const event = parseTranscriptEvent({ offset: 0, chunk });
+  return event.kind === "lifecycle" && (event.phase === "completed" || event.phase === "exited");
+}
+
 /**
  * A resume-from-offset source with no retained chunks — used to flush/complete a stream that a
  * producer opened logically but never wrote to, so its transcript is still stamped `completed`
@@ -180,6 +252,19 @@ export interface RelayTranscriptServiceOptions {
    * ({@link currentPresenceRegistry}). A resolver returning undefined → no linking (advisory).
    */
   readonly instanceForConnection?: (connectionId: string) => string | undefined;
+  /**
+   * Whether a worker instance is still live on any hub connection (#689). Wired to the presence
+   * registry's {@link PresenceRegistry.isInstanceLive}. The disconnect-driven reconcile uses it to
+   * spare a still-active job's stream when its worker merely RECONNECTED mid-job (old producer
+   * connection dropped, a new one re-registered under the same instance): completing then would
+   * archive a live job's transcript and release its correlation, wedging the cockpit (the reconnected
+   * worker's produce frames hit a terminal `completed` stream and are ignored) while the harness
+   * keeps the engine lease. When wired to presence, a true worker-exit still completes: presence
+   * has dropped the instance, so this returns false. Omitted (`() => false`, the static default) →
+   * the prior always-complete-on-disconnect behaviour — every disconnect completes, reconnect
+   * included (the seam never consults presence, so its value does not vary).
+   */
+  readonly isInstanceLive?: (instance: string) => boolean;
   /**
    * Resolve a producing worker instance's durable identity attributes (identity / host) — read at
    * job-completion time and persisted with the attribution so a PAST session stays attributable to a
@@ -245,6 +330,8 @@ export class RelayTranscriptService {
   readonly #correlation: () => CorrelationLink | undefined;
   /** The connection → producing-instance resolver (H6, #149). */
   readonly #instanceForConnection: (connectionId: string) => string | undefined;
+  /** Whether a worker instance is still live on any connection (#689) — gates disconnect completion. */
+  readonly #isInstanceLive: (instance: string) => boolean;
   /** Resolve a worker instance's durable identity attributes for attribution (#485). */
   readonly #attributionForInstance: (instance: string) => WorkerAttribution | undefined;
   /** The durable worker-attribution store, or undefined when unpersisted (#485). */
@@ -259,6 +346,7 @@ export class RelayTranscriptService {
     this.#log = options.log;
     this.#correlation = options.correlation ?? currentCorrelation;
     this.#instanceForConnection = options.instanceForConnection ?? (() => undefined);
+    this.#isInstanceLive = options.isInstanceLive ?? (() => false);
     this.#attributionForInstance = options.attributionForInstance ?? (() => undefined);
     this.#resolveElementInstance = options.resolveElementInstance;
     this.#now = options.now ?? (() => new Date().toISOString());
@@ -424,11 +512,41 @@ export class RelayTranscriptService {
     this.#streams.clear();
   }
 
-  /** Handle one inbound `relay` frame: reconcile dead producers, observe ownership, then delegate. */
+  /** Handle one inbound `relay` frame: reconcile dead producers, observe ownership, delegate, then
+   * release on a terminal `lifecycle` event (#661 — AFTER the hub appended the chunk, so the terminal
+   * event itself is captured in the flushed transcript). */
   #onFrame(frame: Frame, conn: RelayConnectionCtx): void {
     this.#reconcile();
     this.#observe(frame, conn);
     this.relay.handle(frame, conn);
+    this.#observeTerminalLifecycle(frame);
+  }
+
+  /**
+   * Primary job-end release (#661): when a `produce` frame carries the terminal `lifecycle` event
+   * (`phase` `completed`/`exited`), complete its stream so the worker's job⇄instance correlation is
+   * released the moment the job ends — even though the worker's relay connection stays open across jobs
+   * (the disconnect/supersede release paths miss that idle-after-last-job tail, so an idle worker's
+   * finished job would otherwise linger as a phantom active job on its supply row). Runs AFTER the hub
+   * appends the chunk to the ring, so the terminal event is part of the flushed transcript. A narrow,
+   * self-contained decode at the correlation seam that reuses the ONE canonical
+   * {@link parseTranscriptEvent} — the content-agnostic relay ring keeps treating chunks as opaque
+   * bytes, and no transcript-vocab knowledge is forked into it. Non-terminal chunks (raw bytes, a
+   * `phase: "open"` lifecycle, any other event kind) never complete a live stream, so a genuinely
+   * active job is never cleared. Advisory — never throws into the frame handler.
+   */
+  #observeTerminalLifecycle(frame: Frame): void {
+    if (readProp(frame.payload, "op") !== "produce") return;
+    const stream = readProp(frame.payload, "stream");
+    if (typeof stream !== "string" || stream === "") return;
+    const chunk = readProp(frame.payload, "chunk");
+    if (typeof chunk !== "string" || chunk === "") return;
+    const state = this.#streams.get(stream);
+    // Idempotent: an unknown or already-completed stream needs no (further) release — a second terminal
+    // event, or a late one after the disconnect/supersede path already completed the stream, is a no-op.
+    if (state === undefined || state.completed) return;
+    if (!isTerminalLifecycleChunk(chunk)) return;
+    this.completeStream(stream);
   }
 
   /** Record `produce` ownership so a producer disconnect can drive ephemeral completion. */
@@ -616,6 +734,19 @@ export class RelayTranscriptService {
   #reconcile(): void {
     for (const [stream, state] of this.#streams) {
       if (state.producer !== undefined && !this.#registry.has(state.producer)) {
+        // Producer connection gone. Normally that means the job it was relaying ended — release the
+        // correlation and flush+complete its ephemeral transcript. BUT a worker that merely
+        // RECONNECTED mid-job (#689) also loses its old producer connection while its job keeps
+        // running (the harness holds the engine lease and extends it). Presence re-registers the SAME
+        // instance under the new connection, so the instance stays live even though this specific
+        // producer connection is gone. Completing then would archive a still-active job's transcript
+        // to `historical` and drop its correlation — and because a completed stream is terminal
+        // (`#observe` ignores later frames), the reconnected worker could NEVER re-correlate: the
+        // cockpit shows the worker idle with a frozen transcript while the job is genuinely running.
+        // So spare the stream while its instance is still live; the next `produce` re-attributes the
+        // live connection (via `#observe`), a NEW job supersedes it (via `#link`), or — once the
+        // worker truly exits — presence drops the instance and a later reconcile completes it.
+        if (state.instance !== undefined && this.#isInstanceLive(state.instance)) continue;
         // Producer connection gone → the job it was relaying ended: release its correlation.
         this.#unlink(stream, state);
         // ...and flush+complete an ephemeral, not-yet-completed transcript exactly as before.
@@ -624,6 +755,61 @@ export class RelayTranscriptService {
     }
   }
 
+  /**
+   * Defensive engine-reconcile safety net (#661): release any linked jobKey whose engine JOB park is
+   * no longer live. The precise, fast release is the terminal `lifecycle` event
+   * ({@link #observeTerminalLifecycle}), but an UNCLEAN worker exit (crash/kill) can skip that event —
+   * and because the worker's relay connection is persistent across jobs, the disconnect release never
+   * fires either, so the finished job would linger as a phantom active job on the worker's supply row.
+   * This periodic pass asks the engine read model (the same {@link ElementInstanceResolver} the link
+   * path uses at #544) whether each linked job is still parked; a job the engine no longer parks
+   * (resolver returns `undefined`) is released and its transcript completed. Bounds staleness regardless
+   * of whether the worker emitted a clean terminal event — and also covers a worker that emitted nothing
+   * and merely went quiet.
+   *
+   * Advisory and best-effort: a no-op with no resolver wired, and a resolver THROW / REJECTION for a
+   * given job is treated as "unknown — keep it linked" (never a false release of a genuinely active
+   * job). The linked set is snapshotted before any await so a concurrent completion (a terminal
+   * lifecycle event landing mid-pass) cannot corrupt iteration, and each release re-checks the current
+   * stream state so a job already released between snapshot and resolution is not double-completed.
+   */
+  async reconcileEngineCorrelations(): Promise<void> {
+    const resolve = this.#resolveElementInstance;
+    if (resolve === undefined) return;
+    const linked: { stream: string; jobKey: string; processInstanceKey?: string }[] = [];
+    for (const [stream, state] of this.#streams) {
+      if (!state.linked || state.completed) continue;
+      const jobKey = jobKeyOfStream(stream);
+      if (jobKey === undefined) continue;
+      const processInstanceKey = this.#correlation()?.resolve?.(jobKey)?.processInstanceKey;
+      linked.push({ stream, jobKey, processInstanceKey });
+    }
+    for (const { stream, jobKey, processInstanceKey } of linked) {
+      let activeKey: string | undefined;
+      try {
+        activeKey = await resolve(jobKey, processInstanceKey);
+      } catch (err) {
+        // A transient engine read failure must NOT be read as "job gone" — leave the job linked; a
+        // later pass (or the terminal lifecycle event) releases it. Advisory, never a false release.
+        this.#log.warn("agentic relay engine-reconcile read failed — leaving correlation linked", {
+          stream,
+          jobKey,
+          err: String(err),
+        });
+        continue;
+      }
+      // A live JOB park (a resolved element-instance key) means the job is genuinely active — keep it.
+      if (activeKey !== undefined) continue;
+      // The engine no longer parks this job → it ended (possibly via an unclean exit that skipped the
+      // terminal lifecycle event). Re-check the current state — a concurrent completion may already
+      // have released it — then release its correlation and flush its transcript.
+      const current = this.#streams.get(stream);
+      if (current === undefined || current.completed || !current.linked) continue;
+      this.#log.info("agentic relay engine-reconcile released a stale correlation", { stream, jobKey });
+      this.completeStream(stream);
+    }
+  }
+
   /**
    * The still-live relay ring for a stream, for the read path to serve BEFORE a durable flush (#486).
    *
@@ -670,11 +856,18 @@ export function createRelayFamily(options: {
   readonly relay?: RelayHubOptions;
   readonly transcript?: TranscriptStoreOptions;
   readonly ensureSchema?: boolean;
+  /**
+   * Cadence (ms) of the defensive engine-reconcile pass (#661). Defaults to
+   * {@link DEFAULT_ENGINE_RECONCILE_MS}. Clamped to Node's 32-bit timer ceiling; a non-positive /
+   * non-finite value disables the pass (the terminal-lifecycle release path still runs).
+   */
+  readonly engineReconcileIntervalMs?: number;
   /** Called with the live service once mounted, so a driver can drive completion/reattach. */
   readonly onMounted?: (service: RelayTranscriptService) => void;
 } = {}): AgenticFamily {
   let service: RelayTranscriptService | undefined;
   let sweepTimer: ReturnType<typeof setInterval> | undefined;
+  let engineReconcileTimer: ReturnType<typeof setInterval> | undefined;
   return {
     name: RELAY_FAMILY_NAME,
     mount(ctx: AgenticContext): void {
@@ -693,6 +886,11 @@ export function createRelayFamily(options: {
         // are read per call, so this works regardless of family mount order (relay may mount before
         // presence/correlation). Absent registries → no linking, still advisory-correct.
         instanceForConnection: (connectionId) => currentPresenceRegistry()?.instanceForConnection(connectionId),
+        // #689: is the producing worker instance still live on ANY connection? Gates the
+        // disconnect-driven reconcile so a mid-job RECONNECT (old producer connection dropped, the
+        // same instance re-registered) does not archive a still-active job's stream and wedge its
+        // correlation. Read per call for the same mount-order independence as the resolvers above.
+        isInstanceLive: (instance) => currentPresenceRegistry()?.isInstanceLive(instance) ?? false,
         // #485: resolve a completed job's worker attribution (presence identity/host) from the live
         // presence registry, read per call for the same mount-order independence. Absent → attribution
         // records instance only.
@@ -729,6 +927,31 @@ export function createRelayFamily(options: {
         tick();
       }
 
+      // Defensive engine-reconcile safety net (#661): periodically release any linked correlation
+      // whose engine JOB park is gone but whose terminal `lifecycle` event never arrived (an unclean
+      // worker exit), so a crashed worker's finished job stops showing as a phantom active job. Only
+      // useful when an element-instance resolver is wired (engine read-model access); harmless no-op
+      // otherwise. Advisory — a reconcile fault is logged, never thrown, and never keeps the process
+      // alive on its own.
+      if (ctx.resolveElementInstance !== undefined) {
+        const reconcileInterval = engineReconcileMs(options.engineReconcileIntervalMs);
+        if (reconcileInterval !== undefined) {
+          // In-flight guard: `reconcileEngineCorrelations()` is async and awaits an engine read per
+          // linked job, so a pass can outlast `reconcileInterval` (a small interval, or a slow/large
+          // engine read-model). Without a guard, `setInterval` would fire overlapping passes that pile
+          // up concurrent engine reads and log volume. {@link guardOverlappingPasses} skips a tick while
+          // the previous pass is still running so only one reconcile runs at a time — the same "one pass
+          // at a time" discipline the main poll loop enforces by self-scheduling.
+          const reconcileTick = guardOverlappingPasses(() =>
+            (service?.reconcileEngineCorrelations() ?? Promise.resolve()).catch((err: unknown) => {
+              ctx.log.warn("agentic relay engine-reconcile failed", { err: String(err) });
+            }),
+          );
+          engineReconcileTimer = setInterval(reconcileTick, reconcileInterval);
+          engineReconcileTimer.unref?.();
+        }
+      }
+
       options.onMounted?.(service);
     },
     teardown(): void {
@@ -736,6 +959,10 @@ export function createRelayFamily(options: {
         clearInterval(sweepTimer);
         sweepTimer = undefined;
       }
+      if (engineReconcileTimer !== undefined) {
+        clearInterval(engineReconcileTimer);
+        engineReconcileTimer = undefined;
+      }
       service?.teardown();
       if (currentService === service) setCurrentRelayTranscriptService(undefined);
       service = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.171.7",
+  "version": "0.171.9",
   "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",