@nanobpm/nano-workforce 0.174.1 → 0.175.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.175.0](https://github.com/nanobpm/nano-workforce/compare/v0.174.1...v0.175.0) (2026-09-02)
+
+### Features
+
+* **agentic:** engine/poller-owned relay transcript completion (retire the presence heuristic) ([#708](https://github.com/nanobpm/nano-workforce/issues/708)) ([74f42f6](https://github.com/nanobpm/nano-workforce/commit/74f42f6fa3f1b07a6608ccf50979693eecb8ead4)), closes [689/#690](https://github.com/689/nano-workforce/issues/690) [#661](https://github.com/nanobpm/nano-workforce/issues/661) [#691](https://github.com/nanobpm/nano-workforce/issues/691) [#691](https://github.com/nanobpm/nano-workforce/issues/691) [#691](https://github.com/nanobpm/nano-workforce/issues/691) [#unlink](https://github.com/nanobpm/nano-workforce/issues/unlink)
+
 ## [0.174.1](https://github.com/nanobpm/nano-workforce/compare/v0.174.0...v0.174.1) (2026-09-02)
 
 ### Bug Fixes

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

@@ -956,6 +956,198 @@ test("#689 mid-job reconnect: with no isInstanceLive wired, a producer disconnec
   service.teardown();
 });
 
+test("#691 engine-owned disconnect: a mid-job reconnect whose engine job is still parked keeps the correlation live", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["conn-old", "worker-E"]]);
+  // The engine is the completion authority (#691): while the harness holds the lease the job stays
+  // parked (resolver returns an element-instance key), so a producer disconnect must NOT complete it.
+  let parked = true;
+  const resolveElementInstance = (jobKey: string) =>
+    Promise.resolve(parked && jobKey === "9001" ? "ei-9001" : undefined);
+  // isInstanceLive is deliberately NOT wired (static () => false): the engine job-state — not the
+  // presence heuristic — must be what spares the reconnect, proving presence is no longer the authority.
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection, {
+    resolveElementInstance,
+  });
+  const p = connect("conn-old", registry);
+  hub.handler?.(produce(jobStream("9001"), 1, "booting agent"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-E"), ["9001"], "the job links on first produce");
+
+  // The producer WS blips: the old connection drops (no new one yet — presence would report the
+  // instance NOT live). A frame drives #reconcile → drops the dead producer + kicks the engine reconcile.
+  registry.remove("conn-old");
+  const other = connect("cons", registry);
+  hub.handler?.(grant(0), other.conn);
+  await tick(); // let the fire-and-forget engine reconcile settle
+  assertEquals(correlation.jobKeysFor("worker-E"), ["9001"], "a still-parked job survives the disconnect");
+  assertEquals(service.transcriptOf(jobStream("9001")), undefined, "the still-active stream is NOT archived");
+  assertEquals(service.liveFallback(jobStream("9001"))?.ring !== undefined, true, "the transcript is still live");
+
+  // The worker resumes producing on a NEW connection over the same job → re-attributed, still one job.
+  byConnection.set("conn-new", "worker-E");
+  const p2 = connect("conn-new", registry);
+  hub.handler?.(produce(jobStream("9001"), 1, "resumed output"), p2.conn);
+  assertEquals(correlation.jobKeysFor("worker-E"), ["9001"], "the resumed producer stays linked to the same job");
+
+  // The job genuinely ends: the engine park vanishes. The periodic backstop pass completes + archives it.
+  parked = false;
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-E"), [], "the ended job is released");
+  assertEquals(service.transcriptOf(jobStream("9001"))?.status, "completed", "and its transcript is archived");
+  service.teardown();
+});
+
+test("#691 engine-owned disconnect: a true exit whose engine job is gone completes + archives the stream", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-X"]]);
+  // The engine reports the job GONE at disconnect time (a clean completion whose terminal lifecycle
+  // event was missed, or an unclean exit): the disconnect-driven engine reconcile completes it.
+  const resolveElementInstance = () => Promise.resolve(undefined);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection, {
+    resolveElementInstance,
+  });
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("kX"), 1, "x"), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-X"), ["kX"]);
+
+  registry.remove("prod");
+  const other = connect("cons", registry);
+  hub.handler?.(grant(0), other.conn);
+  await tick(); // the fire-and-forget engine reconcile resolves "gone" → completes
+  assertEquals(correlation.jobKeysFor("worker-X"), [], "a truly-ended job is released on disconnect");
+  assertEquals(service.transcriptOf(jobStream("kX"))?.status, "completed", "and its transcript is archived");
+  service.teardown();
+});
+
+test("#691 engine-owned disconnect: an UNLINKED job stream (register/produce race) whose engine job is still parked is NOT archived on disconnect", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  // The connection→instance map is deliberately EMPTY at first produce: the producer's presence
+  // instance is not yet resolvable (the documented register/produce race), so #link leaves the job
+  // stream UNLINKED (`state.linked` stays false) even though it IS a job stream and a resolver is
+  // wired. The engine — not `state.linked` — must own the disconnect completion decision, otherwise
+  // a mid-job reconnect that raced the link would wrongly fall through to the presence fallback and
+  // archive a still-parked job.
+  const byConnection = new Map<string, string>();
+  let parked = true;
+  const resolveElementInstance = (jobKey: string) =>
+    Promise.resolve(parked && jobKey === "7742" ? "ei-7742" : undefined);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection, {
+    resolveElementInstance,
+  });
+  const p = connect("conn-old", registry);
+  hub.handler?.(produce(jobStream("7742"), 1, "booting agent"), p.conn);
+  assertEquals(correlation.count(), 0, "the stream did NOT link — the instance was not resolvable at produce time");
+
+  // The old producer connection blips before a later produce could retry the link. A frame drives
+  // #reconcile → it must defer to the engine (job still parked) rather than archive on presence.
+  registry.remove("conn-old");
+  const other = connect("cons", registry);
+  hub.handler?.(grant(0), other.conn);
+  await tick(); // let the fire-and-forget engine reconcile settle
+  assertEquals(
+    service.transcriptOf(jobStream("7742")),
+    undefined,
+    "an unlinked-but-still-parked job is NOT archived on disconnect",
+  );
+  assertEquals(service.liveFallback(jobStream("7742"))?.ring !== undefined, true, "its transcript is still live");
+
+  // The worker resumes on a NEW connection; the instance now resolves → the late link finally lands.
+  byConnection.set("conn-new", "worker-R");
+  const p2 = connect("conn-new", registry);
+  hub.handler?.(produce(jobStream("7742"), 1, "resumed output"), p2.conn);
+  assertEquals(correlation.jobKeysFor("worker-R"), ["7742"], "the late link succeeds on reconnect once the instance resolves");
+
+  // The job genuinely ends: the engine park vanishes → the backstop pass completes + archives it.
+  parked = false;
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-R"), [], "the ended job is released");
+  assertEquals(service.transcriptOf(jobStream("7742"))?.status, "completed", "and its transcript is archived");
+  service.teardown();
+});
+
+test("#708 periodic backstop covers an UNLINKED job stream: an unlinked-but-parked disconnect that never reconnects is completed once the engine park ends", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  // Same register/produce race as #691: the connection→instance map is empty, so #link leaves the
+  // job stream UNLINKED. The producer then drops while the engine job is still parked, so the
+  // disconnect path keeps the stream live and clears `state.producer` (so #reconcile does not
+  // re-trigger). Critically the worker NEVER reconnects — no later `produce` ever links it. The
+  // periodic backstop is now the ONLY actor that can retire it, so it must include unlinked job
+  // streams in its reconcile snapshot; otherwise the stream leaks live forever once the engine job
+  // becomes terminal.
+  const byConnection = new Map<string, string>();
+  let parked = true;
+  const resolveElementInstance = (jobKey: string) =>
+    Promise.resolve(parked && jobKey === "7708" ? "ei-7708" : undefined);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection, {
+    resolveElementInstance,
+  });
+  const p = connect("conn-old", registry);
+  hub.handler?.(produce(jobStream("7708"), 1, "booting agent"), p.conn);
+  assertEquals(correlation.count(), 0, "the stream did NOT link — the instance was not resolvable at produce time");
+
+  // Producer blips; the disconnect engine-reconcile keeps the still-parked stream live and clears
+  // the producer so #reconcile will not revisit it on later frames.
+  registry.remove("conn-old");
+  const other = connect("cons", registry);
+  hub.handler?.(grant(0), other.conn);
+  await tick();
+  assertEquals(
+    service.transcriptOf(jobStream("7708")),
+    undefined,
+    "an unlinked-but-still-parked job is NOT archived on disconnect",
+  );
+
+  // The engine job genuinely ends. With NO reconnect to link it, only the periodic backstop can
+  // retire it — and it must, even though the stream is unlinked.
+  parked = false;
+  await service.reconcileEngineCorrelations();
+  assertEquals(
+    service.transcriptOf(jobStream("7708"))?.status,
+    "completed",
+    "the periodic backstop completes an unlinked job stream once the engine park disappears",
+  );
+  assertEquals(service.liveFallback(jobStream("7708")), undefined, "and its live ring is retired");
+  service.teardown();
+});
+
+test("#691 engine-owned disconnect: a transient engine read at disconnect never falsely completes; the backstop retries", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-T"]]);
+  // The disconnect-time engine read throws (unavailable). A transient fault must be treated as
+  // "unknown — keep it linked", NEVER as "job gone": the stream stays live until a later pass resolves.
+  let failing = true;
+  let gone = false;
+  const resolveElementInstance = () => {
+    if (failing) return Promise.reject(new Error("engine unavailable"));
+    return Promise.resolve(gone ? undefined : "ei-T");
+  };
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection, {
+    resolveElementInstance,
+  });
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("kT"), 1, "x"), p.conn);
+
+  registry.remove("prod");
+  const other = connect("cons", registry);
+  hub.handler?.(grant(0), other.conn);
+  await tick(); // the engine read rejects → the stream must stay linked, not complete
+  assertEquals(correlation.jobKeysFor("worker-T"), ["kT"], "a transient engine failure leaves the job linked");
+  assertEquals(service.transcriptOf(jobStream("kT")), undefined, "and its transcript is NOT archived");
+
+  // The engine recovers and now reports the job gone: the periodic backstop pass completes it.
+  failing = false;
+  gone = true;
+  await service.reconcileEngineCorrelations();
+  assertEquals(correlation.jobKeysFor("worker-T"), [], "the backstop pass releases the ended job");
+  assertEquals(service.transcriptOf(jobStream("kT"))?.status, "completed", "and archives its transcript");
+  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

