@nanobpm/nano-workforce 0.175.1 → 0.176.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.176.0](https://github.com/nanobpm/nano-workforce/compare/v0.175.2...v0.176.0) (2026-09-02)
+
+### Features
+
+* **agentic:** flush durable transcript on a worker phase:close event (fixes truncated tails) ([#711](https://github.com/nanobpm/nano-workforce/issues/711)) ([e02ff9b](https://github.com/nanobpm/nano-workforce/commit/e02ff9b4f8c2b7452dc40b0b8532736c5d418cc0)), closes [#710](https://github.com/nanobpm/nano-workforce/issues/710)
+
+## [0.175.2](https://github.com/nanobpm/nano-workforce/compare/v0.175.1...v0.175.2) (2026-09-02)
+
+### Bug Fixes
+
+* **abandon:** don't let the cancel-check deadlock a shell-less agent ([#678](https://github.com/nanobpm/nano-workforce/issues/678)) ([#709](https://github.com/nanobpm/nano-workforce/issues/709)) ([f5fed93](https://github.com/nanobpm/nano-workforce/commit/f5fed93bdd0e98cbb24f7dff4b0f9a650c235a69)), closes [#76](https://github.com/nanobpm/nano-workforce/issues/76) [#76](https://github.com/nanobpm/nano-workforce/issues/76)
+
 ## [0.175.1](https://github.com/nanobpm/nano-workforce/compare/v0.175.0...v0.175.1) (2026-09-02)
 
 ### Bug Fixes

package/app/abandon.test.ts

@@ -83,6 +83,32 @@ test("renderAbandonBrief embeds the concrete URL and the stop contract", () => {
   assertEquals(brief.includes("curl -fsS"), true);
 });
 
+test("renderAbandonBrief forbids delegating the check to a sub-agent (issue #678)", () => {
+  // A non-Claude agent (e.g. qwen) that hands this shell command to a shell-less
+  // `general-purpose` sub-agent deadlocks: the sub-agent has no shell, produces no
+  // output, and the worker's idle timeout kills the round. The brief must steer the
+  // agent to run the check inline with its OWN shell and never delegate it.
+  const brief = renderAbandonBrief("https://host/app/api/hooks/abandon?token=tok");
+  // Not merely that it *mentions* sub-agents/inline — it must explicitly PROHIBIT delegation, so a
+  // future edit that softened the brief into *encouraging* delegation would fail this test.
+  assertEquals(/do \*\*not\*\* delegate it to a\s+sub-?agent/i.test(brief), true, "explicitly forbids delegating to a sub-agent");
+  assertEquals(/inline/i.test(brief), true, "tells the agent to run it inline");
+});
+
+test("renderAbandonBrief degrades gracefully when the agent has no shell (issue #678)", () => {
+  // The check is ADVISORY over an airtight harness job-fence (issue #76 layer 2). An
+  // agent that cannot run a shell command at all must be told to SKIP and proceed
+  // rather than thrash/hang — the harness job-fence (issue #76 layer 2) still fences
+  // a cancelled run, so a skipped check degrades safely rather than promising full
+  // independent enforcement.
+  const brief = renderAbandonBrief("https://host/app/api/hooks/abandon?token=tok");
+  assertEquals(/skip this check/i.test(brief), true, "offers a skip path");
+  // Assert the actual anti-deadlock contract, not an explanatory word: a shell-less agent must be
+  // told its lack of a shell is NOT a failed check, and must be forbidden from stalling/hanging.
+  assertEquals(/not (a )?failed check/i.test(brief), true, "no shell is not treated as a failed check");
+  assertEquals(/never stall,.*hang/i.test(brief), true, "forbids stalling/hanging when it can't run curl");
+});
+
 test("prKeyForAbandonToken resolves a known token and rejects unknowns", async () => {
   const data = memData();
   await seedPr(data, "o/r#1", "tok", "converging");

package/app/abandon.ts

@@ -148,5 +148,18 @@ down), instead of silently printing an error body with exit 0.
   try to complete the job is EXPECTED after a cancel — do not treat it as an error to retry.
 - **Proceed** only when the command **succeeds** AND reports \`"abandoned": false\` — and re-check
   right before the push, since a cancel can land at any moment. Checking as late as possible keeps
-  the window tiny.`;
+  the window tiny.
+
+**Run this check yourself, inline, with your own shell tool.** Do **not** delegate it to a
+sub-agent, helper, or a separate "run this command" task: a sub-agent may have **no shell**, in which
+case it cannot run \`curl\`, produces no output, and the worker's idle timeout will kill the round.
+One inline \`curl\` in your own turn is all this needs.
+
+**Having no way to run a shell command at all is NOT a failed check — SKIP this check and proceed.**
+The "abort on non-zero exit" rule above is about \`curl\` *running and reporting* a torn-down run; it
+does **not** mean "abort because you have no shell to run \`curl\` with". This check is a best-effort
+optimisation, not a hard gate: the harness that runs your job also fences a cancelled run's
+completion, so a skipped check only widens a tiny race — it does not by itself create an orphaned
+run. Never stall, thrash, hang, or fail the round trying to run \`curl\` through a tool you do not
+have; a skipped check is strictly better than a hung one.`;
 }

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

@@ -16,7 +16,13 @@ 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 { encodeTranscriptEvent, type SqliteDb, TRANSCRIPT_SCHEMA_SQL } from "@nanobpm/agentic/transcript";
+import {
+  encodeTranscriptEvent,
+  type SqliteDb,
+  TRANSCRIPT_EVENT_MARKER,
+  TRANSCRIPT_EVENT_VERSION,
+  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";
@@ -551,6 +557,21 @@ test("#544 element-instance enrichment: an unresolved job (never parked) leaves
 const lifecycle = (stream: string, incarnation: number, phase: "open" | "completed" | "exited"): Frame =>
   produce(stream, incarnation, encodeTranscriptEvent({ kind: "lifecycle", phase, offset: 0 }));
 
+/**
+ * A `produce` frame carrying the harness's job-end `phase:"close"` transcript lifecycle marker
+ * (#710 / jwulf/c8ctl-plugin-nano#150) — the closing twin of the `phase:"open"` RELAY_OPEN_CHUNK the
+ * harness emits at relay-session open. The typed `encodeTranscriptEvent` cannot express the `close`
+ * phase (the agentic `LifecycleEvent` union is `open|completed|exited`), so the on-wire envelope is
+ * built through the SAME marker/version constants the encoder stamps — mirroring exactly what the
+ * harness's untyped `encodeTranscriptEvent({ kind: "lifecycle", phase: "close" })` puts on the wire,
+ * without a forked wire shape. */
+const closeMarker = JSON.stringify({
+  [TRANSCRIPT_EVENT_MARKER]: TRANSCRIPT_EVENT_VERSION,
+  kind: "lifecycle",
+  phase: "close",
+});
+const close = (stream: string, incarnation: number): Frame => produce(stream, incarnation, closeMarker);
+
 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();
@@ -607,6 +628,79 @@ test("#661 primary release: an `exited` lifecycle also releases; a non-terminal
   service.teardown();
 });
 
+test("#710 close release: a job-end `phase:close` marker flushes the durable transcript with ALL bytes (no truncated tail)", () => {
+  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 N job frames on a live connection → linked as active. It then goes idle after the
+  // job WITHOUT a supersede (no next job) and WITHOUT a disconnect (the channel persists across jobs),
+  // so the ONLY job-end signal is the harness's drained `phase:close` marker.
+  const N = 4;
+  for (let i = 0; i < N; i++) hub.handler?.(produce(jobStream("k1"), 1, `job-1 line ${i}`), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "the job is active while it runs");
+  assertEquals(service.transcriptOf(jobStream("k1")), undefined, "not flushed while the job runs");
+
+  // The job completes: the harness drains its outbound relay buffer and emits `phase:close` on the SAME
+  // live connection, then goes idle. Before #710 this was NOT a flush trigger — the durable transcript
+  // was snapshotted late (or not at all) by a later supersede/disconnect, truncating the tail. Now the
+  // close event flushes it deterministically at job-completion time.
+  hub.handler?.(close(jobStream("k1"), 1), p.conn);
+
+  assertEquals(correlation.jobKeysFor("worker-A"), [], "the finished job is released on the close marker");
+  assertEquals(correlation.count(), 0, "no phantom active job after close");
+
+  const meta = service.transcriptOf(jobStream("k1"));
+  assertEquals(meta?.status, "completed", "the job becomes a completed past session at close time");
+  // ALL N produced frames PLUS the close marker itself are in the durable transcript — no truncated
+  // tail (the close event rides the ring append before the release, like the #661 terminal path).
+  assertEquals(
+    service.reattach(jobStream("k1"), 0)?.entries.length,
+    N + 1,
+    "every relayed byte (and the close marker) is flushed — the tail is not truncated",
+  );
+  service.teardown();
+});
+
+test("#710 idempotent: a close then a duplicate close then a producer disconnect neither double-flushes nor throws", () => {
+  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);
+  hub.handler?.(close(jobStream("k1"), 1), p.conn);
+  const afterClose = service.reattach(jobStream("k1"), 0)?.entries.length;
+  assertEquals(service.transcriptOf(jobStream("k1"))?.status, "completed", "flushed on the first close");
+  assertEquals(correlation.count(), 0, "correlation released on the first close");
+
+  // A late DUPLICATE close (a harness retry, or a redelivered frame) is a no-op — the completed stream
+  // is terminal, so it neither re-flushes nor throws.
+  hub.handler?.(close(jobStream("k1"), 1), p.conn);
+  assertEquals(
+    service.reattach(jobStream("k1"), 0)?.entries.length,
+    afterClose,
+    "a duplicate close does not append or re-flush",
+  );
+
+  // The producer later disconnects (the belt-and-suspenders fallback). #reconcile runs on the next
+  // inbound frame; the already-completed stream is skipped, so the fallback neither double-flushes nor
+  // throws — the additive close trigger composes cleanly with the disconnect fallback.
+  registry.remove("prod");
+  const q = connect("other", registry);
+  hub.handler?.(produce(jobStream("k2"), 1, "unrelated"), q.conn);
+  assertEquals(
+    service.reattach(jobStream("k1"), 0)?.entries.length,
+    afterClose,
+    "the disconnect fallback does not re-flush the already-closed stream",
+  );
+  assertEquals(service.transcriptOf(jobStream("k1"))?.status, "completed", "still exactly one completed past session");
+  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();

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

@@ -24,6 +24,8 @@ 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 {
+  CORE_TRANSCRIPT_VOCAB,
+  mergeTranscriptVocab,
   parseTranscriptEvent,
   type SqliteDb,
   type TranscriptLifecycle,
@@ -32,6 +34,7 @@ import {
   TranscriptStore,
   type TranscriptStoreOptions,
   type TranscriptStream,
+  type TranscriptVocab,
 } from "@nanobpm/agentic/transcript";
 import type { Logger } from "@nanobpm/urban";
 import { currentCorrelation, type JobContext, type JobCorrelation, jobKeyOfStream } from "../correlation.ts";
@@ -128,17 +131,50 @@ function readProp(value: unknown, key: string): unknown {
   return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
 }
 
+/**
+ * The harness's job-end lifecycle phase (#710 / jwulf/c8ctl-plugin-nano#150): the closing twin of the
+ * `phase:"open"` `RELAY_OPEN_CHUNK` the harness emits at relay-session open. The harness emits it —
+ * through agentic's own `encodeTranscriptEvent`, never hand-rolled — right before `job.complete`/
+ * `job.fail`, once it has DRAINED its outbound relay buffer, so it is the deterministic "this job's
+ * bytes are all here, it is done" signal that supersede/disconnect only ever approximated.
+ */
+const HARNESS_CLOSE_PHASE = "close";
+
+/**
+ * The relay family's terminal-detection vocabulary: the ONE canonical transcript vocab, additively
+ * EXTENDED (via the sanctioned {@link mergeTranscriptVocab} extension point, never a forked parser) to
+ * ALSO classify the harness's job-end `phase:"close"` marker (#710). The agentic `LifecycleEvent`
+ * contract's phases are `open|completed|exited` — `close` is a fourth, job-scoped termination marker
+ * agentic 0.10.0 does not yet know, so the core `lifecycle` decoder drops it to a raw `stream-chunk`.
+ * This override recognizes it and maps it onto the contract's terminal `completed` phase, so
+ * {@link parseTranscriptEvent} classifies a close envelope as a terminal lifecycle WITHOUT a second
+ * wire shape. It is scoped to {@link isTerminalLifecycleChunk} (the correlation-release detector); the
+ * cockpit derive/read fold keeps using the CORE vocab, so the close chunk stays byte-faithful in the
+ * durable transcript and this remap never leaks into the derived view.
+ */
+const RELAY_TERMINAL_VOCAB: TranscriptVocab = mergeTranscriptVocab(CORE_TRANSCRIPT_VOCAB, {
+  lifecycle: (body, offset) => {
+    const phase = typeof body.phase === "string" ? body.phase : undefined;
+    if (phase === "open" || phase === "completed" || phase === "exited") return { kind: "lifecycle", offset, phase };
+    if (phase === HARNESS_CLOSE_PHASE) return { kind: "lifecycle", offset, phase: "completed" };
+    return 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.
+ * TERMINAL `lifecycle` event — the authoritative "job end" signal that flushes the durable transcript
+ * and releases correlation. Two shapes are terminal: the agent run's own `phase` `completed`/`exited`
+ * (#661), and the harness's drained job-end `phase:"close"` marker (#710), which
+ * {@link RELAY_TERMINAL_VOCAB} decodes onto the contract's `completed` phase. Anything else — raw
+ * terminal bytes, a non-envelope JSON value, a `phase: "open"` lifecycle, any other event kind — is
+ * not terminal. Reusing {@link parseTranscriptEvent} (with the additively-extended vocab) 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 });
+  const event = parseTranscriptEvent({ offset: 0, chunk }, RELAY_TERMINAL_VOCAB);
   return event.kind === "lifecycle" && (event.phase === "completed" || event.phase === "exited");
 }
 
@@ -516,8 +552,8 @@ export class RelayTranscriptService {
   }
 
   /** 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). */
+   * release on a terminal `lifecycle` event (#661/#710 — 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);
@@ -526,17 +562,23 @@ export class RelayTranscriptService {
   }
 
   /**
-   * 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.
+   * Primary job-end release (#661, #710): when a `produce` frame carries a terminal `lifecycle` event —
+   * the agent run's own `phase` `completed`/`exited` (#661), OR the harness's drained job-end
+   * `phase:"close"` marker (#710) — complete its stream so the worker's job⇄instance correlation is
+   * released, and the durable "past session" transcript is flushed, the moment the job ends. This runs
+   * 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, and its transcript would be snapshotted late → truncated
+   * tail). The `close` trigger is ADDITIVE — supersede + disconnect remain as belt-and-suspenders
+   * fallbacks for a harness that predates the close event or a crash that never sends one — and the
+   * `state.completed` guard below makes a close-then-later-disconnect (or a duplicate close) an
+   * idempotent no-op. 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} ({@link isTerminalLifecycleChunk}) — 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;

package/app/contracts.ts

@@ -463,6 +463,14 @@ export const WIRE_CONTRACTS = {
     shape:
       '{ nwfTranscriptEvent: 1, kind: "permission", phase: "request", callId: string, policy: "escalate"|"yolo", options: [{ optionId: string, name: string, kind: "allow-once"|"allow-always"|"reject-once"|"reject-always" }, ...Array<{ optionId: string, name: string, kind: "allow-once"|"allow-always"|"reject-once"|"reject-always" }>], toolName?: string, title?: string, reason?: string } | { nwfTranscriptEvent: 1, kind: "permission", phase: "resolution", callId: string, optionId: string, allowed: boolean, by?: "operator"|"auto" }',
   },
+  "transcript.lifecycleClose": {
+    category: "wire",
+    name: "transcript.lifecycleClose",
+    owner: "app/agentic/families/relay.family.ts",
+    semantics:
+      "The harness's job-end `phase:\"close\"` transcript `lifecycle` event (issue #710, harness half jwulf/c8ctl-plugin-nano#150) — the closing twin of the `phase:\"open\"` RELAY_OPEN_CHUNK the harness emits at relay-session open. The harness emits it on the `job:<jobKey>` relay stream through agentic's own `encodeTranscriptEvent` (never hand-rolled), right before `job.complete`/`job.fail` and AFTER draining its outbound relay buffer, so it is the deterministic \"all this job's bytes are here, it is done\" signal. The app recognizes it in `isTerminalLifecycleChunk` (relay.family.ts) to `completeStream()` — flush the durable past-session transcript and release job⇄instance correlation — at job-completion time, fixing the truncated-tail defect where the flush waited for a supersede/disconnect. `close` is NOT a core agentic `LifecycleEvent` phase (the contract's phases are open|completed|exited); the app decodes it via an ADDITIVE `mergeTranscriptVocab` extension (`RELAY_TERMINAL_VOCAB`) that maps it onto the terminal `completed` phase — never a forked wire shape, and scoped to the relay job-end detector so the cockpit derive (CORE vocab) keeps the close chunk byte-faithful. The `close` trigger is ADDITIVE: supersede + disconnect remain as fallbacks and the `state.completed` guard keeps a close-then-disconnect (or duplicate close) idempotent. Consume this ONE marker — do not re-declare a synonym or a second job-end signal.",
+    shape: '{ nwfTranscriptEvent: 1, kind: "lifecycle", phase: "close" }',
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {

package/package.json

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