@nanobpm/nano-workforce 0.195.2 → 0.197.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.197.0](https://github.com/nanobpm/nano-workforce/compare/v0.196.0...v0.197.0) (2026-10-01)
+
+### Features
+
+* **pages:** render every list as the card view ([#838](https://github.com/nanobpm/nano-workforce/issues/838)) ([47b9bad](https://github.com/nanobpm/nano-workforce/commit/47b9bad71fe999cd34e298a2c6f36ce796a402bb)), closes [#837](https://github.com/nanobpm/nano-workforce/issues/837)
+
+## [0.196.0](https://github.com/nanobpm/nano-workforce/compare/v0.195.2...v0.196.0) (2026-09-30)
+
+### Features
+
+* **cockpit:** 'Agent' link on active rows opens the cockpit focused on that process ([#834](https://github.com/nanobpm/nano-workforce/issues/834)) ([c9c07a3](https://github.com/nanobpm/nano-workforce/commit/c9c07a3886d065d407260c2dabe2abb410fc7d2d)), closes [#833](https://github.com/nanobpm/nano-workforce/issues/833)
+
 ## [0.195.2](https://github.com/nanobpm/nano-workforce/compare/v0.195.1...v0.195.2) (2026-09-30)
 
 ### Bug Fixes

package/app/agentic/cockpit/cockpit-route.test.ts

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
-import { parseCockpitRoute } from "./cockpit-route.ts";
+import { parseCockpitRoute, parseHostCockpitParam } from "./cockpit-route.ts";
 
 test("parses empty and main cockpit hashes as the main route", () => {
   assert.deepEqual(parseCockpitRoute(""), { kind: "main" });
@@ -19,3 +19,17 @@ test("empty worker and junk hashes fall back to the main route", () => {
   assert.deepEqual(parseCockpitRoute("#/elsewhere"), { kind: "main" });
   assert.deepEqual(parseCockpitRoute("#/cockpit/worker/%E0%A4%A"), { kind: "main" });
 });
+
+test("#833: parses a process-focus hash into the process route", () => {
+  assert.deepEqual(parseCockpitRoute("#/cockpit/process/2251799813685249"), { kind: "process", processInstanceKey: "2251799813685249" });
+  assert.deepEqual(parseCockpitRoute("#/cockpit/process/"), { kind: "main" });
+});
+
+test("#833: the host page's #/cockpit/<process_key> param (an 'Agent' grid link) focuses that process", () => {
+  assert.equal(parseHostCockpitParam("#/cockpit/2251799813685249"), "2251799813685249");
+  assert.equal(parseHostCockpitParam("#/cockpit/a%20b"), "a b");
+  assert.equal(parseHostCockpitParam("#/cockpit"), undefined);
+  assert.equal(parseHostCockpitParam("#/cockpit/"), undefined);
+  assert.equal(parseHostCockpitParam("#/overview/123"), undefined);
+  assert.equal(parseHostCockpitParam("#/cockpit/%E0%A4%A"), undefined);
+});

package/app/agentic/cockpit/cockpit-route.ts

@@ -1,17 +1,46 @@
-export type CockpitRoute = { readonly kind: "main" } | { readonly kind: "worker"; readonly instance: string };
+export type CockpitRoute =
+  | { readonly kind: "main" }
+  | { readonly kind: "worker"; readonly instance: string }
+  /** Focused on one process instance (#833) — the target of an "Agent" grid link. */
+  | { readonly kind: "process"; readonly processInstanceKey: string };
+
+function decodeSegment(raw: string): string | undefined {
+  if (raw === "") return undefined;
+  try {
+    const value = decodeURIComponent(raw);
+    return value === "" ? undefined : value;
+  } catch {
+    return undefined;
+  }
+}
 
 /** Parse the cockpit hash route. Unknown or malformed hashes fall back to the main list. */
 export function parseCockpitRoute(hash: string): CockpitRoute {
   const route = hash.startsWith("#") ? hash.slice(1) : hash;
-  if (route === "" || route === "/cockpit" || route === "/cockpit/") return { kind: "main" };
-  const prefix = "/cockpit/worker/";
-  if (!route.startsWith(prefix)) return { kind: "main" };
-  const raw = route.slice(prefix.length);
-  if (raw === "") return { kind: "main" };
-  try {
-    const instance = decodeURIComponent(raw);
-    return instance === "" ? { kind: "main" } : { kind: "worker", instance };
-  } catch {
-    return { kind: "main" };
+  const worker = "/cockpit/worker/";
+  if (route.startsWith(worker)) {
+    const instance = decodeSegment(route.slice(worker.length));
+    return instance === undefined ? { kind: "main" } : { kind: "worker", instance };
+  }
+  const process = "/cockpit/process/";
+  if (route.startsWith(process)) {
+    const processInstanceKey = decodeSegment(route.slice(process.length));
+    return processInstanceKey === undefined ? { kind: "main" } : { kind: "process", processInstanceKey };
   }
+  return { kind: "main" };
+}
+
+/**
+ * The process-instance key carried by the HOST page's `#/cockpit/<param>` route (#833). An "Agent" grid
+ * link (`{ kind: "page", page: "cockpit", keyField: "process_key" }`) navigates the host page — the
+ * cockpit embed is an iframe with its own hash — so the embed reads the param from its same-origin
+ * parent. Only a single, decodable segment counts; anything else is undefined (no focus).
+ */
+export function parseHostCockpitParam(hash: string): string | undefined {
+  const route = hash.startsWith("#") ? hash.slice(1) : hash;
+  const prefix = "/cockpit/";
+  if (!route.startsWith(prefix)) return undefined;
+  const raw = route.slice(prefix.length);
+  if (raw.includes("/")) return undefined;
+  return decodeSegment(raw);
 }

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

@@ -99,6 +99,7 @@ test("the rendered transcript region sits directly beneath the Workers — suppl
     const shell = document.querySelector(".cockpit-shell");
     const order = [...(shell?.children ?? [])].map((c: { className: string }) => c.className);
     assertEquals(order, [
+      "cockpit-focus",
       "cockpit-supply-region",
       "cockpit-terminal",
       "cockpit-past-region",
@@ -407,3 +408,393 @@ test("agent-history tool call with an empty-string elementId renders no empty ()
     restore();
   }
 });
+
+// #833 — an "Agent" grid link lands on the cockpit focused on ONE process instance. The agent may run
+// in a CHILD instance (call activity), so the focus resolves the engine AgentInstances whose ROOT is
+// the linked key and matches live job correlations against every instance in that tree.
+const PI_ROOT = "pi-root";
+const FOCUS_INSTANCE = {
+  agentInstanceKey: "ai-7",
+  status: "THINKING",
+  processInstanceKey: "pi-child",
+  rootProcessInstanceKey: PI_ROOT,
+  elementId: "implement-task",
+  creationDate: "2024-01-01T00:00:00Z",
+};
+const FOCUS_HISTORY = {
+  agentInstanceKey: "ai-7",
+  count: 1,
+  instance: FOCUS_INSTANCE,
+  records: [
+    {
+      historyItemKey: "h-0",
+      agentInstanceKey: "ai-7",
+      loopIteration: 0,
+      role: "ASSISTANT",
+      commitStatus: "COMMITTED",
+      content: [{ contentType: "TEXT", text: "working on the focused process" }],
+      toolCalls: [],
+    },
+  ],
+};
+
+function focusStub(opts: { correlations: unknown[]; transcripts?: unknown[]; replay?: unknown; seen?: string[] }) {
+  return (url: string): Promise<unknown> => {
+    opts.seen?.push(url);
+    const ok = (body: unknown) => Promise.resolve({ ok: true, status: 200, json: async () => body });
+    if (url.includes("/supply")) return ok({ leaves: [], workers: [], correlations: opts.correlations });
+    if (/\/agent-instances\/[^/?]+\/history/.test(url)) return ok(FOCUS_HISTORY);
+    if (url.includes("/agent-instances")) {
+      const root = url.includes(`rootProcessInstanceKey=${PI_ROOT}`);
+      return ok(root ? { count: 1, instances: [FOCUS_INSTANCE] } : { count: 0, instances: [] });
+    }
+    if (/[?&]stream=/.test(url)) return ok(opts.replay);
+    if (url.includes("/transcripts")) {
+      const mine = (opts.transcripts ?? []).filter((t) => url.includes(`processInstanceKey=${(t as { processInstanceKey: string }).processInstanceKey}`));
+      return ok({ count: mine.length, transcripts: mine });
+    }
+    return Promise.resolve({ ok: false, status: 404, json: async () => ({}) });
+  };
+}
+
+async function settle(): Promise<void> {
+  for (let i = 0; i < 20; i++) await new Promise((r) => setTimeout(r, 0));
+}
+
+test("#833: a process-focus route live-drills the worker running a job of a CHILD instance and shows its agent history", async () => {
+  const restore = installEnv(focusStub({ correlations: [{ jobKey: "j1", stream: "wk-a/j1", processInstanceKey: "pi-child" }] }));
+  (globalThis as { location: { hash: string } }).location.hash = `#/cockpit/process/${PI_ROOT}`;
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await settle();
+      assert((document.querySelector(".cockpit-focus")?.textContent ?? "").includes(PI_ROOT), "the focus banner names the process");
+      assertEquals(document.querySelector(".cockpit-terminal")?.getAttribute("data-terminal-mode"), "live");
+      assert(StubWebSocket.instances.length > 0, "a relay socket was opened for the focused job");
+      const transcript = document.querySelector('.cockpit-agent-transcript[data-agent-instance-key="ai-7"]');
+      assert((transcript?.textContent ?? "").includes("working on the focused process"), "the focused agent's history is shown");
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});
+
+test("#833: with no live job, the process focus replays the newest captured transcript of that process", async () => {
+  const replay = {
+    stream: "wk-a/j9",
+    from: 0,
+    gap: false,
+    nextOffset: 1,
+    entries: [{ offset: 0, chunk: envChunk("message", { role: "assistant", text: "finished earlier" }) }],
+  };
+  const transcripts = [
+    { stream: "wk-a/j9", lifecycle: "ephemeral", status: "completed", createdAt: "2024-01-01T00:00:00Z", nextOffset: 1, byteLength: 10, chunkCount: 1, processInstanceKey: "pi-child" },
+  ];
+  const restore = installEnv(focusStub({ correlations: [], transcripts, replay }));
+  (globalThis as { location: { hash: string } }).location.hash = `#/cockpit/process/${PI_ROOT}`;
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await settle();
+      assertEquals(document.querySelector(".cockpit-terminal")?.getAttribute("data-terminal-mode"), "replay");
+      assert((document.querySelector('[data-terminal="host"]')?.textContent ?? "").includes("finished earlier"));
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});
+
+test("#833: embedded, the host page's #/cockpit/<process_key> (the grid 'Agent' link) focuses the cockpit", async () => {
+  const restore = installEnv(focusStub({ correlations: [] }));
+  const win = (globalThis as { window: Record<string, unknown> }).window;
+  const savedParent = win.parent;
+  win.parent = { location: { hash: `#/cockpit/${PI_ROOT}` } };
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await settle();
+      assert((document.querySelector(".cockpit-focus")?.textContent ?? "").includes(PI_ROOT), "the host param focused the cockpit");
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    win.parent = savedParent;
+    restore();
+  }
+});
+
+test("#833: no focus route → no focus banner", async () => {
+  const restore = installEnv(fetchStub());
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await settle();
+      assertEquals(document.querySelector(".cockpit-focus")?.getAttribute("data-focus"), "none");
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});
+
+// #834 review — a MUTABLE fetch stub: the supply correlations and per-tree transcripts can change
+// between polls, so a test can model a focused live job finishing and its session becoming a capture.
+function mutableFocusStub(state: { correlations: unknown[]; transcripts: unknown[]; replay?: unknown; roots?: string[] }) {
+  return (url: string): Promise<unknown> => {
+    const ok = (body: unknown) => Promise.resolve({ ok: true, status: 200, json: async () => body });
+    if (url.includes("/supply")) return ok({ leaves: [], workers: [], correlations: state.correlations });
+    if (/\/agent-instances\/[^/?]+\/history/.test(url)) return ok(FOCUS_HISTORY);
+    if (url.includes("/agent-instances")) {
+      const root = (state.roots ?? [PI_ROOT]).some((r) => url.includes(`rootProcessInstanceKey=${r}`));
+      return ok(root ? { count: 1, instances: [FOCUS_INSTANCE] } : { count: 0, instances: [] });
+    }
+    if (/[?&]stream=/.test(url)) return ok(state.replay);
+    if (url.includes("/transcripts")) {
+      const mine = state.transcripts.filter((t) => url.includes(`processInstanceKey=${(t as { processInstanceKey: string }).processInstanceKey}`));
+      return ok({ count: mine.length, transcripts: mine });
+    }
+    return Promise.resolve({ ok: false, status: 404, json: async () => ({}) });
+  };
+}
+
+test("#834: when the auto-followed live job finishes, the focus falls back to the newest capture", async () => {
+  const replay = {
+    stream: "wk-a/j1",
+    from: 0,
+    gap: false,
+    nextOffset: 1,
+    entries: [{ offset: 0, chunk: envChunk("message", { role: "assistant", text: "captured after finish" }) }],
+  };
+  const state = {
+    correlations: [{ jobKey: "j1", stream: "wk-a/j1", processInstanceKey: "pi-child" }] as unknown[],
+    transcripts: [] as unknown[],
+    replay,
+  };
+  const restore = installEnv(mutableFocusStub(state));
+  (globalThis as { location: { hash: string } }).location.hash = `#/cockpit/process/${PI_ROOT}`;
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await settle();
+      assertEquals(document.querySelector(".cockpit-terminal")?.getAttribute("data-terminal-mode"), "live");
+      // The followed job finishes: its live correlation drops out and its session becomes a capture.
+      state.correlations = [];
+      state.transcripts = [
+        { stream: "wk-a/j1", lifecycle: "ephemeral", status: "completed", createdAt: "2024-01-01T00:00:00Z", nextOffset: 1, byteLength: 10, chunkCount: 1, processInstanceKey: "pi-child" },
+      ];
+      await handle.refresh();
+      await settle();
+      assertEquals(document.querySelector(".cockpit-terminal")?.getAttribute("data-terminal-mode"), "replay");
+      assert((document.querySelector('[data-terminal="host"]')?.textContent ?? "").includes("captured after finish"), "the newest capture replays after the live job ends");
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});
+
+test("#834: changing the focused process resets the terminal — it never keeps showing the old process's live stream", async () => {
+  const state = {
+    correlations: [{ jobKey: "j1", stream: "wk-a/j1", processInstanceKey: "pi-child" }] as unknown[],
+    transcripts: [] as unknown[],
+    replay: undefined as unknown,
+  };
+  const restore = installEnv(mutableFocusStub(state));
+  (globalThis as { location: { hash: string } }).location.hash = `#/cockpit/process/${PI_ROOT}`;
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await settle();
+      assertEquals(document.querySelector(".cockpit-terminal")?.getAttribute("data-terminal-mode"), "live");
+      // Focus a DIFFERENT process with no live job and no capture: the terminal must reset to idle,
+      // not keep replaying process A's live stream.
+      handle.focus("pi-other");
+      await settle();
+      assert((document.querySelector(".cockpit-focus")?.textContent ?? "").includes("pi-other"), "the banner names the new focus");
+      assertEquals(document.querySelector(".cockpit-terminal")?.getAttribute("data-terminal-mode"), "idle");
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});
+
+test("#834: navigating from a process route to the main route clears the focus", async () => {
+  const restore = installEnv(focusStub({ correlations: [] }));
+  (globalThis as { location: { hash: string } }).location.hash = `#/cockpit/process/${PI_ROOT}`;
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await settle();
+      assert((document.querySelector(".cockpit-focus")?.textContent ?? "").includes(PI_ROOT), "the process route focused the cockpit");
+      // Navigate away to the main route: the URL no longer selects a process, so the focus must clear
+      // (the banner and background focus polls must not keep following the process the view left).
+      // linkedom's dispatchEvent rejects a native Event, so construct the event from the stub window.
+      (globalThis as { location: { hash: string } }).location.hash = "#/cockpit";
+      const win = (globalThis as { window: { Event: new (t: string) => unknown; dispatchEvent: (e: unknown) => void } }).window;
+      win.dispatchEvent(new win.Event("hashchange"));
+      await settle();
+      assertEquals(document.querySelector(".cockpit-focus")?.getAttribute("data-focus"), "none");
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});
+
+test("#834: a failed auto-opened history read is retried on a later poll", async () => {
+  // The history read fails on the FIRST attempt (ok:false → boundedJson throws), then succeeds. The
+  // focus must not latch the run as shown on the failed read: a later poll re-fires it and lands the detail.
+  let historyCalls = 0;
+  const state = { correlations: [] as unknown[], transcripts: [] as unknown[], replay: undefined as unknown };
+  const base = mutableFocusStub(state);
+  const restore = installEnv((url: string) => {
+    if (/\/agent-instances\/[^/?]+\/history/.test(url)) {
+      historyCalls++;
+      if (historyCalls === 1) return Promise.resolve({ ok: false, status: 500, json: async () => ({}) });
+    }
+    return base(url);
+  });
+  (globalThis as { location: { hash: string } }).location.hash = `#/cockpit/process/${PI_ROOT}`;
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await settle();
+      assertEquals(historyCalls, 1, "the focus auto-opened the newest run's history once");
+      assert(
+        (document.querySelector(".cockpit-agent-transcript")?.textContent ?? "").includes("working on the focused process") === false,
+        "the failed read rendered nothing",
+      );
+      // A later poll retries the failed read; the detail now renders.
+      await handle.refresh();
+      await settle();
+      assert(historyCalls >= 2, "the failed auto-open was retried on a later poll");
+      assert(
+        (document.querySelector(".cockpit-agent-transcript")?.textContent ?? "").includes("working on the focused process"),
+        "the retried read rendered the focused agent's history",
+      );
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});
+
+test("#834: 'Show all' clears the focus route from the URL so a refresh does not reopen the process", async () => {
+  const restore = installEnv(focusStub({ correlations: [] }));
+  (globalThis as { location: { hash: string } }).location.hash = `#/cockpit/process/${PI_ROOT}`;
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await settle();
+      assert((document.querySelector(".cockpit-focus")?.textContent ?? "").includes(PI_ROOT), "the process route focused the cockpit");
+      // Clicking "Show all" must navigate the focus route out of the URL, not just hide the banner —
+      // otherwise refreshing/sharing `#/cockpit/process/<key>` reopens the process just cleared (#834).
+      const clear = document.querySelector(".cockpit-focus-clear");
+      assert(clear != null, "the focus banner offers a 'Show all' control");
+      const win = (globalThis as { window: { Event: new (t: string) => unknown; dispatchEvent: (e: unknown) => void } }).window;
+      (clear as { dispatchEvent: (e: unknown) => void }).dispatchEvent(new win.Event("click"));
+      assertEquals((globalThis as { location: { hash: string } }).location.hash, "#/cockpit", "'Show all' navigated the URL back to the cockpit root");
+      // The resulting hashchange then clears the focus, exactly as a real browser navigation would.
+      win.dispatchEvent(new win.Event("hashchange"));
+      await settle();
+      assertEquals(document.querySelector(".cockpit-focus")?.getAttribute("data-focus"), "none");
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});
+
+test("#834: switching the focused process clears the old focus's agent-history list immediately", async () => {
+  const state = { correlations: [] as unknown[], transcripts: [] as unknown[], replay: undefined as unknown };
+  const restore = installEnv(mutableFocusStub(state));
+  (globalThis as { location: { hash: string } }).location.hash = `#/cockpit/process/${PI_ROOT}`;
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await settle();
+      assert(document.querySelector(".cockpit-agent-region .cockpit-agent-history") != null, "focus A rendered its agent-history list");
+      // The switch must blank the list SYNCHRONOUSLY, not leave A's rows up until B's reads land: a click
+      // on a stale A row would otherwise start a detail read under B's focus generation (#834).
+      handle.focus("pi-other");
+      assertEquals(document.querySelector(".cockpit-agent-region")?.childElementCount, 0, "the old focus's history list was cleared immediately on focus change");
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});
+
+test("#834: a superseded focus's in-flight transcript scan does not block the new focus's scan", async () => {
+  // Park focus A's per-tree transcript scan on a never-settling fetch, then switch to B. With a shared
+  // scan lock, B would skip its scan until A's request settled (up to the 15s timeout); the lock must be
+  // scoped to the focus generation so B scans immediately and replays its own capture (#834).
+  let releaseA: () => void = () => {};
+  const aParked = new Promise<void>((r) => {
+    releaseA = r;
+  });
+  const bReplay = {
+    stream: "wk-b/j9",
+    from: 0,
+    gap: false,
+    nextOffset: 1,
+    entries: [{ offset: 0, chunk: envChunk("message", { role: "assistant", text: "B capture replays" }) }],
+  };
+  const state = { correlations: [] as unknown[], transcripts: [] as unknown[], replay: bReplay, roots: [] as string[] };
+  const base = mutableFocusStub(state);
+  const restore = installEnv(async (url: string) => {
+    if (url.includes("/transcripts") && url.includes(`processInstanceKey=${PI_ROOT}`)) {
+      await aParked; // focus A's scan hangs here until released
+      return { ok: true, status: 200, json: async () => ({ count: 0, transcripts: [] }) };
+    }
+    return base(url);
+  });
+  (globalThis as { location: { hash: string } }).location.hash = `#/cockpit/process/${PI_ROOT}`;
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    try {
+      await settle();
+      // A is focused; its transcript scan is parked awaiting `aParked` and holds the scan lock.
+      assertEquals(document.querySelector(".cockpit-terminal")?.getAttribute("data-terminal-mode"), "idle");
+      // Switch to B, which HAS a capture: its scan must run despite A's lock still being held.
+      state.transcripts = [
+        { stream: "wk-b/j9", lifecycle: "ephemeral", status: "completed", createdAt: "2024-01-01T00:00:00Z", nextOffset: 1, byteLength: 10, chunkCount: 1, processInstanceKey: "pi-bee" },
+      ];
+      handle.focus("pi-bee");
+      await settle();
+      assertEquals(document.querySelector(".cockpit-terminal")?.getAttribute("data-terminal-mode"), "replay");
+      assert(
+        (document.querySelector('[data-terminal="host"]')?.textContent ?? "").includes("B capture replays"),
+        "the new focus replayed its capture even though the superseded focus's scan is still in flight",
+      );
+    } finally {
+      releaseA();
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});

package/nano.app.json

@@ -265,7 +265,8 @@
       "enabled": true,
       "pagesDir": "pages",
       "homePage": "overview",
-      "sourceName": "app"
+      "sourceName": "app",
+      "gridLayout": "cards"
     }
   },
   "ui": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.195.2",
+  "version": "0.197.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",
@@ -65,7 +65,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.14.0",
-    "@nanobpm/urban": "^0.93.0",
+    "@nanobpm/urban": "^0.94.1",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {

package/pages/cockpit/cockpit.css

@@ -545,3 +545,20 @@
   border-top: 1px solid var(--cockpit-edge);
   padding-top: 6px;
 }
+
+/* ── Process focus banner (#833): the cockpit opened from an "Agent" grid link. ── */
+
+.cockpit-focus[data-focus="none"] { display: none; }
+
+.cockpit-focus {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  padding: 6px 10px;
+  margin-bottom: 8px;
+  border: 1px solid var(--cockpit-edge);
+  border-radius: 6px;
+  font-size: 13px;
+}
+
+.cockpit-focus-clear { margin-left: auto; }

package/pages/cockpit/mount.js

@@ -35,18 +35,53 @@ function isPosInt(value) {
   return Number.isSafeInteger(value) && value > 0;
 }
 
+function decodeSegment(raw) {
+  if (raw === "") return undefined;
+  try {
+    const value = decodeURIComponent(raw);
+    return value === "" ? undefined : value;
+  } catch {
+    return undefined;
+  }
+}
+
+// Mirrors app/agentic/cockpit/cockpit-route.ts `parseCockpitRoute` (keep in lockstep).
 function parseCockpitRoute(hash) {
   const route = hash.startsWith("#") ? hash.slice(1) : hash;
-  if (route === "" || route === "/cockpit" || route === "/cockpit/") return { kind: "main" };
-  const prefix = "/cockpit/worker/";
-  if (!route.startsWith(prefix)) return { kind: "main" };
+  const worker = "/cockpit/worker/";
+  if (route.startsWith(worker)) {
+    const instance = decodeSegment(route.slice(worker.length));
+    return instance === undefined ? { kind: "main" } : { kind: "worker", instance };
+  }
+  const process = "/cockpit/process/";
+  if (route.startsWith(process)) {
+    const processInstanceKey = decodeSegment(route.slice(process.length));
+    return processInstanceKey === undefined ? { kind: "main" } : { kind: "process", processInstanceKey };
+  }
+  return { kind: "main" };
+}
+
+// Mirrors app/agentic/cockpit/cockpit-route.ts `parseHostCockpitParam` (#833): the process key an
+// "Agent" grid link put on the HOST page's `#/cockpit/<param>` route.
+function parseHostCockpitParam(hash) {
+  const route = hash.startsWith("#") ? hash.slice(1) : hash;
+  const prefix = "/cockpit/";
+  if (!route.startsWith(prefix)) return undefined;
   const raw = route.slice(prefix.length);
-  if (raw === "") return { kind: "main" };
+  if (raw.includes("/")) return undefined;
+  return decodeSegment(raw);
+}
+
+// The host page's cockpit param, when this module runs in a same-origin App-View iframe. A
+// cross-origin parent throws on `location` access — no focus then.
+function hostCockpitParam() {
   try {
-    const instance = decodeURIComponent(raw);
-    return instance === "" ? { kind: "main" } : { kind: "worker", instance };
+    const parent = window.parent;
+    if (parent == null || parent === window) return undefined;
+    const hash = parent.location?.hash;
+    return typeof hash === "string" ? parseHostCockpitParam(hash) : undefined;
   } catch {
-    return { kind: "main" };
+    return undefined;
   }
 }
 
@@ -836,6 +871,10 @@ export function mountCockpit(host, opts = {}) {
   const terminalNote = el(doc, "p", "cockpit-terminal-note");
   terminalNote.setAttribute("data-terminal-note", "none");
   terminalPanel.appendChild(terminalNote);
+  // Process-focus banner (#833): shown when the cockpit was opened from an "Agent" grid link.
+  const focusBanner = el(doc, "div", "cockpit-focus");
+  focusBanner.setAttribute("data-focus", "none");
+  shell.appendChild(focusBanner);
   shell.appendChild(listRegion);
   shell.appendChild(terminalPanel);
   shell.appendChild(pastRegion);
@@ -865,6 +904,40 @@ export function mountCockpit(host, opts = {}) {
   let agentRefreshing = false;
   let agentRefreshPending = false;
   let shownAgentInstanceKey;
+  // In-flight guard for an auto-triggered agent-history read, distinct from `shownAgentInstanceKey`.
+  // The focus auto-opens the newest run's history once; marking it `shown` only AFTER the read renders
+  // (in viewAgentHistory) means a failed/timed-out read leaves `shown` unset so a later poll retries —
+  // while this in-flight key still prevents a duplicate request stacking on the one outstanding (#834).
+  let autoHistoryKey;
+  // Process focus (#833). `focusKey` is the linked process instance; `focusKeys` grows to every
+  // process instance in its tree that hosts one of its agents (a call-activity CHILD runs the agent
+  // job, so its correlation carries the child key). While `focusAuto` holds, the terminal follows the
+  // focus (live drill if a job is running, else the newest captured transcript); any operator
+  // selection clears it so the cockpit never yanks the panel away from what they chose.
+  let lastReport;
+  let focusKey;
+  let focusKeys = new Set();
+  let focusAuto = false;
+  // The per-tree transcript-scan lock, scoped to the focus generation that holds it rather than a
+  // shared boolean: a stale scan from a superseded focus must NOT block the new focus's scan, and its
+  // late settle must NOT release the new focus's lock (review #834). `undefined` = free.
+  let focusReplayGen;
+  // Bumped by every setFocus(); captured before each focus-scoped async read (agent-instances list,
+  // per-tree transcript scan, history detail) so a response that resolves after the focus changed —
+  // including an A→B→A flip where the key matches again — is dropped instead of mutating the new
+  // focus's `focusKeys`, terminal, or agent detail (review #834).
+  let focusGen = 0;
+  // The stream of a live drill the FOCUS auto-selected (vs. one the operator picked). When that job
+  // finishes (its correlation drops out) the auto drill is torn down so the focus can fall back to the
+  // newest capture; a manually chosen stream is never auto-closed.
+  let autoDrillStream;
+  // Rate-limit the per-tree transcript scan: a fan-out focus with many children and no captures would
+  // otherwise re-scan every child on every supply poll. Scan at most once per focusScanMinMs.
+  const focusScanMinMs = staleAfterMs;
+  let focusScanAt = 0;
+  // Monotonic token for the agent-history DETAIL read, so a slow response for a previously selected
+  // run can't overwrite a newer selection within the same focus.
+  let detailToken = 0;
 
   function setMode(next, stream) {
     mode = next;
@@ -903,10 +976,10 @@ export function mountCockpit(host, opts = {}) {
   function renderRoute() {
     if (view == null) return;
     if (route.kind === "worker") {
-      renderWorkerDetail(listRegion, doc, workerDetailView(view, route.instance), backToMain, drillInto);
+      renderWorkerDetail(listRegion, doc, workerDetailView(view, route.instance), backToMain, userDrill);
       return;
     }
-    renderSupply(listRegion, doc, view, drillInto, openWorker);
+    renderSupply(listRegion, doc, view, userDrill, openWorker);
   }
 
   function openWorker(instance) {
@@ -932,6 +1005,13 @@ export function mountCockpit(host, opts = {}) {
 
   function onHashChange() {
     route = parseCockpitRoute(location.hash);
+    if (route.kind === "process") {
+      if (route.processInstanceKey !== focusKey) setFocus(route.processInstanceKey);
+    } else if (focusKey != null) {
+      // Navigated to the main/worker route: the URL no longer selects a process, so drop the focus —
+      // otherwise the banner and the background focus polls keep following a process the view left (#834).
+      setFocus(undefined);
+    }
     try {
       renderRoute();
     } catch (err) {
@@ -942,6 +1022,132 @@ export function mountCockpit(host, opts = {}) {
 
   window.addEventListener("hashchange", onHashChange);
 
+  function userDrill(stream) {
+    focusAuto = false;
+    autoDrillStream = undefined;
+    drillInto(stream);
+  }
+
+  function userReplay(stream) {
+    focusAuto = false;
+    autoDrillStream = undefined;
+    return replayInto(stream);
+  }
+
+  function renderFocus() {
+    focusBanner.replaceChildren();
+    if (focusKey == null) {
+      focusBanner.setAttribute("data-focus", "none");
+      return;
+    }
+    focusBanner.setAttribute("data-focus", focusKey);
+    focusBanner.appendChild(el(doc, "span", "cockpit-focus-label", `Focused on process instance ${focusKey}`));
+    const clear = el(doc, "button", "cockpit-focus-clear", "Show all");
+    clear.setAttribute("type", "button");
+    clear.addEventListener("click", () => clearFocus());
+    focusBanner.appendChild(clear);
+  }
+
+  // "Show all" must clear the URL that selected the focus, not just the banner — otherwise the focus
+  // route survives in the address bar and a refresh/share reopens the process the operator just
+  // dismissed (review #834). Standalone, the focus lives in our own `#/cockpit/process/<key>` hash, so
+  // navigating it to `#/cockpit` fires onHashChange, which clears the focus. Embedded, the focus derives
+  // from the host page's `#/cockpit/<param>` hash; rewrite the parent hash to `#/cockpit` so it stops
+  // re-seeding the focus (a cross-origin parent throws on access — fall back to a local clear).
+  function clearFocus() {
+    if (route.kind === "process") {
+      location.hash = "#/cockpit";
+      return;
+    }
+    try {
+      const parent = window.parent;
+      if (parent != null && parent !== window && parseHostCockpitParam(parent.location?.hash ?? "") != null) {
+        parent.location.hash = "#/cockpit";
+      }
+    } catch {
+      // cross-origin host — can't touch its hash; fall through to a local focus clear.
+    }
+    setFocus(undefined);
+  }
+
+  function setFocus(key) {
+    // A new focus invalidates every in-flight focus-scoped read (list/scan/detail) and the terminal
+    // that was following the old focus. Bump the generation first so any awaited result now resolving
+    // is rejected, then hard-reset the panels the old focus owned.
+    focusGen++;
+    focusKey = key;
+    focusKeys = new Set(key == null ? [] : [key]);
+    focusAuto = key != null;
+    autoDrillStream = undefined;
+    focusScanAt = 0;
+    shownAgentInstanceKey = undefined;
+    autoHistoryKey = undefined;
+    // Clear the agent-history LIST alongside the detail: leaving the old focus's list up until the new
+    // focus's reads land would let a click on a stale row start a detail read under the new focus's
+    // generation, surfacing A's history beneath B's banner (review #834).
+    agentRegion.replaceChildren();
+    agentDetailRegion.replaceChildren();
+    teardownTerminal();
+    setMode(undefined, undefined);
+    renderFocus();
+    void focusTick();
+  }
+
+  // Follow the focus: drill into a live job of any process in the focused tree; otherwise replay
+  // the newest captured transcript of that tree (only while the terminal is idle).
+  async function autoFocusTerminal() {
+    if (!focusAuto || disposed) return;
+    const gen = focusGen;
+    const live = (lastReport?.correlations ?? []).find(
+      (c) => c.processInstanceKey != null && focusKeys.has(c.processInstanceKey) && typeof c.stream === "string" && c.stream !== "",
+    );
+    if (live) {
+      autoDrillStream = live.stream;
+      drillInto(live.stream);
+      return;
+    }
+    // The auto-followed live job finished — its correlation is gone but the terminal is still parked in
+    // `live` mode on that stream. Close only THIS auto drill (never an operator's manual selection) so
+    // the focus can fall back to the newest capture below.
+    if (autoDrillStream != null && mode === "live" && drill?.stream === autoDrillStream) {
+      autoDrillStream = undefined;
+      teardownTerminal();
+      setMode(undefined, undefined);
+    }
+    if (mode != null) return;
+    // A scan already running for THIS focus generation blocks a duplicate; a lock still held by a
+    // superseded focus (gen mismatch) must NOT block this focus's scan (review #834).
+    if (focusReplayGen === gen) return;
+    // Throttle the per-tree transcript scan (a focus with many children and no captures would otherwise
+    // re-scan every child every poll). The first scan after a focus change runs immediately (focusScanAt=0).
+    if (Date.now() - focusScanAt < focusScanMinMs) return;
+    focusScanAt = Date.now();
+    focusReplayGen = gen;
+    try {
+      const transcripts = [];
+      for (const key of focusKeys) {
+        const url = new URL(transcriptsUrl, location.href);
+        url.searchParams.set("processInstanceKey", key);
+        const report = await boundedJson(url.href);
+        if (gen !== focusGen || disposed) return;
+        transcripts.push(...(report.transcripts ?? []));
+      }
+      const newest = transcriptsView({ count: transcripts.length, transcripts }).sessions[0];
+      if (newest && gen === focusGen && focusAuto && mode == null && !disposed) await replayInto(newest.stream);
+    } catch (err) {
+      onError(err);
+    } finally {
+      // Only release the lock if THIS scan still owns it: a newer focus may have claimed it while we
+      // awaited, and clearing it then would let a duplicate scan stack under the new focus.
+      if (focusReplayGen === gen) focusReplayGen = undefined;
+    }
+  }
+
+  async function focusTick() {
+    await refreshAgentHistory();
+    await autoFocusTerminal();
+  }
+
   function drillInto(stream) {
     if (disposed || (mode === "live" && drill?.stream === stream)) return;
     // Claim the terminal region: bump the op token so an in-flight replay drops its stale result.
@@ -1113,7 +1319,7 @@ export function mountCockpit(host, opts = {}) {
           pastRegion,
           doc,
           transcriptsView(report),
-          replayInto,
+          userReplay,
           mode === "replay" ? shownStream : undefined,
           instance == null ? "Past sessions" : "Job history",
           instance == null ? "No captured sessions yet." : "No captured sessions for this worker yet.",
@@ -1143,6 +1349,7 @@ export function mountCockpit(host, opts = {}) {
     }
     if (disposed) return;
     try {
+      lastReport = report;
       view = supplyView(report, staleAfterMs);
       renderRoute();
     } catch (err) {
@@ -1150,8 +1357,9 @@ export function mountCockpit(host, opts = {}) {
     }
     // Fire-and-forget: a hung transcripts endpoint must never stall the supply poll's next tick.
     void refreshPast(routeInstance());
-    // Same discipline for the engine agent-history list (issue #745): single-flight + bounded.
-    void refreshAgentHistory();
+    // Same discipline for the engine agent-history list (issue #745): single-flight + bounded. Under a
+    // process focus (#833) the list is focus-filtered and the terminal follows the focus.
+    void focusTick();
   }
 
   // The engine-native SETTLED agent-history endpoints (issue #745/#747), anchored module-relatively
@@ -1180,6 +1388,25 @@ export function mountCockpit(host, opts = {}) {
     }
   }
 
+  // The engine AgentInstances of one focused process TREE (#833): those owned by the instance itself
+  // and those whose ROOT it is (an agent in a call-activity child). Their process keys join
+  // `focusKeys` so live-job correlations on a child instance match the focus.
+  async function focusedAgentInstances(key, gen) {
+    const byKey = new Map();
+    for (const param of ["processInstanceKey", "rootProcessInstanceKey"]) {
+      const url = new URL(agentInstancesUrl, location.href);
+      url.searchParams.set(param, key);
+      const report = await boundedJson(url.href);
+      // The focus changed while this list was in flight — drop it rather than fold a stale tree's keys
+      // into the new focus's `focusKeys`.
+      if (gen !== focusGen || disposed) return { count: 0, instances: [] };
+      for (const i of report.instances ?? []) byKey.set(i.agentInstanceKey, i);
+    }
+    const instances = [...byKey.values()];
+    for (const i of instances) if (i.processInstanceKey) focusKeys.add(i.processInstanceKey);
+    return { count: instances.length, instances };
+  }
+
   async function refreshAgentHistory() {
     // Single-flight (mirrors refreshPast): a slow/hung engine read endpoint never stacks fetches nor
     // gates the supply poll. The list is engine-global (settled AgentInstances), so it is not route-filtered.
@@ -1190,17 +1417,34 @@ export function mountCockpit(host, opts = {}) {
     agentRefreshing = true;
     try {
       let report;
+      const key = focusKey;
+      const gen = focusGen;
       try {
-        report = await boundedJson(agentInstancesUrl);
+        report = key == null ? await boundedJson(agentInstancesUrl) : await focusedAgentInstances(key, gen);
       } catch (err) {
         onError(err);
         return;
       }
-      if (disposed) return;
+      if (disposed || gen !== focusGen) return;
+      let sessions;
       try {
-        renderAgentSessions(agentRegion, doc, agentSessionsView(report), viewAgentHistory, shownAgentInstanceKey);
+        sessions = agentSessionsView(report);
+        renderAgentSessions(agentRegion, doc, sessions, viewAgentHistory, shownAgentInstanceKey);
       } catch (err) {
         onError(err);
+        return;
+      }
+      // Under a focus, open the newest run's history once so the linked agent is on screen. Fire it
+      // WITHOUT awaiting: `focusTick` follows autoFocusTerminal right after this resolves, so a slow
+      // (bounded) history-detail read must not stall the terminal from following the focused live job.
+      // Gate on the in-flight `autoHistoryKey`, NOT `shownAgentInstanceKey`: the run is marked shown
+      // only after its detail actually renders (viewAgentHistory), so a read that failed or timed out
+      // leaves `shown` unset and a later poll retries it — while `autoHistoryKey` still stops a second
+      // request stacking on the one already outstanding (#834).
+      const newest = sessions.sessions[0];
+      if (key != null && shownAgentInstanceKey == null && newest != null && autoHistoryKey !== newest.agentInstanceKey) {
+        autoHistoryKey = newest.agentInstanceKey;
+        void viewAgentHistory(newest.agentInstanceKey);
       }
     } finally {
       agentRefreshing = false;
@@ -1213,14 +1457,22 @@ export function mountCockpit(host, opts = {}) {
 
   async function viewAgentHistory(agentInstanceKey) {
     if (disposed) return;
+    // Capture the focus generation and a fresh selection token; a response that resolves after the
+    // focus changed or after a newer run was selected is dropped instead of overwriting the current view.
+    const gen = focusGen;
+    const token = ++detailToken;
     let report;
     try {
       report = await boundedJson(agentHistoryReadUrl(agentInstanceKey));
     } catch (err) {
       onError(err);
+      // The auto-open read failed: release the in-flight key so a later poll retries it (the run was
+      // never marked shown). A stale superseded read is left latched — a newer selection already
+      // replaced it.
+      if (gen === focusGen && autoHistoryKey === agentInstanceKey) autoHistoryKey = undefined;
       return;
     }
-    if (disposed) return;
+    if (disposed || gen !== focusGen || token !== detailToken) return;
     try {
       shownAgentInstanceKey = agentInstanceKey;
       renderAgentHistory(agentDetailRegion, doc, agentHistoryView(report));
@@ -1228,6 +1480,9 @@ export function mountCockpit(host, opts = {}) {
       void refreshAgentHistory();
     } catch (err) {
       onError(err);
+    } finally {
+      // The auto-open read settled: release the in-flight key (no-op for a manual or superseded read).
+      if (gen === focusGen && autoHistoryKey === agentInstanceKey) autoHistoryKey = undefined;
     }
   }
 
@@ -1261,8 +1516,16 @@ export function mountCockpit(host, opts = {}) {
     window.removeEventListener("hashchange", onHashChange);
   }
 
+  const initialFocus = route.kind === "process" ? route.processInstanceKey : hostCockpitParam();
+  if (initialFocus != null) {
+    focusKey = initialFocus;
+    focusKeys = new Set([initialFocus]);
+    focusAuto = true;
+  }
+  renderFocus();
+
   start();
-  return { start, stop, dispose, refresh, drill: drillInto, replay: replayInto, viewAgentHistory };
+  return { start, stop, dispose, refresh, drill: userDrill, replay: userReplay, viewAgentHistory, focus: setFocus };
 }
 
 /**

package/pages/cockpit/standalone.html

@@ -34,14 +34,20 @@
       // credentials via the URL fragment — the report guard secret via #secret= (sent as
       // x-hook-secret) and the relay credentials via #token= and #capability= — NOT the query string,
       // so they never leak via server access logs, browser history, or the Referer header. The
-      // fragment is stripped from the address bar immediately after it is read.
+      // sensitive fragment keys are stripped from the address bar immediately after they are read,
+      // while any OTHER fragment — notably a `#/cockpit/process/<key>` focus route (#833) — is
+      // preserved so mountCockpit can still read it and focus that process.
       const params = new URLSearchParams(location.search);
       const secrets = new URLSearchParams(location.hash.slice(1));
       const hookSecret = secrets.get("secret") ?? undefined;
       const relayToken = secrets.get("token") ?? undefined;
       const relayCapability = secrets.get("capability") ?? undefined;
-      if (location.hash) {
-        history.replaceState(null, "", location.pathname + location.search);
+      if (hookSecret !== undefined || relayToken !== undefined || relayCapability !== undefined) {
+        secrets.delete("secret");
+        secrets.delete("token");
+        secrets.delete("capability");
+        const rest = secrets.toString();
+        history.replaceState(null, "", location.pathname + location.search + (rest ? `#${rest}` : ""));
       }
       mountCockpit(document.getElementById("cockpit-root"), {
         reportUrl: params.get("report") ?? undefined,

package/pages/delivery-graph-detail.page.json

@@ -96,6 +96,7 @@
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Graph", "subtitleField": "run_key", "truncate": true, "width": "30%" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "process_key", "header": "Agent", "template": "Transcript", "width": "7rem", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
           {
             "field": "stage",
             "header": "Pipeline",

package/pages/delivery-graphs.page.json

@@ -132,14 +132,15 @@
           { "label": "All", "filter": [] }
         ],
         "columns": [
-          { "field": "title", "template": "{{title}}", "header": "Graph", "subtitleField": "run_key", "truncate": true, "width": "18%", "link": { "kind": "page", "page": "delivery-graph-detail", "keyField": "run_key" } },
+          { "field": "title", "template": "{{title}}", "header": "Graph", "subtitleField": "run_key", "truncate": true, "width": "16%", "link": { "kind": "page", "page": "delivery-graph-detail", "keyField": "run_key" } },
           { "field": "status", "header": "Status", "truncate": true, "width": "10%", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "process_key", "header": "Agent", "template": "Transcript", "truncate": true, "width": "5%", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
           { "field": "process_key", "header": "Instance", "width": "8%", "truncate": true, "link": { "kind": "processExplorer", "keyField": "process_key" } },
           {
             "field": "stage",
             "header": "Pipeline",
             "kind": "pipeline",
-            "width": "18%",
+            "width": "15%",
             "stages": [
               { "key": "Requested", "label": "Requested" },
               { "key": "Implementing", "label": "Implementing" },

package/pages/epic-detail.page.json

@@ -149,6 +149,7 @@
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "plan_key", "truncate": true, "width": "34%", "linkField": "issue_url" },
           { "field": "epic_phase", "header": "Phase" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "process_key", "header": "Agent", "template": "Transcript", "width": "7rem", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
           { "field": "delivery", "header": "Delivery" },
           { "field": "wait_gate_label", "header": "Wait gate" },
           { "field": "promotion_state", "header": "Promotion" },
@@ -242,6 +243,7 @@
           { "field": "task_id", "header": "Task" },
           { "field": "title", "header": "Title" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "process_key", "header": "Agent", "template": "Transcript", "width": "7rem", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
           { "field": "pr_key", "header": "PR", "linkField": "pr_url" },
           { "field": "summary", "header": "Summary" },
           { "field": "updated_at", "header": "Updated", "format": "datetime" }

package/pages/epic.page.json

@@ -121,6 +121,7 @@
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "plan_key", "truncate": true, "width": "38%", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
           { "field": "epic_phase", "header": "Phase", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "process_key", "header": "Agent", "template": "Transcript", "width": "7rem", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
           { "field": "delivery_label", "header": "Delivery", "truncate": true },
           { "field": "task_count", "header": "Tasks" },
           { "field": "issue_number", "header": "Issue", "linkField": "issue_url" },

package/pages/feature.page.json

@@ -136,6 +136,7 @@
             "notInPathField": "stage_skipped",
             "locus": { "field": "process_key", "link": { "kind": "processExplorer", "keyField": "process_key" } }
           },
+          { "field": "process_key", "header": "Agent", "template": "Transcript", "width": "7rem", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
           { "field": "updated_at", "header": "Updated", "width": "9rem", "format": "datetime" }
         ],
         "rowActions": [

package/pages/home.page.json

@@ -173,6 +173,17 @@
               "keyField": "process_key"
             }
           },
+          {
+            "field": "process_key",
+            "header": "Agent",
+            "template": "Transcript",
+            "width": "7rem",
+            "link": {
+              "kind": "page",
+              "page": "cockpit",
+              "keyField": "process_key"
+            }
+          },
           {
             "field": "incident_message",
             "header": "Incident",

package/pages/lineage.page.json

@@ -122,6 +122,7 @@
             "truncate": true,
             "link": { "kind": "processExplorer", "keyField": "process_key" }
           },
+          { "field": "process_key", "header": "Agent", "template": "Transcript", "width": "7rem", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
           { "field": "pr_count", "header": "PRs", "width": "5rem" },
           { "field": "updated_at", "header": "Updated", "width": "9rem", "format": "datetime" }
         ],
@@ -145,6 +146,7 @@
               "columns": [
                 { "field": "title", "template": "{{title}}", "header": "PR", "subtitleField": "pr_key", "truncate": true, "linkField": "url" },
                 { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+                { "field": "process_key", "header": "Agent", "template": "Transcript", "width": "7rem", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
                 { "field": "current_round", "header": "Round" },
                 { "field": "outcome", "header": "Outcome", "truncate": true },
                 { "field": "updated_at", "header": "Updated", "width": "9rem", "format": "datetime" }

package/pages/overview.page.json

@@ -112,6 +112,7 @@
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "pr_key", "truncate": true, "width": "36%", "link": { "kind": "page", "page": "home", "keyField": "pr_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "process_key", "header": "Agent", "template": "Transcript", "width": "7rem", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
           { "field": "incident_message", "header": "Incident", "truncate": true, "badge": { "tone": "danger", "label": "1" } },
           { "field": "current_round", "template": "{{current_round}} · {{active_worker}}", "header": "Round · Agent" },
           { "field": "updated_at", "header": "Updated", "width": "9rem", "format": "datetime" }
@@ -149,6 +150,7 @@
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "plan_key", "truncate": true, "width": "36%", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "process_key", "header": "Agent", "template": "Transcript", "width": "7rem", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
           { "field": "delivery_label", "header": "Landing" },
           { "field": "wave_label", "header": "Wave" },
           { "field": "updated_at", "header": "Updated", "width": "9rem", "format": "datetime" }
@@ -186,6 +188,7 @@
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "feature_key", "truncate": true, "width": "36%", "link": { "kind": "page", "page": "feature", "keyField": "feature_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "process_key", "header": "Agent", "template": "Transcript", "width": "7rem", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
           { "field": "delivery_label", "header": "Delivery" },
           { "field": "updated_at", "header": "Updated", "width": "9rem", "format": "datetime" }
         ],
@@ -227,6 +230,7 @@
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "run_key", "truncate": true, "width": "30%", "link": { "kind": "page", "page": "delivery-graph-detail", "keyField": "run_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "process_key", "header": "Agent", "template": "Transcript", "width": "7rem", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
           {
             "field": "stage",
             "header": "Pipeline",

package/pages/tasks.page.json

@@ -106,6 +106,7 @@
             "header": "Process",
             "link": { "kind": "processExplorer", "keyField": "process_key" }
           },
+          { "field": "process_key", "header": "Agent", "template": "Transcript", "width": "7rem", "link": { "kind": "page", "page": "cockpit", "keyField": "process_key" } },
           { "field": "updated_at", "header": "Updated", "format": "datetime" }
         ],
         "rowKey": "user_task_key",

package/test/agent-link-column.test.ts

@@ -0,0 +1,66 @@
+// #833 — every grid whose cell links a process instance to the explorer also offers an "Agent" cell
+// linking the SAME process_key to the cockpit (which focuses that process: live terminal, else its
+// latest transcript, plus the engine agent history). Guards the class: a new active-run grid can't
+// ship with a process-explorer link but no way to reach its agent — regardless of which column
+// carries the explorer link (Status, Phase, Stage, Process, …).
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { test } from "node:test";
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// The `link` object of a column, if it has one (no `as`: narrowed through type guards).
+function columnLink(column: unknown): Record<string, unknown> | undefined {
+  if (!isObject(column)) return undefined;
+  return isObject(column.link) ? column.link : undefined;
+}
+
+// The process-explorer link of a column, wherever it lives: a plain column carries it at `link`,
+// but a `pipeline` column carries it on its `locus` (the cell that links the row's process instance —
+// e.g. the Feature runs grid's Pipeline column, pages/feature.page.json). Guarding only `link` would
+// let a pipeline-locus explorer link ship with no Agent column and this test still pass (#834).
+function explorerLink(column: unknown): Record<string, unknown> | undefined {
+  const direct = columnLink(column);
+  if (direct?.kind === "processExplorer") return direct;
+  if (!isObject(column)) return undefined;
+  const locus = isObject(column.locus) ? column.locus : undefined;
+  const locusLink = locus && isObject(locus.link) ? locus.link : undefined;
+  return locusLink?.kind === "processExplorer" ? locusLink : undefined;
+}
+
+// Collect every `columns` array anywhere in the page tree (top-level grids, tab grids, detail
+// children, …) without asserting the parsed JSON's shape.
+function grids(node: unknown, out: unknown[][]): void {
+  if (Array.isArray(node)) {
+    for (const n of node) grids(n, out);
+    return;
+  }
+  if (!isObject(node)) return;
+  if (Array.isArray(node.columns)) out.push(node.columns);
+  for (const v of Object.values(node)) grids(v, out);
+}
+
+test("#833: every process-explorer grid also links its process to the cockpit via an Agent column", () => {
+  let checked = 0;
+  for (const file of readdirSync("pages").filter((f) => f.endsWith(".page.json"))) {
+    const all: unknown[][] = [];
+    grids(JSON.parse(readFileSync(`pages/${file}`, "utf8")), all);
+    for (const cols of all) {
+      // A grid qualifies whenever ANY of its columns links to the process explorer — not just a
+      // Status/Phase header, and not just a plain `link`: a pipeline column's `locus.link` counts too
+      // — so a Stage/Process/Pipeline (or any future) explorer link is guarded too.
+      const explorer = cols.some((c) => explorerLink(c) !== undefined);
+      if (!explorer) continue;
+      checked++;
+      const agent = cols.find((c) => isObject(c) && c.header === "Agent");
+      assert.deepEqual(
+        columnLink(agent),
+        { kind: "page", page: "cockpit", keyField: "process_key" },
+        `${file}: grid missing the Agent → cockpit link`,
+      );
+    }
+  }
+  assert.ok(checked > 0, "found no process-explorer grids to check");
+});

package/test/grid-layout-cards.test.ts

@@ -0,0 +1,10 @@
+// #837 — every dataGrid renders as the urban card list at every width: the fixed-max-width shell
+// clips wide tables on any monitor, while the card view shows every field.
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+
+test("#837: the pages surface opts into the app-wide card layout", () => {
+  const manifest = JSON.parse(readFileSync("nano.app.json", "utf8"));
+  assert.equal(manifest.surfaces?.pages?.gridLayout, "cards");
+});