@@ -254,15 +254,18 @@ export interface RelayTranscriptServiceOptions {
   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).
+   * registry's {@link PresenceRegistry.isInstanceLive}. Since #691 the disconnect-driven reconcile
+   * defers to the engine job-state (the poller-owned completion authority) whenever an engine view
+   * ({@link resolveElementInstance}) is wired, so this presence signal is consulted ONLY as the
+   * engine-less fallback: on a host with no engine read-model (or a non-job stream — no jobKey, so
+   * nothing for the engine to reconcile against; an unlinked *job* stream still has a jobKey and DOES
+   * reconcile against the engine since #691) it spares 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). A true worker-exit still completes (presence has dropped the instance → false).
+   * Omitted (`() => false`, the static default) → the prior always-complete-on-disconnect behaviour in
+   * that fallback path.
    */
   readonly isInstanceLive?: (instance: string) => boolean;
   /**
@@ -725,27 +728,56 @@ export class RelayTranscriptService {
   }
 
   /**
-   * Flush + complete every ephemeral stream whose producer connection is no longer live (the S1
-   * registry dropped it on close or liveness timeout), and release its job correlation (H6, #149).
-   * Lazy, like the relay hub's own dead-subscriber prune: it runs on each inbound frame, and shutdown
-   * covers the quiescent tail via {@link teardown}. The correlation release is store-independent (it
-   * runs even for an unpersisted relay), so a dropped worker's `jobKeys` always clear.
+   * Reconcile every ephemeral stream whose producer connection is no longer live (the S1 registry
+   * dropped it on close or liveness timeout). For a job stream with an engine view wired this
+   * defers the completion decision to the engine job-state (#691) — the poller-owned authority —
+   * regardless of whether the stream is linked yet (an unlinked job stream can still be mid-reconnect
+   * on the register/produce race), so a mid-job reconnect never archives a still-active job; for an
+   * engine-less host (or a non-job stream with no engine job to reconcile against) it flushes +
+   * completes the ephemeral stream and releases its correlation (H6, #149), with
+   * presence liveness (#689/#690) sparing a still-live instance as the only fallback signal. Lazy, like
+   * the relay hub's own dead-subscriber prune: it runs on each inbound frame, and shutdown covers the
+   * quiescent tail via {@link teardown}. The correlation release is store-independent (it runs even for
+   * an unpersisted relay), so a dropped worker's `jobKeys` always clear.
    */
   #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.
+        // Producer connection gone. Normally that means the job it was relaying ended — 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). Inferring job-end from the
+        // relay-connection layer (the old presence heuristic, #690) conflates two independent liveness
+        // signals (engine lease vs. WS connection); the authoritative one is the engine job-state the
+        // poller already reconciles (#691).
+        if (this.#resolveElementInstance !== undefined && jobKeyOfStream(stream) !== undefined) {
+          // Engine/poller-owned completion (#691): drop the dead producer so `#reconcile` does not
+          // re-trigger on every subsequent frame, then reconcile THIS stream against the engine's view
+          // of its job (fire-and-forget — the sync frame handler must not await an engine read). A
+          // reconnected worker's job is still parked → kept live (the reconnect's next `produce`
+          // re-attributes the live connection via `#observe`); a genuine exit's job is gone →
+          // completed + archived. The periodic {@link reconcileEngineCorrelations} pass is the backstop
+          // if this read faults transiently. Presence liveness is no longer consulted here — the
+          // engine job-state is the sole completion authority whenever an engine view is wired.
+          //
+          // NB: this deliberately does NOT require `state.linked`. A job stream can still be UNLINKED
+          // during the documented register/produce race (the producer's presence instance was not yet
+          // resolvable at `produce` time, so `#link` deferred). Gating the engine path on `linked`
+          // would fall an unlinked-but-engine-wired job through to the presence fallback below and
+          // archive a still-parked job mid-reconnect — the very heuristic #691 removes. The engine is
+          // resolvable by jobKey alone (as at link time), so defer to it regardless of `linked`;
+          // `#unlink` inside `completeStream` stays a no-op for a stream that never linked.
+          state.producer = undefined;
+          void this.#reconcileStreamAgainstEngine(stream).catch((err: unknown) => {
+            this.#log.warn("agentic relay disconnect engine-reconcile failed", { stream, err: String(err) });
+          });
+          continue;
+        }
+        // Engine-less fallback (no engine view wired — e.g. an engine-less host, or a non-job stream
+        // with no engine job to reconcile against): presence-liveness spares a still-live
+        // instance's stream (#689/#690) and a truly-gone instance completes. Presence remains a
+        // completion signal ONLY in this degraded path where there is no engine job-state to consult —
+        // never the sole authority on the engine-wired path above. (A job stream with an engine view
+        // wired always took the engine path above, linked or not — it never reaches here.)
         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);
