@nanobpm/nano-workforce 0.182.2 → 0.182.3

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.182.3](https://github.com/nanobpm/nano-workforce/compare/v0.182.2...v0.182.3) (2026-09-06)
+
+### Bug Fixes
+
+* cockpit historical transcript replay 404s through console gateway (encoded slash in stream-id path) ([#750](https://github.com/nanobpm/nano-workforce/issues/750)) ([8dd5e61](https://github.com/nanobpm/nano-workforce/commit/8dd5e619d664a50f513347f3b6f090d190495070)), closes [#744](https://github.com/nanobpm/nano-workforce/issues/744) [#744](https://github.com/nanobpm/nano-workforce/issues/744)
+
 ## [0.182.2](https://github.com/nanobpm/nano-workforce/compare/v0.182.1...v0.182.2) (2026-09-04)
 
 ### Bug Fixes

package/app/agentic/cockpit/mount.test.ts

@@ -70,12 +70,14 @@ function installEnv(fetchImpl: (url: string) => Promise<unknown>): () => void {
 
 const SUPPLY = { leaves: [], correlations: [] };
 
-/** A fetch stub answering the supply poll, the past-sessions list, and a single-stream replay. */
+/** A fetch stub answering the supply poll, the past-sessions list, and a single-stream replay. The
+ * replay READ is matched by its `stream` query param — the proxy-safe form (#744) the deployed
+ * client builds; a slash-bearing id must never appear as a path segment. */
 function fetchStub(replay?: unknown) {
   return (url: string): Promise<unknown> => {
     const ok = (body: unknown) => Promise.resolve({ ok: true, status: 200, json: async () => body });
     if (url.includes("/supply")) return ok(SUPPLY);
-    if (replay !== undefined && /\/transcripts\/[^/]+$/.test(url)) return ok(replay);
+    if (replay !== undefined && /[?&]stream=/.test(url)) return ok(replay);
     if (url.includes("/transcripts")) return ok({ sessions: [] });
     return Promise.resolve({ ok: false, status: 404, json: async () => ({}) });
   };
@@ -160,3 +162,54 @@ test("replay renders a past session's transcript — never a raw nwfTranscriptEv
     restore();
   }
 });
+
+// #744 — the deployed cockpit's replay READ must be proxy-safe: the stream id rides the QUERY
+// (`?stream=`), never a path segment. A worker-instance stream id contains a real `/`
+// (`34:<instance>/<jobKey>`); the console gateway decodes an encoded %2F in a PATH segment back
+// to `/` before the app routes, splitting the id into an extra segment → 404 {"error":"no such
+// operation"} → replayInto's fetch throws → the terminal region renders empty ("nothing").
+test("#744: replay fetches the proxy-safe ?stream= query form — a slash-bearing id never lands in a path segment", async () => {
+  const stream = "34:joshs-macbook-pro-copilot-3d6ee882/13859";
+  const replay = {
+    stream,
+    from: 0,
+    gap: false,
+    nextOffset: 1,
+    entries: [{ offset: 0, chunk: envChunk("message", { role: "user", text: "past session bytes" }) }],
+  };
+  const urls: string[] = [];
+  const stub = fetchStub(replay);
+  const restore = installEnv((url) => {
+    urls.push(url);
+    return stub(url);
+  });
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    // Dispose in a finally: mountCockpit auto-starts a poll whose next-tick timer (refreshMs) is a
+    // live handle — a mid-test assertion failure that skipped dispose would hold the event loop
+    // open and hang the whole test runner.
+    try {
+      await handle.replay(stream);
+
+      // The auto-started supply poll and the past-sessions list also hit the wire; the READ fetch is
+      // the only one carrying the stream id (in either URL form — that's what's under test).
+      const readUrl = urls.find((u) => u.includes(encodeURIComponent(stream)) || u.includes(stream));
+      assert(readUrl !== undefined, `the replay fetched a transcript read URL for the stream (saw: ${urls.join(", ")})`);
+      const parsed = new URL(readUrl);
+      // The pathname STAYS the collection route: no %-encoded (or raw) slash-bearing id segment the
+      // gateway peel could split — this is the structural fix for the whole failure class, not just
+      // this one stream shape.
+      assertEquals(parsed.pathname, "/app/api/agentic/transcripts");
+      assertEquals(parsed.searchParams.get("stream"), stream, "the slash-bearing id round-trips intact as a query value");
+      // And the fetched bytes still render through the derive path.
+      const host = document.querySelector('[data-terminal="host"]');
+      assert((host?.textContent ?? "").includes("past session bytes"), "the past session rendered");
+      assertEquals(document.querySelector(".cockpit-terminal")?.getAttribute("data-terminal-mode"), "replay");
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});

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

@@ -61,7 +61,11 @@ export interface SupplyCockpitEnv {
    */
   readonly fetchTranscripts?: (instance?: string) => Promise<TranscriptListReport>;
   /**
-   * Fetches a stored transcript's bytes (`GET /agentic/transcripts/{stream}`) for static replay.
+   * Fetches a stored transcript's bytes for static replay. Production wiring hits the proxy-safe
+   * query form `GET /agentic/transcripts?stream=<id>&from=<n>` (#744 — see `transcriptReadUrlFor`
+   * in app/agentic/transcript-url.ts and its browser twin in pages/cockpit/mount.js): a
+   * slash-bearing stream id in a PATH segment (`GET /agentic/transcripts/{stream}`) is split by
+   * gateway proxies that decode %2F before routing, 404ing the read.
    * Required for the "past sessions" replay to work; must be provided together with {@link fetchTranscripts}.
    */
   readonly fetchTranscript?: (stream: string, from?: number) => Promise<TranscriptDataReport>;

package/app/agentic/transcript-read.ts

@@ -15,9 +15,10 @@
 // unit-testable on the injected env (Node, no browser), and never touches the engine or a BPMN flow.
 
 import type { TranscriptChunk, TranscriptRing, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
-import type { AgenticTranscript, AgenticTranscriptData } from "../../nano-generated/api-io.d.ts";
+import type { AgenticTranscript, AgenticTranscriptData, ErrorBody } from "../../nano-generated/api-io.d.ts";
 import { type CorrelationRegistry, jobKeyOfStream } from "./correlation.ts";
 import type { AgenticCorrelationStore } from "./correlation-store.ts";
+import type { RelayTranscriptService } from "./families/relay.family.ts";
 import { utf8ByteLength } from "./transcript-events.ts";
 
 /** Total captured bytes across a set of retained chunks (UTF-8, the on-the-wire terminal encoding). */
@@ -242,3 +243,47 @@ export function readTranscriptFrom(
   if (fields.host !== undefined) out.host = fields.host;
   return out;
 }
+
+/** The single-stream read result both transcript READ routes share (#744): the bytes on 200, the
+ * same 400 (malformed `from`) / 404 (no such stream, or no service mounted) outcomes on failure. */
+export type SingleTranscriptResult =
+  | { status: 200; body: AgenticTranscriptData }
+  | { status: 400; body: ErrorBody }
+  | { status: 404; body: ErrorBody };
+
+/**
+ * The ONE canonical single-stream transcript read, shared by BOTH routes that serve it (#744):
+ * `GET /agentic/transcripts?stream=<id>&from=<n>` (the proxy-safe QUERY form the cockpit clients
+ * build — a gateway that peels one percent-encoding layer before routing splits an encoded slash
+ * in a PATH segment into an extra segment and 404s, while a query value survives intact) and
+ * `GET /agentic/transcripts/{stream}` (the legacy path form the worker-emitted `transcriptUrl`
+ * resolves — safe there because `job:<jobKey>` ids structurally never contain a slash). One
+ * implementation so the two addressings can never answer differently for the same stream/from.
+ */
+export function readSingleTranscript(
+  stream: string,
+  from: number | undefined,
+  service: RelayTranscriptService | undefined,
+  correlation: CorrelationRegistry | undefined,
+): SingleTranscriptResult {
+  const offset = from ?? 0;
+  if (!Number.isSafeInteger(offset) || offset < 0) {
+    return { status: 400, body: { error: "invalid from: expected a non-negative integer offset" } };
+  }
+  if (!service) {
+    // No relay/transcript service mounted at all - nothing to replay.
+    return { status: 404, body: { error: "no transcript for stream" } };
+  }
+  const data = readTranscriptFrom(
+    stream,
+    offset,
+    service.store,
+    correlation,
+    service.correlationStore,
+    service.liveFallback(stream),
+  );
+  if (data === undefined) {
+    return { status: 404, body: { error: "no transcript for stream" } };
+  }
+  return { status: 200, body: data };
+}

package/app/agentic/transcript-url.test.ts

@@ -7,6 +7,7 @@ import { jobStream } from "./correlation.ts";
 import {
   TRANSCRIPT_URL_BASE_VAR,
   TRANSCRIPT_URL_VAR,
+  transcriptReadUrlFor,
   transcriptUrlBaseFor,
   transcriptUrlForJob,
 } from "./transcript-url.ts";
@@ -33,3 +34,48 @@ test("derivation: transcriptUrlForJob is exactly transcriptUrlBaseFor + jobStrea
   const jobKey = "job-abc";
   assertEquals(transcriptUrlForJob(jobKey, BASE), `${transcriptUrlBaseFor(BASE)}${jobStream(jobKey)}`);
 });
+
+// #744 — the proxy-safe single-stream READ form. A worker-instance stream id CONTAINS a slash
+// (`34:<instance>/<jobKey>`); the Nano Console gateway proxy peels exactly one percent-encoding
+// layer off the request before the app routes it, so an encoded slash (%2F) in a PATH segment
+// arrives as a real / and splits the id into an extra segment — the app matches no route and
+// answers 404 {"error":"no such operation"}. Carrying the id as a QUERY value makes the read
+// structurally immune: a / is legal inside a query value, encoded or not.
+const SLASH_STREAM = "34:joshs-macbook-pro-copilot-3d6ee882/13859";
+const ENDPOINT = `${BASE}/app/api/agentic/transcripts`;
+
+/** Non-empty path-segment count of a URL — what a route matcher counts. */
+function pathSegments(u: string): number {
+  return new URL(u).pathname.split("/").filter((s) => s !== "").length;
+}
+
+test("transcriptReadUrlFor: the stream id rides the query, never a path segment (#744)", () => {
+  const url = new URL(transcriptReadUrlFor(ENDPOINT, SLASH_STREAM));
+  assertEquals(url.pathname, "/app/api/agentic/transcripts");
+  assertEquals(url.searchParams.get("stream"), SLASH_STREAM);
+});
+
+test("transcriptReadUrlFor: an explicit from offset appends as a query param", () => {
+  const url = new URL(transcriptReadUrlFor(ENDPOINT, "job:6494", 42));
+  assertEquals(url.searchParams.get("stream"), "job:6494");
+  assertEquals(url.searchParams.get("from"), "42");
+});
+
+test("#744 failure class: a gateway peel of one encoding layer breaks an encoded slash in a PATH segment but not a query value", () => {
+  // The legacy path form matches the `/app/api/agentic/transcripts/{stream}` route (5 segments)
+  // ONLY while the %2F stays encoded.
+  const pathForm = `${ENDPOINT}/${encodeURIComponent(SLASH_STREAM)}`;
+  assertEquals(pathSegments(pathForm), 5);
+  // The gateway peels exactly one percent-encoding layer before the app routes (#744 evidence):
+  // %2F becomes a real /, the app sees 6 segments, no route matches → 404 → the cockpit's replay
+  // fetch throws and the terminal region renders empty.
+  assertEquals(pathSegments(decodeURIComponent(pathForm)), 6);
+
+  // The query form is immune to the SAME peel: the pathname stays the collection route (4
+  // segments) before and after decoding, and the slash-bearing id round-trips intact.
+  const queryForm = transcriptReadUrlFor(ENDPOINT, SLASH_STREAM);
+  assertEquals(pathSegments(queryForm), 4);
+  const peeled = new URL(decodeURIComponent(queryForm));
+  assertEquals(pathSegments(peeled.href), 4);
+  assertEquals(peeled.searchParams.get("stream"), SLASH_STREAM);
+});

package/app/agentic/transcript-url.ts

@@ -48,7 +48,36 @@ export function transcriptUrlBaseFor(base: string = publicBaseUrl()): string {
  * The full durable transcript URL for a completed job's `jobKey` — the value a worker emits on
  * {@link TRANSCRIPT_URL_VAR}. Derived from {@link transcriptUrlBaseFor} + {@link jobStream} so it can
  * never disagree with the base the dispatcher seeds or the endpoint route it resolves to.
+ *
+ * The path-segment form is proxy-safe HERE because a `job:<jobKey>` id structurally never contains a
+ * slash (the jobKey is an engine key) — the #744 gateway-peel failure only bites slash-bearing ids.
+ * Any client that reads an ARBITRARY stream (e.g. the cockpit's past-session replay, whose
+ * worker-instance ids look like `34:<instance>/<jobKey>`) MUST use {@link transcriptReadUrlFor}
+ * instead.
  */
 export function transcriptUrlForJob(jobKey: string, base: string = publicBaseUrl()): string {
   return `${transcriptUrlBaseFor(base)}${jobStream(jobKey)}`;
 }
+
+/**
+ * The proxy-safe single-stream READ URL (#744): `<transcriptsEndpoint>?stream=<id>[&from=<n>]` —
+ * the query form of `GET /agentic/transcripts` (operation `listAgenticTranscripts`), answering with
+ * the same bytes the legacy `GET /agentic/transcripts/{stream}` path form serves.
+ *
+ * The stream id rides a QUERY value, never a path segment: the Nano Console gateway proxy peels
+ * exactly one percent-encoding layer before the app routes, so an encoded slash (%2F) in a PATH
+ * segment arrives as a real / and splits a slash-bearing id (`34:<instance>/<jobKey>`) into an extra
+ * segment — no route matches and the read 404s. A / inside a query value is never a separator, so
+ * this form survives the peel intact (the whole failure class, not just one stream shape).
+ *
+ * `transcriptsEndpoint` is the collection-route URL (`<base>/app/api/agentic/transcripts` — the same
+ * string the cockpit carries as its `transcriptsUrl`). This is the SINGLE SOURCE OF TRUTH for the
+ * query form: the cockpit's browser adapter (`pages/cockpit/mount.js`, which cannot import server
+ * modules) carries a hand-maintained twin of this builder — keep the two in lockstep.
+ */
+export function transcriptReadUrlFor(transcriptsEndpoint: string, stream: string, from?: number): string {
+  const url = new URL(transcriptsEndpoint);
+  url.searchParams.set("stream", stream);
+  if (from !== undefined) url.searchParams.set("from", String(from));
+  return url.href;
+}

package/app/contracts.ts

@@ -471,6 +471,14 @@ export const WIRE_CONTRACTS = {
       "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" }',
   },
+  "transcript.readUrl": {
+    category: "wire",
+    name: "transcript.readUrl",
+    owner: "app/agentic/transcript-url.ts",
+    semantics:
+      "The proxy-safe single-stream transcript READ URL (issue #744): `GET <base>/app/api/agentic/transcripts?stream=<id>&from=<n>` — the stream id rides a QUERY value, NEVER a path segment, because the Nano Console gateway proxy peels one percent-encoding layer before the app routes: an encoded slash (%2F) in a PATH segment arrives as a real / and splits a slash-bearing worker-instance id (`34:<instance>/<jobKey>`) into an extra segment, so the legacy `GET /app/api/agentic/transcripts/{stream}` route 404s behind the proxy (the cockpit past-session replay rendered empty). The path form stays served for back-compat and is proxy-safe ONLY for the slash-free `job:<jobKey>` ids it is seeded with (the worker-emitted `transcriptUrl` = `transcriptUrlBaseFor()` + `jobStream()`, a bare concatenation, must remain resolvable both directly and behind the proxy). ONE builder: `transcriptReadUrlFor()` in app/agentic/transcript-url.ts, served by ONE canonical read (`readSingleTranscript` in app/agentic/transcript-read.ts) shared by both routes; the browser adapter pages/cockpit/mount.js carries a hand-maintained twin (it cannot import server modules). Never put a stream id in a path segment again — do not re-declare a synonym scheme.",
+    shape: "GET <transcriptsEndpoint>?stream=<percent-encoded stream id>[&from=<non-negative integer offset>] → AgenticTranscriptData | ErrorBody",
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {

package/app/mcpToolSurface.ts

@@ -92,8 +92,14 @@ export const MCP_TOOL_COUNT_BUDGET = 60;
  * client must parse). The deployed surface measures ~78,962 bytes (issue #715); this ceiling forbids
  * meaningful growth so a fat new schema cannot silently re-inflate the surface past the harness
  * deferral point.
+ *
+ * RAISE PROVENANCE — 84_000 → 84_500 (#744): the proxy-safe single-stream transcript read adds two
+ * input-schema properties (`stream`/`from`) to `listAgenticTranscripts` plus one summary line on
+ * each of the two transcript tools, keeping the `?stream=` form discoverable from the tool surface
+ * alone (measured +219 bytes serialized, 83,824 → 84,043 — over the old ceiling's 176-byte
+ * headroom). Deliberate, documented growth — not schema fat.
  */
-export const MCP_SURFACE_BYTES_BUDGET = 84_000;
+export const MCP_SURFACE_BYTES_BUDGET = 84_500;
 
 /**
  * The eagerly-loaded curated subset MUST stay materially smaller than the full surface — otherwise it

package/openapi.yaml

@@ -3795,11 +3795,33 @@ paths:
       operationId: listAgenticTranscripts
       summary: List captured agent sessions (H3/#146) — the durable transcripts an ephemeral agent flushed
         on job completion, readable AFTER it exited. Optional filters by jobKey / process instance / plan /
-        time. Advisory read-only; never gates control flow. Feeds the cockpit "past sessions" view.
+        time. Also serves the proxy-safe single-stream READ form `?stream=` (#744). Advisory read-only;
+        never gates control flow. Feeds the cockpit "past sessions" view.
       security:
         - hookSecret: []
         - {}
       parameters:
+        - name: stream
+          in: query
+          required: false
+          schema:
+            type: string
+          description: >-
+            Single-stream READ form (#744, proxy-safe): when present, the response is that ONE
+            stream's transcript bytes (`AgenticTranscriptData` — the payload
+            `GET /agentic/transcripts/{stream}` serves), NOT the list, and the filters below are
+            ignored. The id rides a query value, so slash-bearing worker-instance ids
+            (`34:<instance>/<jobKey>`) survive gateways that decode %2F in path segments before
+            routing. Prefer this form over the path form behind any proxy.
+        - name: from
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+          description: Only with `stream` — resume from this offset (inclusive). Default 0. Rejected with 400
+            when supplied without `stream`.
         - name: jobKey
           in: query
           required: false
@@ -3846,13 +3868,17 @@ paths:
           description: Return only sessions created at or before this ISO-8601 instant.
       responses:
         "200":
-          description: The captured session list.
+          description: The captured session list — or, in the single-stream form (`?stream=`), that
+            stream's stored transcript bytes (#744).
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AgenticTranscriptList"
+                oneOf:
+                  - $ref: "#/components/schemas/AgenticTranscriptList"
+                  - $ref: "#/components/schemas/AgenticTranscriptData"
         "400":
-          description: A malformed filter (e.g. an unparseable since/until).
+          description: A malformed filter (e.g. an unparseable since/until), or — in the single-stream
+            form — a malformed `from` offset.
           content:
             application/json:
               schema:
@@ -3863,12 +3889,19 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+        "404":
+          description: Single-stream form only — no transcript exists for the given `stream`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /agentic/transcripts/{stream}:
     get:
       operationId: getAgenticTranscript
       summary: Fetch a stored transcript's bytes (H3/#146), range/offset-based so the cockpit terminal
-        replays it through the same resume-from-offset renderer it uses for a live stream. Advisory
-        read-only; never gates control flow.
+        replays it through the same resume-from-offset renderer it uses for a live stream. PATH form
+        of the single-stream read (back-compat; a slash-bearing id 404s behind a decoding proxy —
+        prefer the `?stream=` query form there, #744). Advisory read-only; never gates control flow.
       security:
         - hookSecret: []
         - {}
@@ -3878,7 +3911,9 @@ paths:
           required: true
           schema:
             type: string
-          description: The relay stream id to fetch (`job:<jobKey>` for a job stream).
+          description: The relay stream id to fetch (`job:<jobKey>` for a job stream). CAVEAT (#744) —
+            a gateway that decodes %2F in a path segment splits a slash-bearing id and this route
+            404s; such ids must use the `?stream=` query form. Slash-free ids are safe in either.
         - name: from
           in: query
           required: false

package/operations/getAgenticTranscript.ts

@@ -2,8 +2,12 @@
 //
 // Fetch a stored transcript's bytes, range/offset-based (?from=<offset>, default 0) so the cockpit
 // terminal replays a closed stream through the SAME resume-from-offset renderer it uses for a live one
-// (static playback of an exited agent). Sourced from the mounted relay/transcript service's
-// TranscriptStore over `app.data`, correlated best-effort via `app/agentic/correlation.ts`.
+// (static playback of an exited agent). The PATH form of the single-stream read, kept for back-compat
+// (the worker-emitted `transcriptUrl` and Explorer links resolve here — safe because `job:<jobKey>`
+// ids never contain a slash); proxy-exposed clients use the `?stream=` QUERY form on the collection
+// route instead (#744 — a gateway that decodes %2F in a path segment 404s this route). Both forms run
+// the ONE canonical read (`readSingleTranscript` in app/agentic/transcript-read.ts), so they can never
+// answer differently for the same stream/from.
 //
 // Advisory read-only (ADR 0056): it NEVER gates a BPMN sequence flow. Unknown stream -> 404; a
 // malformed `from` -> 400. Shared-secret guard mirrors getAgenticSupply (x-hook-secret when
@@ -11,7 +15,7 @@
 
 import { currentCorrelation } from "../app/agentic/correlation.ts";
 import { currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
-import { readTranscriptFrom } from "../app/agentic/transcript-read.ts";
+import { readSingleTranscript } from "../app/agentic/transcript-read.ts";
 import { envVar } from "../app/version.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
@@ -23,29 +27,5 @@ export default defineOperation("getAgenticTranscript", async ({ params, query, r
     return { status: 401, body: { error: "unauthorized" } };
   }
 
-  const from = query.from ?? 0;
-  if (!Number.isSafeInteger(from) || from < 0) {
-    return { status: 400, body: { error: "invalid from: expected a non-negative integer offset" } };
-  }
-
-  const service = currentRelayTranscriptService();
-  if (!service) {
-    // No relay/transcript service mounted at all - nothing to replay.
-    return { status: 404, body: { error: "no transcript for stream" } };
-  }
-
-  // Read the durable store first, falling back to the still-live relay ring (#486) so a `transcriptUrl`
-  // emitted by a job on a still-live multiplexing worker is readable before its ring is flushed.
-  const data = readTranscriptFrom(
-    params.stream,
-    from,
-    service.store,
-    currentCorrelation(),
-    service.correlationStore,
-    service.liveFallback(params.stream),
-  );
-  if (data === undefined) {
-    return { status: 404, body: { error: "no transcript for stream" } };
-  }
-  return { status: 200, body: data };
+  return readSingleTranscript(params.stream, query.from, currentRelayTranscriptService(), currentCorrelation());
 });

package/operations/listAgenticTranscripts.test.ts

@@ -167,3 +167,89 @@ test("shared-secret guard rejects a missing secret when configured", async () =>
     else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
   }
 });
+
+// #744 — the proxy-safe single-stream read form: `?stream=` on the collection route returns that
+// transcript's BYTES (the AgenticTranscriptData payload GET /{stream} serves), NOT the session
+// list. Worker-instance stream ids contain a slash (`34:<instance>/<jobKey>`); behind the console
+// gateway — which decodes %2F in a path segment back to a real / before the app routes — the
+// legacy path form 404s, so the cockpit reads a single stream through this query form.
+test("#744: ?stream= returns the single transcript's bytes for a slash-bearing id (not the list)", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  const store = currentRelayTranscriptService()?.store;
+  assert(store !== undefined);
+  const stream = "34:joshs-macbook-pro-copilot-3d6ee882/13859";
+  store.flush(
+    stream,
+    { since: () => ({ entries: [{ offset: 0, chunk: "aa" }, { offset: 1, chunk: "bb" }] }), nextOffset: 2 },
+    "ephemeral",
+  );
+  try {
+    const res = (await handler(input({ stream }), app)) as {
+      status: number;
+      body: {
+        stream: string;
+        from: number;
+        gap: boolean;
+        nextOffset: number;
+        chunkCount: number;
+        byteLength: number;
+        entries: Array<{ offset: number; chunk: string }>;
+      };
+    };
+    assertEquals(res.status, 200);
+    assertEquals(res.body.stream, stream);
+    assertEquals(res.body.from, 0);
+    assertEquals(res.body.gap, false);
+    assertEquals(res.body.nextOffset, 2);
+    assertEquals(res.body.chunkCount, 2);
+    assertEquals(res.body.byteLength, 4);
+    assertEquals(res.body.entries.map((e) => e.chunk), ["aa", "bb"]);
+  } finally {
+    relayFamily.teardown?.();
+  }
+});
+
+test("#744: ?stream= honors from, 404s an unknown stream, and 400s a malformed from", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  const store = currentRelayTranscriptService()?.store;
+  assert(store !== undefined);
+  store.flush(
+    "job:6494",
+    { since: () => ({ entries: [{ offset: 0, chunk: "aa" }, { offset: 1, chunk: "bb" }] }), nextOffset: 2 },
+    "ephemeral",
+  );
+  try {
+    const resume = (await handler(input({ stream: "job:6494", from: 1 }), app)) as {
+      status: number;
+      body: { from: number; chunkCount: number; entries: Array<{ chunk: string }> };
+    };
+    assertEquals(resume.status, 200);
+    assertEquals(resume.body.from, 1);
+    assertEquals(resume.body.entries.map((e) => e.chunk), ["bb"]);
+
+    const unknown = (await handler(input({ stream: "job:nope" }), app)) as { status: number };
+    assertEquals(unknown.status, 404);
+
+    const bad = (await handler(input({ stream: "job:6494", from: -1 }), app)) as { status: number };
+    assertEquals(bad.status, 400);
+  } finally {
+    relayFamily.teardown?.();
+  }
+});
+
+test("#744: ?stream= 404s (not an empty list) when no relay/transcript family is mounted", async () => {
+  relayFamily.teardown?.();
+  const res = (await handler(input({ stream: "job:1" }), app)) as { status: number };
+  assertEquals(res.status, 404);
+});
+
+test("#744: `from` without `stream` is a 400 (not a silently-ignored list read)", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  try {
+    const res = (await handler(input({ from: 0 }), app)) as { status: number; body: { error: string } };
+    assertEquals(res.status, 400);
+    assert(res.body.error.includes("stream"));
+  } finally {
+    relayFamily.teardown?.();
+  }
+});

package/operations/listAgenticTranscripts.ts

@@ -6,13 +6,19 @@
 // correlated via `app/agentic/correlation.ts` (best-effort — jobKey is always recovered from the stream
 // id, engine context only while the job is still live). Feeds the cockpit "past sessions" view.
 //
+// Also serves the proxy-safe single-stream READ form (#744): `?stream=<id>&from=<n>` switches this route
+// from the session list to that ONE stream's bytes — the same payload GET /{stream} serves, through the
+// same canonical read (`readSingleTranscript`). The id rides a QUERY value so a slash-bearing stream id
+// (`34:<instance>/<jobKey>`) survives gateway proxies that decode %2F in a PATH segment back to a real /
+// before routing (the cockpit replay 404'd silently behind the Nano Console).
+//
 // Advisory read-only (ADR 0056): it NEVER gates a BPMN sequence flow. Optional filters (jobKey / process
 // instance / plan / time) narrow the feed. The optional shared-secret guard mirrors getAgenticSupply:
 // when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header; unset -> open.
 
 import { currentCorrelation } from "../app/agentic/correlation.ts";
 import { currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
-import { listTranscripts, type TranscriptFilter } from "../app/agentic/transcript-read.ts";
+import { listTranscripts, readSingleTranscript, type TranscriptFilter } from "../app/agentic/transcript-read.ts";
 import { envVar } from "../app/version.ts";
 import type { AgenticTranscriptList } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
@@ -30,6 +36,18 @@ export default defineOperation("listAgenticTranscripts", async ({ query, req },
     return { status: 401, body: { error: "unauthorized" } };
   }
 
+  // #744: the single-stream READ form takes precedence — `?stream=` addresses ONE transcript's bytes,
+  // not the list, so the list filters below do not apply.
+  if (query.stream !== undefined) {
+    return readSingleTranscript(query.stream, query.from, currentRelayTranscriptService(), currentCorrelation());
+  }
+
+  // `from` addresses an offset WITHIN one stream, so it is only meaningful with `?stream=`. Reject it
+  // rather than silently returning the list, so the API can never quietly ignore a caller's intent.
+  if (query.from !== undefined) {
+    return { status: 400, body: { error: "invalid from: only valid together with stream" } };
+  }
+
   if (badInstant(query.since) || badInstant(query.until)) {
     return { status: 400, body: { error: "invalid since/until: expected an ISO-8601 instant" } };
   }

package/package.json

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

package/pages/cockpit/mount.js

@@ -468,7 +468,9 @@ function relaySocketFactory(url) {
  * @param {string} [opts.transcriptsUrl] — the captured-session list endpoint backing the always-on
  *   "past sessions" history + replay (default
  *   `new URL("../app/api/agentic/transcripts", import.meta.url).href`, module-anchored so it
- *   resolves to the app root `<appMount>/app/api/agentic/transcripts`, not the `/cockpit/` shell base).
+ *   resolves to the app root `<appMount>/app/api/agentic/transcripts`, not the `/cockpit/` shell
+ *   base). The per-session replay read uses the proxy-safe `?stream=` query form on this same URL
+ *   (#744 — never a `/…/<id>` path segment, which a decoding gateway splits on encoded slashes).
  * @returns a handle with `.dispose()`.
  */
 export function mountCockpit(host, opts = {}) {
@@ -718,7 +720,8 @@ export function mountCockpit(host, opts = {}) {
       abortTimer.unref?.();
       let res;
       try {
-        res = await fetch(`${transcriptsUrl}/${encodeURIComponent(stream)}`, { headers: jsonHeaders(), signal: controller.signal });
+        // Proxy-safe read URL (#744): the stream id rides the QUERY (?stream=), never a path segment.
+        res = await fetch(transcriptReadUrl(stream), { headers: jsonHeaders(), signal: controller.signal });
       } finally {
         clearTimeout(abortTimer);
       }
@@ -753,6 +756,25 @@ export function mountCockpit(host, opts = {}) {
     return url.href;
   }
 
+  // The proxy-safe single-stream READ URL (#744) — the browser twin of `transcriptReadUrlFor` in
+  // app/agentic/transcript-url.ts (mount.js cannot import the server module; keep the two in
+  // lockstep). The stream id rides a QUERY value, never a path segment: the console gateway peels
+  // one percent-encoding layer before the app routes, so an encoded slash (%2F) in a PATH segment
+  // arrives as a real / and splits a slash-bearing worker-instance id (`34:<instance>/<jobKey>`)
+  // into an extra segment — the app matches no route and answers 404, which left the past-session
+  // replay silently empty behind the proxy. A / inside a query value is never a separator.
+  //
+  // Mirrors the server SSOT's optional `from` offset (`transcriptReadUrlFor(endpoint, stream, from?)`):
+  // omitted -> no `from` param (read from the start); a numeric offset appends `&from=<n>` so a
+  // resume-from-offset replay can fetch from a non-zero position and the two twins stay structurally
+  // in lockstep.
+  function transcriptReadUrl(stream, from) {
+    const url = new URL(transcriptsUrl, location.href);
+    url.searchParams.set("stream", stream);
+    if (from !== undefined) url.searchParams.set("from", String(from));
+    return url.href;
+  }
+
   async function refreshPast(instance = routeInstance()) {
     // Single-flight: while one past-fetch is outstanding (including a hung one), skip starting another
     // so the supply poll can't stack pending fetches against a slow/unresponsive transcripts endpoint.