@@ -756,58 +788,98 @@ 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
+   * Defensive engine-reconcile safety net (#661): release any job stream — linked OR unlinked (#708) —
+   * 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
+   * path uses at #544) whether each 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.
+   * and merely went quiet. It covers UNLINKED job streams too (#708): the disconnect path (#691)
+   * can leave a job stream unlinked-but-still-parked with no producer, and jobKey alone resolves
+   * terminality, so this backstop is the only actor that can retire one whose worker never reconnects.
    *
    * 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
+   * given job is treated as "unknown — keep it" (never a false release of a genuinely active
+   * job). The job-stream 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 }[] = [];
+    if (this.#resolveElementInstance === undefined) return;
+    // Snapshot the job-stream ids BEFORE any await so a concurrent completion (a terminal lifecycle
+    // event, a supersede, or a disconnect-triggered engine reconcile landing mid-pass) cannot corrupt
+    // iteration; the per-stream helper re-reads live state, so a job released between snapshot and
+    // resolution is not double-completed.
+    const streams: 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 });
+      if (state.completed) continue;
+      if (jobKeyOfStream(stream) === undefined) continue;
+      // Include UNLINKED job streams too (#708). The disconnect path (#691) routes an unlinked
+      // job stream through the engine reconcile and clears `state.producer`, so if the engine
+      // reports "still parked" at disconnect (or the read faults transiently) and the worker never
+      // reconnects to `produce` a link, this periodic pass is the ONLY actor left that can retire
+      // it. jobKey alone resolves terminality (as at link time), so gating this snapshot on
+      // `state.linked` would leak such a stream live forever once its engine job becomes terminal.
+      streams.push(stream);
     }
-    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);
+    for (const stream of streams) await this.#reconcileStreamAgainstEngine(stream);
+  }
+
+  /**
+   * Reconcile ONE `job:<jobKey>` stream against the engine's view of its job (the poller-owned
+   * completion authority, #691). Asks the engine read model (the {@link ElementInstanceResolver} the
+   * #544 link path uses) whether the job is still parked: still parked → genuinely active, kept live;
+   * gone → ended (a clean completion whose terminal lifecycle event was missed, or an unclean exit) →
+   * released + its transcript flushed/archived. This is the single canonical engine-reconcile step,
+   * shared by BOTH the periodic safety-net pass ({@link reconcileEngineCorrelations}) and the
+   * disconnect-driven `#reconcile` — so a producer disconnect no longer completes a stream by inferring
+   * job-end from relay-connection/presence liveness (#689/#690), but by the authoritative engine
+   * job-state. A no-op with no resolver wired, and a resolver THROW / REJECTION is treated as
+   * "unknown — keep it" so a transient engine read never falsely releases a genuinely active
+   * job (a later pass, or the terminal lifecycle event, releases it). Re-reads live state before
+   * completing so a job released between the read and the completion is not double-completed.
+   *
+   * Does NOT require `state.linked`: the disconnect path (#691) also routes an UNLINKED job stream
+   * here (a job stream whose link deferred on the register/produce race), so the engine — not the
+   * link flag — owns its completion. The engine resolves by jobKey alone (as at link time); an
+   * unlinked stream the engine says is gone is still flushed/archived, and `#unlink` inside
+   * `completeStream` stays a no-op for it.
+   */
+  async #reconcileStreamAgainstEngine(stream: string): Promise<void> {
+    const resolve = this.#resolveElementInstance;
+    if (resolve === undefined) return;
+    const before = this.#streams.get(stream);
+    if (before === undefined || before.completed) return;
+    const jobKey = jobKeyOfStream(stream);
+    if (jobKey === undefined) return;
+    const processInstanceKey = this.#correlation()?.resolve?.(jobKey)?.processInstanceKey;
+    let activeKey: string | undefined;
+    try {
+      activeKey = await resolve(jobKey, processInstanceKey);
+    } catch (err) {
+      // A transient engine read failure must NOT be read as "job gone" — keep the stream live; a
+      // later pass (or the terminal lifecycle event) releases it. Advisory, never a false release.
+      this.#log.warn("agentic relay engine-reconcile read failed — keeping stream live", {
+        stream,
+        jobKey,
+        err: String(err),
+      });
+      return;
     }
+    // A live JOB park (a resolved element-instance key) means the job is genuinely active — keep it.
+    // This is what spares a mid-job RECONNECT: the harness still holds the engine lease, so the job is
+    // still parked even though the old producer connection dropped.
+    if (activeKey !== undefined) return;
+    // 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) return;
+    this.#log.info("agentic relay engine-reconcile released a stale correlation", { stream, jobKey });
+    this.completeStream(stream);
   }
 
   /**
@@ -886,10 +958,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.
+        // #689/#691: is the producing worker instance still live on ANY connection? Since #691 the
+        // disconnect-driven reconcile decides completion by the engine job-state (below) whenever the
+        // element-instance resolver is wired; this presence signal is the engine-LESS fallback that
+        // spares a mid-job RECONNECT's still-active stream where no engine view is available. Read per
+        // call for the same mount-order independence as the resolvers around it.
         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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.174.1",
+  "version": "0.175.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",