refactor(cli,workflow-meta): scaffold AGENT.md on init; align develop prompts

Generate AGENT.md at ~/.uncaged-nerve root during nerve init (layout, verb-first workflows, createRole four-tuple, root build, coding style). Role prompts instruct agents to use cat AGENT.md instead of node_modules nerve-skills paths.

E2E init test asserts AGENT.md. Retain .knowledge workflow/adapter updates and flat single-file roles guidance from the branch.

Fixes #287

Made-with: Cursor

.knowledge/adapter.md

@@ -28,8 +28,29 @@ For long-running or incremental agent outputs:
 |---------|---------|------|
 | `@uncaged/nerve-adapter-cursor` | `cursorAdapter` / `createCursorAdapter()` | cursor-agent CLI |
 | `@uncaged/nerve-adapter-hermes` | `hermesAdapter` / `createHermesAdapter()` | hermes chat CLI |
+| `@uncaged/nerve-workflow-utils` | `createLlmAdapter(provider)` | OpenAI-compatible HTTP chat (single-turn) |
 
-Each exports a **default instance** (sensible defaults) and a **factory** for custom config.
+The Cursor and Hermes adapter packages each export a **default instance** (sensible defaults) and a **factory** for custom config. `createLlmAdapter` is a factory on `@uncaged/nerve-workflow-utils` only.
+
+## createLlmAdapter
+
+`createLlmAdapter` builds an `AgentFn` from an `LlmProvider` (`baseUrl`, `apiKey`, `model`). One chat completion per role step: **system** = the string passed by `createRole` (your prompt); **user** = `ctx.start.content` (the thread’s start frame). On failure it throws with a formatted LLM error.
+
+```ts
+import { createLlmAdapter, createRole } from "@uncaged/nerve-workflow-utils";
+import { z } from "zod";
+
+const metaSchema = z.object({ ok: z.boolean() });
+
+const planner = createRole(
+  createLlmAdapter({ baseUrl: "https://api.example.com/v1", apiKey: "…", model: "gpt-4o-mini" }),
+  "You are a planner…",
+  metaSchema,
+  extractConfig,
+);
+```
+
+Use this when you want a role backed by an HTTP LLM instead of a subprocess CLI adapter.
 
 ## Usage in Workflows
 

.knowledge/workflow.md

@@ -2,6 +2,20 @@
 
 Stateful multi-step execution driven by Roles and a Moderator.
 
+## Workspace Layout (authoring)
+
+User Nerve workspaces use a **flat** build: one root `package.json`, one root bundle script (typically `scripts/build.mjs` wired from `scripts.build`), and **no** per-workflow `package.json` or `tsconfig.json`.
+
+| Location | Purpose |
+|----------|---------|
+| `workflows/<name>/index.ts` | Default export: `WorkflowDefinition` (moderator + role map). |
+| `workflows/<name>/roles/<role>.ts` | One module per role — schemas, prompts, `createRole` factories, or hand-written async role functions. |
+| `dist/workflows/<name>/index.js` | Emit of the root build; this is what the daemon loads. |
+
+**Naming:** Workflow ids should be **verb-first** kebab-case phrases (e.g. `deploy-staging`, `scan-dependencies`), not opaque nouns alone.
+
+Senses follow the same flat pattern: `senses/<name>/src/*.ts`, `migrations/`, root build → `dist/senses/<name>/index.js`. See `.knowledge/sense.md`.
+
 ## Core Concepts
 
 - **Workflow** — definition with concurrency strategy

packages/cli/src/__tests__/e2e-validate-init.test.ts

@@ -205,6 +205,10 @@ describe("e2e init", () => {
     expect(existsSync(join(nerveRoot, "scripts", "build.mjs"))).toBe(true);
     expect(existsSync(join(nerveRoot, "biome.json"))).toBe(true);
     expect(existsSync(join(nerveRoot, ".gitignore"))).toBe(true);
+    expect(existsSync(join(nerveRoot, "AGENT.md"))).toBe(true);
+    const agentMd = readFileSync(join(nerveRoot, "AGENT.md"), "utf8");
+    expect(agentMd).toContain("verb-first");
+    expect(agentMd).toContain("createRole");
     expect(existsSync(join(nerveRoot, "senses", "cpu-usage", "src", "index.ts"))).toBe(true);
     expect(existsSync(join(nerveRoot, "senses", "cpu-usage", "src", "schema.ts"))).toBe(true);
     expect(existsSync(join(nerveRoot, "senses", "cpu-usage", "migrations", "0001_init.sql"))).toBe(

packages/cli/src/commands/init.ts

@@ -127,6 +127,70 @@ node_modules/
 knowledge.db
 `;
 
+/** Generated at workspace root so agents can \`cat AGENT.md\` instead of npm skill paths. */
+const AGENT_MD = `# Nerve workspace — agent guide
+
+This file is created by \`nerve init\`. Read it before implementing senses or workflows.
+
+## Directory layout
+
+| Path | Purpose |
+|------|---------|
+| \`nerve.yaml\` | Senses, workflows, intervals, groups |
+| \`package.json\` | Single root package — no per-sense/per-workflow packages |
+| \`scripts/build.mjs\` | Root esbuild step; output under \`dist/\` |
+| \`senses/<name>/src/index.ts\` | Sense \`compute()\` entry |
+| \`senses/<name>/src/schema.ts\` | Drizzle SQLite schema (TypeScript) |
+| \`senses/<name>/migrations/*.sql\` | SQL migrations (next to \`src/\`, not inside it) |
+| \`workflows/<name>/index.ts\` | Default export: \`WorkflowDefinition\` |
+| \`workflows/<name>/roles/<role>.ts\` | One TypeScript file per role |
+| \`dist/senses/<name>/index.js\` | Bundled sense (after build) |
+| \`dist/workflows/<name>/index.js\` | Bundled workflow (after build) |
+
+There is **no** \`package.json\` or \`tsconfig.json\` inside individual senses or workflows.
+
+## Naming
+
+- **Workflows:** verb-first kebab-case (e.g. \`review-pull-request\`, \`deploy-staging\`). Avoid bare nouns like \`notifications\`.
+- **Senses:** kebab-case descriptive nouns (e.g. \`cpu-usage\`).
+
+## Workflow roles — four-tuple pattern
+
+Wire each role with \`createRole\` from \`@uncaged/nerve-workflow-utils\`:
+
+1. **Adapter** — \`AgentFn\` (LLM call)
+2. **Prompt builder** — \`async (ctx: ThreadContext) => string\`
+3. **Meta schema** — Zod object (routing / structured output from the model)
+4. **Extractor config** — how JSON meta is parsed from replies
+
+Keep meta small (often one boolean per role). The **moderator** in \`WorkflowDefinition\` routes between role names.
+
+## Build commands
+
+Always run from the **workspace root**:
+
+\`\`\`bash
+pnpm run build
+# or: npm run build
+\`\`\`
+
+Fix errors until this succeeds. New workflows must appear under \`workflows/<name>/\` and be registered in \`nerve.yaml\`; new senses under \`senses/<name>/\` with matching \`nerve.yaml\` entries.
+
+## Coding style (Nerve conventions)
+
+- Use \`type\`, not \`interface\`; prefer \`function\` over classes (except errors / library requirements).
+- **Named exports only** — no \`export default\` (exception: \`workflows/<name>/index.ts\` uses default export for the daemon loader).
+- Nullable fields: \`T | null\`, not TypeScript optional \`?:\`.
+- No dynamic \`import()\` in workspace code (bundling and tooling assume static imports).
+- Use \`async\`/\`await\`; use a \`Result\` type for expected failures instead of control-flow try/catch.
+
+## Extra references (optional)
+
+- \`CONVENTIONS.md\` — project-specific overrides at repo root.
+- \`.knowledge/*.md\` — deeper docs when working inside the Nerve monorepo.
+- \`.cursor/skills/\` — Cursor Agent Skills (\`SKILL.md\` per skill).
+`;
+
 const NERVE_SKILLS_MDC = `---
 description: >-
   Where Agent Skills live in this Nerve workspace and how to use them with Cursor
@@ -362,6 +426,7 @@ async function runInitWorkspace(force: boolean, skipInstall = false): Promise<vo
   writeFile(join(nerveRoot, "scripts", "build.mjs"), BUILD_MJS);
   writeFile(join(nerveRoot, "biome.json"), BIOME_JSON);
   writeFile(join(nerveRoot, ".gitignore"), GITIGNORE);
+  writeFile(join(nerveRoot, "AGENT.md"), AGENT_MD);
   writeFile(join(nerveRoot, "senses", "cpu-usage", "src", "index.ts"), CPU_INDEX_TS);
   writeFile(join(nerveRoot, "senses", "cpu-usage", "src", "schema.ts"), CPU_SCHEMA_TS);
   writeFile(

packages/daemon/src/__tests__/fixtures/crash-worker.js

@@ -1,9 +0,0 @@
-// Ready then crashes on a timer; still echoes IPC so parent tests can send after respawn
-process.on("message", (msg) => {
-  if (msg && msg.type === "shutdown") {
-    process.exit(0);
-  }
-  process.send({ type: "echo", payload: msg });
-});
-process.send({ type: "ready" });
-setTimeout(() => process.exit(1), 50);

packages/daemon/src/__tests__/fixtures/echo-worker.js

@@ -1,9 +0,0 @@
-// Simple test worker: sends ready, echoes messages, handles shutdown
-process.on("message", (msg) => {
-  if (msg && msg.type === "shutdown") {
-    process.exit(0);
-  }
-  // Echo back with 'echo' type
-  process.send({ type: "echo", payload: msg });
-});
-process.send({ type: "ready" });

packages/daemon/src/__tests__/fixtures/stderr-worker.js

@@ -1,9 +0,0 @@
-// Like echo-worker but writes stderr for tail diagnostics
-console.error("stderr-marker");
-process.on("message", (msg) => {
-  if (msg && msg.type === "shutdown") {
-    process.exit(0);
-  }
-  process.send({ type: "echo", payload: msg });
-});
-process.send({ type: "ready" });

packages/daemon/src/__tests__/kernel-phase6.test.ts

@@ -70,14 +70,6 @@ const { createKernel } = await import("../kernel.js");
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** Sense worker `fork` runs on the next microtask per scheduled `start`. */
-async function flushSenseWorkerForkMicrotasks(kernel: { groups: Set<string> }): Promise<void> {
-  const n = kernel.groups.size;
-  for (let i = 0; i < n; i++) {
-    await Promise.resolve();
-  }
-}
-
 function makeConfig(overrides: Partial<NerveConfig> = {}): NerveConfig {
   return {
     senses: {
@@ -150,8 +142,6 @@ describe("kernel — getHealth", () => {
       },
     });
     const kernel = createKernel(config, nerveRoot);
-    await flushSenseWorkerForkMicrotasks(kernel);
-    await vi.runAllTimersAsync();
 
     const health = kernel.getHealth();
     expect(health.activeSenses).toBe(3);
@@ -181,8 +171,6 @@ describe("kernel — restartGroup", () => {
   it("sends shutdown to old worker and spawns new one", async () => {
     const config = makeConfig();
     const kernel = createKernel(config, nerveRoot);
-    await flushSenseWorkerForkMicrotasks(kernel);
-    await vi.runAllTimersAsync();
 
     expect(mockChildren.length).toBe(1);
     const oldChild = mockChildren[0];
@@ -190,7 +178,6 @@ describe("kernel — restartGroup", () => {
     const restartPromise = kernel.restartGroup("system");
     // The shutdown message triggers exit in the mock
     await restartPromise;
-    await vi.runAllTimersAsync();
 
     // A new child should have been spawned
     expect(mockChildren.length).toBe(2);
@@ -204,8 +191,6 @@ describe("kernel — restartGroup", () => {
   it("restartGroup on unknown group does nothing", async () => {
     const config = makeConfig();
     const kernel = createKernel(config, nerveRoot);
-    await flushSenseWorkerForkMicrotasks(kernel);
-    await vi.runAllTimersAsync();
 
     expect(mockChildren.length).toBe(1);
     await kernel.restartGroup("nonexistent");
@@ -233,8 +218,6 @@ describe("kernel — reloadConfig", () => {
   it("adds new group worker when new sense group appears", async () => {
     const config = makeConfig();
     const kernel = createKernel(config, nerveRoot);
-    await flushSenseWorkerForkMicrotasks(kernel);
-    await vi.runAllTimersAsync();
 
     expect(mockChildren.length).toBe(1); // only system group
     expect(kernel.groups.has("network")).toBe(false);
@@ -266,9 +249,6 @@ describe("kernel — reloadConfig", () => {
       api: { port: null, token: null, host: "127.0.0.1" },
     });
 
-    await Promise.resolve();
-    await vi.runAllTimersAsync();
-
     expect(kernel.groups.has("network")).toBe(true);
     expect(mockChildren.length).toBe(2); // system + network
 
@@ -303,8 +283,6 @@ describe("kernel — reloadConfig", () => {
       api: { port: null, token: null, host: "127.0.0.1" },
     };
     const kernel = createKernel(config, nerveRoot);
-    await flushSenseWorkerForkMicrotasks(kernel);
-    await vi.runAllTimersAsync();
 
     expect(mockChildren.length).toBe(2);
     expect(kernel.groups.has("network")).toBe(true);
@@ -330,7 +308,6 @@ describe("kernel — reloadConfig", () => {
     });
 
     expect(kernel.groups.has("network")).toBe(false);
-    await vi.runAllTimersAsync();
     // Network child should have received shutdown
     expect(networkChild.send).toHaveBeenCalledWith(expect.objectContaining({ type: "shutdown" }));
 
@@ -340,8 +317,6 @@ describe("kernel — reloadConfig", () => {
   it("health reflects updated sense count after reloadConfig", async () => {
     const config = makeConfig();
     const kernel = createKernel(config, nerveRoot);
-    await flushSenseWorkerForkMicrotasks(kernel);
-    await vi.runAllTimersAsync();
 
     expect(kernel.getHealth().activeSenses).toBe(1);
 

packages/daemon/src/__tests__/kernel-trigger-sense.test.ts

@@ -29,9 +29,6 @@ type MockChild = EventEmitter & {
 function makeMockChild(pid = 1): MockChild {
   const child = new EventEmitter() as MockChild;
   child.connected = true;
-  setImmediate(() => {
-    child.emit("message", { type: "ready" });
-  });
   child.send = vi.fn((msg: unknown) => {
     if (
       msg !== null &&
@@ -139,7 +136,6 @@ describe("kernel.triggerSense()", () => {
       logStore: makeMockLogStore() as never,
     });
 
-    await vi.runAllTimersAsync();
     expect(() => kernel.triggerSense("no-such-sense")).toThrow(/Unknown sense/);
 
     await kernel.stop();
@@ -173,7 +169,6 @@ describe("kernel.triggerSense()", () => {
       logStore: makeMockLogStore() as never,
     });
 
-    await vi.runAllTimersAsync();
     // Two groups → two workers
     expect(mockChildren.length).toBe(2);
 
@@ -219,7 +214,6 @@ describe("kernel.triggerSense()", () => {
       logStore: makeMockLogStore() as never,
     });
 
-    await vi.runAllTimersAsync();
     // Both senses share the "system" group → one worker only
     expect(mockChildren.length).toBe(1);
     const worker = mockChildren[0];
@@ -243,7 +237,6 @@ describe("kernel.triggerSense()", () => {
       logStore: makeMockLogStore() as never,
     });
 
-    await new Promise<void>((resolve) => setImmediate(resolve));
     const worker = mockChildren[0];
     worker.connected = false;
 

packages/daemon/src/__tests__/kernel-workflow-integration.test.ts

@@ -102,13 +102,6 @@ function makeLogStore() {
   };
 }
 
-async function flushSenseWorkerForkMicrotasks(kernel: { groups: Set<string> }): Promise<void> {
-  const n = kernel.groups.size;
-  for (let i = 0; i < n; i++) {
-    await Promise.resolve();
-  }
-}
-
 function makeConfig(overrides: Partial<NerveConfig> = {}): NerveConfig {
   return {
     senses: {
@@ -171,8 +164,6 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
-      await flushSenseWorkerForkMicrotasks(kernel);
-      await vi.runAllTimersAsync();
 
       // Simulate a sense worker sending a signal with workflow launch payload
       // The kernel's handleWorkerMessage processes "signal" type messages
@@ -231,8 +222,6 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
-      await flushSenseWorkerForkMicrotasks(kernel);
-      await vi.runAllTimersAsync();
 
       // Simulate sense worker returning a signal plus workflow launch
       const workerPool = mockChildren[0];
@@ -286,8 +275,6 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
-      await flushSenseWorkerForkMicrotasks(kernel);
-      await vi.runAllTimersAsync();
 
       const workerPool = mockChildren[0];
       if (workerPool) {
@@ -350,8 +337,6 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
-      await flushSenseWorkerForkMicrotasks(kernel);
-      await vi.runAllTimersAsync();
 
       // Emit a regular signal (shorthand payload) — should NOT trigger any workflow
       const workerPool = mockChildren[0];
@@ -402,8 +387,6 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
-      await flushSenseWorkerForkMicrotasks(kernel);
-      await vi.runAllTimersAsync();
 
       // Simulate sense compute returning a signal plus workflow launch
       const workerPool = mockChildren[0];
@@ -457,8 +440,6 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
-      await flushSenseWorkerForkMicrotasks(kernel);
-      await vi.runAllTimersAsync();
 
       // Reload with a workflow added
       const newConfig: NerveConfig = {
@@ -536,8 +517,6 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
-      await flushSenseWorkerForkMicrotasks(kernel);
-      await vi.runAllTimersAsync();
 
       // Reload with the workflow removed
       const newConfig: NerveConfig = {
@@ -621,8 +600,6 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
-      await flushSenseWorkerForkMicrotasks(kernel);
-      await vi.runAllTimersAsync();
 
       // Trigger a workflow via sense compute return value
       const workerPool = mockChildren[0];
@@ -687,8 +664,6 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
-      await flushSenseWorkerForkMicrotasks(kernel);
-      await vi.runAllTimersAsync();
 
       const health = kernel.getHealth();
       expect(health).toHaveProperty("activeWorkflows");

packages/daemon/src/__tests__/kernel.test.ts

@@ -16,12 +16,10 @@ type MockChild = EventEmitter & {
   send: ReturnType<typeof vi.fn>;
   kill: ReturnType<typeof vi.fn>;
   pid: number;
-  connected: boolean;
 };
 
 function makeMockChild(pid = 1): MockChild {
   const child = new EventEmitter() as MockChild;
-  child.connected = true;
   setImmediate(() => {
     child.emit("message", { type: "ready" });
   });
@@ -29,10 +27,7 @@ function makeMockChild(pid = 1): MockChild {
     if (msg === null || typeof msg !== "object") return;
     const m = msg as Record<string, unknown>;
     if (m.type === "shutdown") {
-      setImmediate(() => {
-        child.connected = false;
-        child.emit("exit", 0, null);
-      });
+      setImmediate(() => child.emit("exit", 0, null));
       return;
     }
     if (m.type === "compute" && typeof m.sense === "string") {
@@ -42,7 +37,6 @@ function makeMockChild(pid = 1): MockChild {
     }
   });
   child.kill = vi.fn((_signal?: string) => {
-    child.connected = false;
     child.emit("exit", null, _signal ?? "SIGKILL");
   });
   child.pid = pid;
@@ -65,14 +59,6 @@ const { createLogStore } = await import("@uncaged/nerve-store");
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** `WorkerRuntime.start` schedules `fork` on the next microtask — flush one tick per initial group. */
-async function flushSenseWorkerForkMicrotasks(kernel: { groups: Set<string> }): Promise<void> {
-  const n = kernel.groups.size;
-  for (let i = 0; i < n; i++) {
-    await Promise.resolve();
-  }
-}
-
 function makeConfig(overrides: Partial<NerveConfig> = {}): NerveConfig {
   return {
     senses: {
@@ -187,7 +173,6 @@ describe("kernel — message routing", () => {
       },
     });
     const kernel = createKernel(config, nerveRoot);
-    await flushSenseWorkerForkMicrotasks(kernel);
 
     const child = mockChildren[0];
     child.emit("message", { type: "error", sense: "cpu-usage", error: "compute failed" });
@@ -216,7 +201,6 @@ describe("kernel — message routing", () => {
       },
     });
     const kernel = createKernel(config, nerveRoot);
-    await flushSenseWorkerForkMicrotasks(kernel);
 
     const child = mockChildren[0];
     const callsBefore = stderrSpy.mock.calls.length;
@@ -244,7 +228,6 @@ describe("kernel — message routing", () => {
       },
     });
     const kernel = createKernel(config, nerveRoot);
-    await flushSenseWorkerForkMicrotasks(kernel);
 
     const child = mockChildren[0];
     expect(() => child.emit("message", { type: "unknown-type" })).not.toThrow();
@@ -307,7 +290,6 @@ describe("kernel — groupForSense mapping", () => {
       api: { port: null, token: null, host: "127.0.0.1" },
     };
     const kernel = createKernel(config, nerveRoot);
-    await flushSenseWorkerForkMicrotasks(kernel);
 
     // system and network = 2 unique groups
     expect(mockChildren.length).toBe(2);
@@ -329,10 +311,8 @@ describe("kernel — groupForSense mapping", () => {
       },
     });
     const kernel = createKernel(config, nerveRoot);
-    await flushSenseWorkerForkMicrotasks(kernel);
-    const child = mockChildren[0];
-    child.emit("message", { type: "ready" });
 
+    const child = mockChildren[0];
     vi.advanceTimersByTime(500);
 
     expect(child.send).toHaveBeenCalledWith(

packages/daemon/src/__tests__/worker-pool.test.ts

@@ -50,7 +50,6 @@ async function startWorkerWithReady(
   group: string,
 ): Promise<void> {
   const pr = pool.startWorker(group);
-  await Promise.resolve();
   const child = mockChildren[mockChildren.length - 1];
   child.emit("message", { type: "ready" });
   await pr;
@@ -138,7 +137,6 @@ describe("createSenseWorkerPool", () => {
     expect(pool.activeGroupCount()).toBe(1);
     pool.evictGroup("x");
     expect(pool.hasWorkerForGroup("x")).toBe(false);
-    await Promise.resolve();
     expect(mockChildren[0].send).toHaveBeenCalledWith(
       expect.objectContaining({ type: "shutdown" }),
     );
@@ -161,7 +159,6 @@ describe("createSenseWorkerPool", () => {
 
     const p = pool.restartGroup("g");
     expect(onBeforeGroupRestart).toHaveBeenCalledWith("g");
-    await Promise.resolve();
     expect(mockChildren[0].send).toHaveBeenCalledWith(
       expect.objectContaining({ type: "shutdown" }),
     );
@@ -174,7 +171,7 @@ describe("createSenseWorkerPool", () => {
   });
 
   it("onWorkerCrashed runs and schedules respawn after non-zero exit", async () => {
-    vi.useFakeTimers();
+    vi.useFakeTimers({ shouldAdvanceTime: true });
     const onWorkerCrashed = vi.fn();
     const pool = createSenseWorkerPool({
       nerveRoot: "/tmp/n",

packages/daemon/src/__tests__/worker-runtime.test.ts

@@ -1,180 +0,0 @@
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { createWorkerRuntime } from "../worker-runtime.js";
-
-const fixturesDir = join(dirname(fileURLToPath(import.meta.url)), "fixtures");
-const echoWorkerPath = join(fixturesDir, "echo-worker.js");
-const crashWorkerPath = join(fixturesDir, "crash-worker.js");
-const stderrWorkerPath = join(fixturesDir, "stderr-worker.js");
-
-function baseConfig(script: string) {
-  return {
-    script,
-    argsForKey: () => [],
-    forwardStderr: true,
-    onMessage: vi.fn(),
-    onReady: vi.fn(),
-    onExit: vi.fn(),
-    respawn: {
-      enabled: true,
-      maxCrashes: 6,
-      windowMs: 60_000,
-      delayMs: 80,
-      allowRespawn: null,
-    },
-    shutdownTimeoutMs: 5000,
-  };
-}
-
-describe("createWorkerRuntime", () => {
-  const runtimes: Array<{ shutdown: () => Promise<void> }> = [];
-
-  afterEach(async () => {
-    await Promise.all(runtimes.splice(0).map((r) => r.shutdown()));
-  });
-
-  function track<R extends { shutdown: () => Promise<void> }>(r: R): R {
-    runtimes.push(r);
-    return r;
-  }
-
-  it("start + send message + receive echo", async () => {
-    const incoming: unknown[] = [];
-    const rt = track(
-      createWorkerRuntime({
-        ...baseConfig(echoWorkerPath),
-        onMessage: (_key, msg) => {
-          incoming.push(msg);
-        },
-      }),
-    );
-
-    await rt.start("a");
-    expect(rt.has("a")).toBe(true);
-    await rt.send("a", { type: "ping", n: 1 });
-
-    await vi.waitFor(() => {
-      expect(incoming.some((m) => isEchoOf(m, { type: "ping", n: 1 }))).toBe(true);
-    });
-    await rt.shutdown();
-  });
-
-  it("cold start on send (no explicit start)", async () => {
-    const incoming: unknown[] = [];
-    const rt = track(
-      createWorkerRuntime({
-        ...baseConfig(echoWorkerPath),
-        onMessage: (_key, msg) => {
-          incoming.push(msg);
-        },
-      }),
-    );
-
-    expect(rt.has("x")).toBe(false);
-    await rt.send("x", { type: "hi" });
-    await vi.waitFor(() => {
-      expect(rt.has("x")).toBe(true);
-      expect(incoming.some((m) => isEchoOf(m, { type: "hi" }))).toBe(true);
-    });
-    await rt.shutdown();
-  });
-
-  it("evict stops worker; has() is false", async () => {
-    const rt = track(createWorkerRuntime(baseConfig(echoWorkerPath)));
-    await rt.start("k");
-    expect(rt.has("k")).toBe(true);
-    await rt.evict("k");
-    expect(rt.has("k")).toBe(false);
-    await rt.shutdown();
-  });
-
-  it("drain stops and respawns (new pid)", async () => {
-    const rt = track(createWorkerRuntime(baseConfig(echoWorkerPath)));
-    await rt.start("k");
-    const before = rt.pid("k");
-    expect(before).not.toBeNull();
-    await rt.drain("k");
-    const after = rt.pid("k");
-    expect(after).not.toBeNull();
-    expect(after).not.toBe(before);
-    await rt.shutdown();
-  });
-
-  it("crash triggers auto-respawn", async () => {
-    const incoming: unknown[] = [];
-    const onExit = vi.fn();
-    const rt = track(
-      createWorkerRuntime({
-        ...baseConfig(crashWorkerPath),
-        onExit,
-        onMessage: (_key, msg) => {
-          incoming.push(msg);
-        },
-      }),
-    );
-
-    await rt.start("c");
-
-    await vi.waitFor(() => expect(onExit.mock.calls.length).toBeGreaterThanOrEqual(1), {
-      timeout: 3000,
-    });
-    await vi.waitFor(() => expect(rt.has("c")).toBe(true), { timeout: 3000 });
-
-    await rt.send("c", { type: "after-crash" });
-    await vi.waitFor(() => {
-      expect(incoming.some((m) => isEchoOf(m, { type: "after-crash" }))).toBe(true);
-    });
-    await rt.shutdown();
-  });
-
-  it("crash limit reached → no more automatic respawns", async () => {
-    const rt = track(
-      createWorkerRuntime({
-        ...baseConfig(crashWorkerPath),
-        respawn: {
-          enabled: true,
-          maxCrashes: 2,
-          windowMs: 60_000,
-          delayMs: 50,
-          allowRespawn: null,
-        },
-      }),
-    );
-
-    await rt.start("z");
-
-    await vi.waitFor(() => expect(rt.has("z")).toBe(false), { timeout: 8000 });
-
-    await rt.shutdown();
-  });
-
-  it("shutdown stops all workers", async () => {
-    const rt = track(createWorkerRuntime(baseConfig(echoWorkerPath)));
-    await rt.start("a");
-    await rt.start("b");
-    expect(rt.keys().sort()).toEqual(["a", "b"].sort());
-    await rt.shutdown();
-    expect(rt.keys()).toEqual([]);
-    expect(rt.has("a")).toBe(false);
-    expect(rt.has("b")).toBe(false);
-  });
-
-  it("stderrTail captures stderr output", async () => {
-    const rt = track(createWorkerRuntime(baseConfig(stderrWorkerPath)));
-    await rt.start("s");
-    await vi.waitFor(() => {
-      expect(rt.stderrTail("s")).toContain("stderr-marker");
-    });
-    await rt.shutdown();
-  });
-});
-
-function isEchoOf(msg: unknown, payload: unknown): boolean {
-  return (
-    typeof msg === "object" &&
-    msg !== null &&
-    (msg as Record<string, unknown>).type === "echo" &&
-    JSON.stringify((msg as Record<string, unknown>).payload) === JSON.stringify(payload)
-  );
-}

packages/daemon/src/worker-pool.ts

@@ -1,13 +1,19 @@
 /**
- * Sense worker pool — thin wrapper around WorkerRuntime (RFC-006): one fork per sense group.
+ * Sense worker pool — forked child processes per sense group (IPC lifecycle).
  */
 
+import { fork } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import type { ComputeMessage } from "./ipc.js";
-import { formatCapturedStderrTail, formatChildExitSummary } from "./worker-fork-support.js";
-import { createWorkerRuntime } from "./worker-runtime.js";
+import type { ComputeMessage, ShutdownMessage } from "./ipc.js";
+import { parseWorkerMessage } from "./ipc.js";
+import {
+  formatCapturedStderrTail,
+  formatChildExitSummary,
+  teeCapturedStderr,
+} from "./worker-fork-support.js";
 
 export function resolveWorkerScript(): string {
   const __filename = fileURLToPath(import.meta.url);
@@ -15,12 +21,17 @@ export function resolveWorkerScript(): string {
   return join(__dir, "sense-worker.js");
 }
 
+type WorkerEntry = {
+  group: string;
+  process: ChildProcess;
+};
+
 export type SenseWorkerPoolOptions = {
   nerveRoot: string;
   workerScript: string;
   /** Invoked for every IPC message from a worker (including ready / signal / error). */
   onWorkerMessage: (raw: unknown) => void;
-  /** Sense names in a group — reserved for scheduler-aligned cleanup (kernel passes current config). */
+  /** Sense names in a group — used when clearing scheduler state on crash or restart. */
   sensesForGroup: (group: string) => string[];
   /**
    * Called when a worker exits with non-zero code before scheduling a respawn
@@ -47,106 +58,144 @@ export type SenseWorkerPool = {
   activeGroupCount: () => number;
 };
 
-/** Matches legacy pool: long crash window, 1s respawn delay, practical unlimited respawns. */
-const SENSE_WORKER_RESPAWN = {
-  enabled: true,
-  maxCrashes: 100_000,
-  windowMs: 86_400_000,
-  delayMs: 1000,
-} as const;
+function spawnWorker(
+  nerveRoot: string,
+  group: string,
+  workerScript: string,
+  stderrTail: { value: string },
+): ChildProcess {
+  const child = fork(workerScript, ["--group", group, "--root", nerveRoot], {
+    stdio: ["ignore", "inherit", "pipe", "ipc"],
+  });
+  teeCapturedStderr(child, stderrTail);
+  child.on("error", (err) => {
+    if ((err as NodeJS.ErrnoException).code !== "EPIPE") {
+      console.error("[worker] error:", err.message);
+    }
+  });
+  return child;
+}
+
+function sendComputeToProcess(worker: ChildProcess, senseName: string): void {
+  if (worker.connected === false) return;
+  const msg: ComputeMessage = { type: "compute", sense: senseName };
+  try {
+    worker.send(msg);
+  } catch {
+    // IPC channel closed between connected check and send
+  }
+}
+
+function sendShutdownToProcess(worker: ChildProcess): void {
+  if (worker.connected === false) return;
+  const msg: ShutdownMessage = { type: "shutdown" };
+  try {
+    worker.send(msg);
+  } catch {
+    // IPC channel closed between connected check and send
+  }
+}
+
+function waitForExit(child: ChildProcess, timeoutMs: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      resolve();
+    }, timeoutMs);
+    child.once("exit", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
 
 export function createSenseWorkerPool(options: SenseWorkerPoolOptions): SenseWorkerPool {
-  const runtime = createWorkerRuntime<string>({
-    script: options.workerScript,
-    argsForKey: (group) => ["--group", group, "--root", options.nerveRoot],
-    forwardStderr: true,
-    onMessage: (_key, raw) => {
+  const workers = new Map<string, WorkerEntry>();
+
+  function startWorker(group: string): Promise<void> {
+    const stderrTail = { value: "" };
+    const child = spawnWorker(options.nerveRoot, group, options.workerScript, stderrTail);
+
+    let workerReadyResolve: (() => void) | undefined;
+    const workerReady = new Promise<void>((resolve) => {
+      workerReadyResolve = resolve;
+    });
+
+    child.on("message", (raw: unknown) => {
+      const result = parseWorkerMessage(raw);
+      if (result.ok && result.value.type === "ready") {
+        workerReadyResolve?.();
+      }
       options.onWorkerMessage(raw);
-    },
-    onReady: (_key, msg) => {
-      options.onWorkerMessage(msg);
-    },
-    onExit: (group, code, signal) => {
-      const sig =
-        signal === null || signal === undefined || signal === ""
-          ? null
-          : (signal as NodeJS.Signals);
-      const summary = formatChildExitSummary(code, sig);
+    });
+
+    child.on("exit", (code, signal) => {
+      const summary = formatChildExitSummary(code, signal ?? null);
       process.stderr.write(
-        `[kernel] worker for group "${group}" exited (${summary})${formatCapturedStderrTail(runtime.stderrTail(group))}\n`,
+        `[kernel] worker for group "${group}" exited (${summary})${formatCapturedStderrTail(stderrTail.value)}\n`,
       );
+      workerReadyResolve?.();
       if (!options.isStopped() && code !== 0) {
         process.stderr.write(`[kernel] respawning worker for group "${group}" in 1s\n`);
         options.onWorkerCrashed(group);
+        setTimeout(() => {
+          if (!options.isStopped()) {
+            startWorker(group);
+          }
+        }, 1000);
       }
-    },
-    respawn: {
-      ...SENSE_WORKER_RESPAWN,
-      allowRespawn: (_group) => !options.isStopped(),
-    },
-    shutdownTimeoutMs: 5000,
-  });
+    });
 
-  /** Groups we have ever started — mirrors legacy Map presence for `restartGroup` no-op when unknown. */
-  const trackedGroups = new Set<string>();
-  /** Marks groups mid-evict so `hasWorkerForGroup` drops immediately (legacy synchronous eviction). */
-  const evicting = new Set<string>();
-
-  async function startWorker(group: string): Promise<void> {
-    trackedGroups.add(group);
-    await runtime.start(group);
+    workers.set(group, { group, process: child });
+    return workerReady;
   }
 
   async function restartGroup(group: string): Promise<void> {
-    if (!trackedGroups.has(group)) {
-      return;
-    }
+    const entry = workers.get(group);
+    if (entry === undefined) return;
+
     options.onBeforeGroupRestart(group);
-    await runtime.drain(group);
+
+    sendShutdownToProcess(entry.process);
+    await waitForExit(entry.process, 5000);
+
+    if (!options.isStopped()) {
+      await startWorker(group);
+    }
   }
 
   function evictGroup(group: string): void {
-    trackedGroups.delete(group);
-    evicting.add(group);
-    void runtime.evict(group).finally(() => {
-      evicting.delete(group);
-    });
+    const entry = workers.get(group);
+    if (entry === undefined) return;
+    sendShutdownToProcess(entry.process);
+    workers.delete(group);
   }
 
   async function shutdownAll(): Promise<void> {
-    await runtime.shutdown();
-    trackedGroups.clear();
-    evicting.clear();
+    const exitPromises: Promise<void>[] = [];
+    for (const entry of workers.values()) {
+      sendShutdownToProcess(entry.process);
+      exitPromises.push(waitForExit(entry.process, 5000));
+    }
+    await Promise.all(exitPromises);
   }
 
   function sendCompute(group: string, senseName: string): void {
-    if (!trackedGroups.has(group) || evicting.has(group)) {
-      return;
-    }
-    // Legacy pool: `child.send` no-op when IPC is closed (still allow cold start: child === null).
-    if (runtime.hasDisconnectedChild(group)) {
-      return;
-    }
-    const msg: ComputeMessage = { type: "compute", sense: senseName };
-    if (!runtime.trySendSync(group, msg)) {
-      void runtime.send(group, msg).catch(() => {
-        // IPC channel may close between scheduling and send — same as legacy try/catch on child.send
-      });
-    }
+    const entry = workers.get(group);
+    if (entry === undefined) return;
+    sendComputeToProcess(entry.process, senseName);
   }
 
   function getWorkerPid(group: string): number | null {
-    return runtime.pid(group);
+    return workers.get(group)?.process.pid ?? null;
   }
 
-  /** True once `startWorker` has been called for the group and it is not mid-evict (matches legacy Map key). */
   function hasWorkerForGroup(group: string): boolean {
-    return trackedGroups.has(group) && !evicting.has(group);
+    return workers.has(group);
   }
 
-  /** Count of sense groups with a worker slot (includes not-yet-ready), excluding evicted keys. */
   function activeGroupCount(): number {
-    return trackedGroups.size;
+    return workers.size;
   }
 
   return {

packages/daemon/src/worker-runtime.ts

@@ -1,404 +0,0 @@
-/**
- * Generic message-routed worker process manager (RFC-006).
- * One forked Node child per key; cold start, crash respawn, drain/evict, shutdown.
- */
-
-import { type ChildProcess, type Serializable, fork } from "node:child_process";
-import { isPlainRecord } from "@uncaged/nerve-core";
-
-const STDERR_TAIL_MAX_CHARS = 2048;
-
-export type WorkerRuntimeConfig<K extends string> = {
-  script: string;
-  argsForKey: (key: K) => string[];
-  /** When false, stderr is not captured into `stderrTail` (e.g. tests without a pipe). */
-  forwardStderr: boolean;
-  onMessage: (key: K, msg: unknown) => void;
-  onReady: (key: K, msg: unknown) => void;
-  onExit: (key: K, code: number | null, signal: string | null) => void;
-  respawn: {
-    enabled: boolean;
-    maxCrashes: number;
-    windowMs: number;
-    delayMs: number;
-    /** When non-null, return false to skip automatic respawn after an unexpected exit. */
-    allowRespawn: ((key: K) => boolean) | null;
-  };
-  shutdownTimeoutMs: number;
-};
-
-export type WorkerRuntime<K extends string> = {
-  send: (key: K, msg: unknown) => Promise<void>;
-  /** When the worker is already ready and IPC-connected, sends synchronously (returns true). Otherwise false — caller may fall back to `send`. */
-  trySendSync: (key: K, msg: unknown) => boolean;
-  start: (key: K) => Promise<void>;
-  evict: (key: K) => Promise<void>;
-  drain: (key: K) => Promise<void>;
-  shutdown: () => Promise<void>;
-  has: (key: K) => boolean;
-  /** True when a child exists but IPC is disconnected (legacy pool skipped sends in this case). */
-  hasDisconnectedChild: (key: K) => boolean;
-  pid: (key: K) => number | null;
-  keys: () => K[];
-  stderrTail: (key: K) => string;
-};
-
-type WorkerMachineState = "stopped" | "starting" | "ready" | "draining";
-
-type ReadyWaiter = {
-  resolve: () => void;
-  reject: (err: Error) => void;
-};
-
-/** Internal: one forked process slot (ManagedWorker). */
-type WorkerSlot<K extends string> = {
-  key: K;
-  state: WorkerMachineState;
-  child: ChildProcess | null;
-  pid: number | null;
-  stderrTail: string;
-  crashTimestamps: number[];
-  expectExit: boolean;
-  readyWaiters: ReadyWaiter[];
-  opChain: Promise<void>;
-};
-
-function isReadyIpcMessage(raw: unknown): boolean {
-  return isPlainRecord(raw) && raw.type === "ready";
-}
-
-function signalToString(signal: NodeJS.Signals | null): string | null {
-  if (signal === null) {
-    return null;
-  }
-  return String(signal);
-}
-
-function attachStderrTail<K extends string>(child: ChildProcess, slot: WorkerSlot<K>): void {
-  const stream = child.stderr;
-  if (stream == null) {
-    return;
-  }
-  stream.setEncoding("utf8");
-  stream.on("data", (chunk: string | Buffer) => {
-    const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
-    slot.stderrTail = (slot.stderrTail + text).slice(-STDERR_TAIL_MAX_CHARS);
-  });
-}
-
-function enqueueOp<K extends string>(slot: WorkerSlot<K>, fn: () => Promise<void>): Promise<void> {
-  const run = slot.opChain.then(fn, fn);
-  slot.opChain = run.then(
-    () => {},
-    () => {},
-  );
-  return run;
-}
-
-function resolveReadyWaiters<K extends string>(slot: WorkerSlot<K>): void {
-  const waiters = slot.readyWaiters;
-  slot.readyWaiters = [];
-  for (const w of waiters) {
-    w.resolve();
-  }
-}
-
-function rejectReadyWaiters<K extends string>(slot: WorkerSlot<K>, err: Error): void {
-  const waiters = slot.readyWaiters;
-  slot.readyWaiters = [];
-  for (const w of waiters) {
-    w.reject(err);
-  }
-}
-
-function waitForReady<K extends string>(
-  slot: WorkerSlot<K>,
-  shutdownTimeoutMs: number,
-): Promise<void> {
-  if (slot.state === "ready" && slot.child !== null && slot.child.connected) {
-    return Promise.resolve();
-  }
-  return new Promise((resolve, reject) => {
-    let settled = false;
-    const timer = setTimeout(() => {
-      if (!settled) {
-        settled = true;
-        reject(new Error(`Worker "${String(slot.key)}" ready timeout`));
-      }
-    }, shutdownTimeoutMs);
-    slot.readyWaiters.push({
-      resolve: () => {
-        if (settled) {
-          return;
-        }
-        settled = true;
-        clearTimeout(timer);
-        resolve();
-      },
-      reject: (err: Error) => {
-        if (settled) {
-          return;
-        }
-        settled = true;
-        clearTimeout(timer);
-        reject(err);
-      },
-    });
-  });
-}
-
-async function waitForChildExit(child: ChildProcess, timeoutMs: number): Promise<void> {
-  await new Promise<void>((resolve) => {
-    const timer = setTimeout(() => {
-      child.kill("SIGKILL");
-    }, timeoutMs);
-    child.once("exit", () => {
-      clearTimeout(timer);
-      resolve();
-    });
-  });
-}
-
-export function createWorkerRuntime<K extends string>(
-  config: WorkerRuntimeConfig<K>,
-): WorkerRuntime<K> {
-  const workers = new Map<K, WorkerSlot<K>>();
-
-  function getOrCreateSlot(key: K): WorkerSlot<K> {
-    let slot = workers.get(key);
-    if (slot === undefined) {
-      slot = {
-        key,
-        state: "stopped",
-        child: null,
-        pid: null,
-        stderrTail: "",
-        crashTimestamps: [],
-        expectExit: false,
-        readyWaiters: [],
-        opChain: Promise.resolve(),
-      };
-      workers.set(key, slot);
-    }
-    return slot;
-  }
-
-  function handleWorkerMessage(slot: WorkerSlot<K>, msg: unknown): void {
-    if (isReadyIpcMessage(msg)) {
-      if (slot.state === "starting") {
-        slot.state = "ready";
-        config.onReady(slot.key, msg);
-        resolveReadyWaiters(slot);
-      }
-      return;
-    }
-    config.onMessage(slot.key, msg);
-  }
-
-  function onChildExit(
-    slot: WorkerSlot<K>,
-    code: number | null,
-    signal: NodeJS.Signals | null,
-  ): void {
-    config.onExit(slot.key, code, signalToString(signal));
-
-    if (slot.child !== null) {
-      slot.child.removeAllListeners("message");
-      slot.child.removeAllListeners("exit");
-    }
-
-    const wasExpect = slot.expectExit;
-    slot.expectExit = false;
-
-    slot.child = null;
-    slot.pid = null;
-
-    if (wasExpect) {
-      slot.state = "stopped";
-      return;
-    }
-
-    rejectReadyWaiters(slot, new Error(`Worker "${String(slot.key)}" exited unexpectedly`));
-    slot.state = "stopped";
-
-    void enqueueOp(slot, async () => {
-      await handleUnexpectedCrashRecovery(slot);
-    });
-  }
-
-  function registerChild(slot: WorkerSlot<K>, child: ChildProcess): void {
-    slot.child = child;
-    slot.pid = child.pid ?? null;
-    if (config.forwardStderr) {
-      attachStderrTail(child, slot);
-    }
-    child.on("message", (msg: unknown) => {
-      handleWorkerMessage(slot, msg);
-    });
-    child.on("exit", (code, sig) => {
-      onChildExit(slot, code, sig ?? null);
-    });
-  }
-
-  async function forkAndWaitReady(slot: WorkerSlot<K>): Promise<void> {
-    if (slot.state === "ready" && slot.child !== null && slot.child.connected) {
-      return;
-    }
-
-    slot.state = "starting";
-
-    let child: ChildProcess;
-    try {
-      child = fork(config.script, config.argsForKey(slot.key), {
-        stdio: ["ignore", "inherit", "pipe", "ipc"],
-        env: process.env,
-      });
-    } catch (e) {
-      slot.state = "stopped";
-      const err = e instanceof Error ? e : new Error(String(e));
-      rejectReadyWaiters(slot, err);
-      throw err;
-    }
-
-    registerChild(slot, child);
-    await waitForReady(slot, config.shutdownTimeoutMs);
-  }
-
-  async function gracefulStop(slot: WorkerSlot<K>): Promise<void> {
-    if (slot.child === null) {
-      return;
-    }
-    slot.expectExit = true;
-    slot.state = "draining";
-    const child = slot.child;
-    try {
-      child.send({ type: "shutdown" });
-    } catch {
-      // IPC channel may have closed between null-check and send
-    }
-    await waitForChildExit(child, config.shutdownTimeoutMs);
-  }
-
-  async function handleUnexpectedCrashRecovery(slot: WorkerSlot<K>): Promise<void> {
-    if (!config.respawn.enabled) {
-      return;
-    }
-    if (config.respawn.allowRespawn !== null && !config.respawn.allowRespawn(slot.key)) {
-      return;
-    }
-
-    const now = Date.now();
-    slot.crashTimestamps.push(now);
-    slot.crashTimestamps = slot.crashTimestamps.filter((t) => now - t <= config.respawn.windowMs);
-
-    if (slot.crashTimestamps.length >= config.respawn.maxCrashes) {
-      console.error(
-        `[WorkerRuntime] worker "${String(slot.key)}" exceeded crash limit (${String(config.respawn.maxCrashes)} in ${String(config.respawn.windowMs)}ms); not respawning`,
-      );
-      return;
-    }
-
-    await new Promise<void>((resolve) => setTimeout(resolve, config.respawn.delayMs));
-    await forkAndWaitReady(slot);
-  }
-
-  async function shutdownWorker(slot: WorkerSlot<K>): Promise<void> {
-    await gracefulStop(slot);
-    workers.delete(slot.key);
-  }
-
-  function isActive(slot: WorkerSlot<K>): boolean {
-    return slot.state === "ready" && slot.child !== null && slot.child.connected;
-  }
-
-  return {
-    send: async (key: K, msg: unknown) => {
-      const slot = getOrCreateSlot(key);
-      await enqueueOp(slot, async () => {
-        await forkAndWaitReady(slot);
-        const child = slot.child;
-        if (child === null || !child.connected) {
-          throw new Error(`Worker "${String(key)}" is not connected`);
-        }
-        child.send(msg as Serializable);
-      });
-    },
-
-    trySendSync: (key: K, msg: unknown): boolean => {
-      const slot = workers.get(key);
-      if (slot === undefined || !isActive(slot)) {
-        return false;
-      }
-      const child = slot.child;
-      if (child === null || !child.connected) {
-        return false;
-      }
-      try {
-        child.send(msg as Serializable);
-        return true;
-      } catch {
-        return false;
-      }
-    },
-
-    start: async (key: K) => {
-      const slot = getOrCreateSlot(key);
-      await enqueueOp(slot, async () => {
-        await forkAndWaitReady(slot);
-      });
-    },
-
-    evict: async (key: K) => {
-      const slot = getOrCreateSlot(key);
-      await enqueueOp(slot, async () => {
-        await gracefulStop(slot);
-        workers.delete(key);
-      });
-    },
-
-    drain: async (key: K) => {
-      const slot = getOrCreateSlot(key);
-      await enqueueOp(slot, async () => {
-        if (slot.child === null) {
-          await forkAndWaitReady(slot);
-          return;
-        }
-        await gracefulStop(slot);
-        await forkAndWaitReady(slot);
-      });
-    },
-
-    shutdown: async () => {
-      const snapshot = [...workers.values()];
-      await Promise.all(snapshot.map((slot) => enqueueOp(slot, () => shutdownWorker(slot))));
-    },
-
-    has: (key: K) => {
-      const slot = workers.get(key);
-      return slot !== undefined && isActive(slot);
-    },
-
-    hasDisconnectedChild: (key: K): boolean => {
-      const slot = workers.get(key);
-      if (slot === undefined || slot.child === null) {
-        return false;
-      }
-      return !slot.child.connected;
-    },
-
-    pid: (key: K) => {
-      const slot = workers.get(key);
-      if (slot === undefined || !isActive(slot) || slot.pid === null) {
-        return null;
-      }
-      return slot.pid;
-    },
-
-    keys: () => [...workers.values()].filter((slot) => isActive(slot)).map((slot) => slot.key),
-
-    stderrTail: (key: K) => {
-      const slot = workers.get(key);
-      return slot === undefined ? "" : slot.stderrTail;
-    },
-  };
-}

packages/workflow-meta/src/develop-sense/roles/coder.ts

@@ -10,7 +10,7 @@ export type CoderMeta = z.infer<typeof coderMetaSchema>;
 
 export function coderPrompt({ threadId }: { threadId: string }): string {
   return `Read the workflow thread for the planner's sense design and any tester feedback: \`nerve thread ${threadId}\`
-Read the nerve-dev skill for sense file structure and conventions: \`cat node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md\`
+Read \`cat AGENT.md\` from the repository root, then \`CONVENTIONS.md\` and \`.knowledge/sense.md\` if present.
 
 ## Your task
 
@@ -20,21 +20,21 @@ Implement (or fix) the sense the planner designed. If there is tester feedback i
 
 You do NOT need to finish everything in one pass. You may return \`done: false\` to continue in the next iteration.
 
-## File structure for each sense
+## File structure for each sense (flat workspace)
 
-- \`senses/<name>/src/index.ts\` — TypeScript compute source; import schema as \`./schema.ts\`
+The workspace has **one root** \`package.json\` and root \`scripts/build.mjs\` (or equivalent) that bundles all senses. There is **no** per-sense \`package.json\`. Bundled output is \`dist/senses/<name>/index.js\` after a root build.
+
+- \`senses/<name>/src/index.ts\` — compute entry; import schema as \`./schema.ts\`
 - \`senses/<name>/src/schema.ts\` — Drizzle schema (TypeScript)
-- \`senses/<name>/migrations/\` — Drizzle migration files (at sense root, not inside src/)
-- \`senses/<name>/package.json\` — with esbuild build script
-- \`senses/<name>/index.js\` — bundled output generated by \`pnpm build\` (do NOT edit by hand)
+- \`senses/<name>/migrations/\` — SQL migration files (at sense root, not inside \`src/\`)
 
-Look at existing senses for the package.json template and patterns.
+Look at existing senses for patterns.
 
 ## When to return done: true
 
 Return \`done: true\` ONLY when ALL of the following are true:
 - All required files are created
-- \`pnpm install --no-cache && pnpm build\` succeeds (run it!)
+- From the **workspace root**, \`pnpm run build\` or \`npm run build\` succeeds (run it!) and \`dist/senses/<name>/index.js\` exists
 - \`nerve.yaml\` is updated with the sense config
 
 Return \`done: false\` if you made progress but there is still work to do.`;

packages/workflow-meta/src/develop-sense/roles/planner.ts

@@ -12,7 +12,7 @@ export function plannerPrompt({ threadId }: { threadId: string }): string {
   return `You are planning a new Nerve sense.
 
 Read the workflow thread for the user's request: \`nerve thread ${threadId}\`
-Read the nerve-dev skill for sense conventions: \`cat node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md\`
+Read the workspace guide: \`cat AGENT.md\` from the repository root (created by \`nerve init\`). Also read \`CONVENTIONS.md\` and \`.knowledge/sense.md\` if present. Optional skills live under \`.cursor/skills/\`.
 Also look at existing senses in the \`senses/\` directory for patterns.
 
 Pick a good kebab-case name for this sense. Produce a PLAN (not code) in markdown:

packages/workflow-meta/src/develop-sense/roles/tester.ts

@@ -17,21 +17,20 @@ export function testerPrompt({
 **IMPORTANT: The Nerve workspace is at \`${nerveRoot}\`. All paths below are relative to this directory. Always \`cd ${nerveRoot}\` first.**
 
 Read the workflow thread for context: \`nerve thread ${threadId}\`
-Read the nerve-dev skill for expected file structure: \`cat ${nerveRoot}/node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md\`
+Read \`cat ${nerveRoot}/AGENT.md\`, then \`${nerveRoot}/CONVENTIONS.md\` and \`${nerveRoot}/.knowledge/sense.md\` if they exist.
 
 Verify the full lifecycle in this order:
 
-1. **File check** — all required sense files exist:
+1. **File check** — all required sense files exist (no per-sense \`package.json\`):
    - \`senses/<name>/src/index.ts\`
    - \`senses/<name>/src/schema.ts\`
    - \`senses/<name>/migrations/\`
-   - \`senses/<name>/package.json\`
 
-2. **Build** — run inside the sense directory:
+2. **Build** — from the workspace root:
    \`\`\`
-   cd ${nerveRoot}/senses/<name> && pnpm install --no-cache && pnpm build
+   cd ${nerveRoot} && pnpm run build
    \`\`\`
-   Must produce \`index.js\` at sense root without errors.
+   (or \`npm run build\` per root \`package.json\`.) Must produce \`${nerveRoot}/dist/senses/<name>/index.js\` without errors.
 
 3. **Config check** — \`nerve validate\` passes, confirming nerve.yaml is valid.
 

packages/workflow-meta/src/develop-workflow/roles/coder.ts

@@ -10,7 +10,7 @@ export type CoderMeta = z.infer<typeof coderMetaSchema>;
 
 export function coderPrompt({ threadId }: { threadId: string }): string {
   return `Read the workflow thread to get the planner's design and any reviewer/tester/committer feedback: \`nerve thread ${threadId}\`
-Read the nerve-dev skill for workflow file structure and conventions: \`cat node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md\`
+Read \`cat AGENT.md\` from the repository root, then \`CONVENTIONS.md\` and \`.knowledge/workflow.md\` if present. Optional skills live under \`.cursor/skills/\`.
 Also look at existing workflows in the \`workflows/\` directory for patterns.
 
 ## Your task
@@ -29,15 +29,13 @@ You do NOT need to finish everything in one pass. You may return \`done: false\`
 2. Second pass: implement role logic
 3. Third pass: fix build/lint errors
 
-## Workflow file structure
+## Workflow file structure (flat workspace)
+
+The workspace has **one root** \`package.json\` and **one** root build (\`pnpm run build\` or \`npm run build\`), implemented by \`scripts/build.mjs\`, which emits bundles under \`dist/workflows/<name>/index.js\`. There is **no** per-workflow \`package.json\` or \`tsconfig.json\`.
 
 Each workflow must have:
-- \`workflows/<name>/index.ts\` — WorkflowDefinition default export
-- \`workflows/<name>/build.ts\` — factory function
-- \`workflows/<name>/moderator.ts\` — moderator + meta types
-- \`workflows/<name>/roles/<role>.ts\` — meta schema and prompt function per role
-- \`workflows/<name>/package.json\` — with esbuild build script
-- \`workflows/<name>/tsconfig.json\` — TypeScript config
+- \`workflows/<name>/index.ts\` — default export \`WorkflowDefinition\` (moderator and meta types typically live here or are imported from co-located modules)
+- \`workflows/<name>/roles/<role>.ts\` — one TypeScript file per role (schemas, prompts, \`createRole\` wiring, or plain async role functions)
 
 For **new workflows**, also update \`nerve.yaml\` with \`workflows.<name>\`.
 
@@ -53,7 +51,7 @@ For **new workflows**, also update \`nerve.yaml\` with \`workflows.<name>\`.
 
 Return \`done: true\` ONLY when ALL of the following are true:
 - All changes from the plan are implemented
-- \`cd workflows/<name> && pnpm install --no-cache && pnpm build\` succeeds (run it!)
+- From the **workspace root**, \`pnpm run build\` or \`npm run build\` succeeds (run it!) so \`dist/workflows/<name>/index.js\` is produced
 - No lint or type errors remain
 
 Return \`done: false\` if you made progress but there is still work to do, or if build/lint has errors you plan to fix in the next iteration.`;

packages/workflow-meta/src/develop-workflow/roles/planner.ts

@@ -12,18 +12,18 @@ export function plannerPrompt({ threadId }: { threadId: string }): string {
   return `You are a Nerve workflow planner. You can **create new workflows** or **modify existing ones**.
 
 Read the workflow thread for the user's request: \`nerve thread ${threadId}\`
-Read the nerve-dev skill for workflow conventions: \`cat node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md\`
+Read the workspace guide: \`cat AGENT.md\` from the repository root (created by \`nerve init\`). Also read \`CONVENTIONS.md\` if it exists; if \`.knowledge/workflow.md\` exists (e.g. Nerve monorepo), read it for layout and engine behavior. Optional Cursor skills live under \`.cursor/skills/\`.
 List existing workflows: \`ls workflows/\`
 
 ## Determine the task type
 
-1. If the user wants to **modify an existing workflow** — read its current code (\`cat workflows/<name>/moderator.ts\`, \`cat workflows/<name>/build.ts\`, \`ls workflows/<name>/roles/\`, etc.) and understand its current structure before planning changes.
+1. If the user wants to **modify an existing workflow** — read its current code (\`cat workflows/<name>/index.ts\`, \`ls workflows/<name>/roles/\`, \`cat workflows/<name>/roles/<role>.ts\`, etc.) and understand its current structure before planning changes.
 2. If the user wants to **create a new workflow** — look at existing workflows in \`workflows/\` for patterns to follow.
 
 ## Produce a PLAN (not code) in markdown
 
 For **new workflows**:
-- Workflow name (kebab-case)
+- Workflow name — **verb-first** kebab-case phrase (e.g. \`review-pull-request\`, \`deploy-staging\`), not a bare noun
 - Roles list (name, purpose, tool)
 - Flow transitions / moderator routing logic
 - Validation loops design

packages/workflow-meta/src/develop-workflow/roles/tester.ts

@@ -17,24 +17,22 @@ export function testerPrompt({
 **IMPORTANT: The Nerve workspace is at \`${nerveRoot}\`. All paths below are relative to this directory. Always \`cd ${nerveRoot}\` first.**
 
 Read the workflow thread for context: \`nerve thread ${threadId}\`
-Read the nerve-dev skill for expected file structure: \`cat ${nerveRoot}/node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md\`
+Read \`cat ${nerveRoot}/AGENT.md\`, then \`${nerveRoot}/CONVENTIONS.md\` and \`${nerveRoot}/.knowledge/workflow.md\` if they exist.
 
 Get the workflow name from the thread (the planner's output).
 
 Verify the full lifecycle in this order:
 
-1. **File check** — all required workflow files exist (under \`${nerveRoot}/\`):
+1. **File check** — all required workflow sources exist (under \`${nerveRoot}/\`):
    - \`workflows/<name>/index.ts\`
-   - \`workflows/<name>/build.ts\`
-   - \`workflows/<name>/moderator.ts\`
-   - \`workflows/<name>/roles/\` with one \`.ts\` file per role
-   - \`workflows/<name>/package.json\`
+   - \`workflows/<name>/roles/\` with one \`.ts\` file per role (flat files, not per-role packages)
+   - **No** \`workflows/<name>/package.json\` or \`tsconfig.json\` expected
 
-2. **Build** — run inside the workflow directory:
+2. **Build** — from the workspace root:
    \`\`\`
-   cd ${nerveRoot}/workflows/<name> && pnpm install --no-cache && pnpm build
+   cd ${nerveRoot} && pnpm run build
    \`\`\`
-   Must produce \`dist/index.js\` without errors.
+   (or \`npm run build\` if that is what the root \`package.json\` defines.) Must produce \`${nerveRoot}/dist/workflows/<name>/index.js\` without errors.
 
 3. **Config check** — \`cd ${nerveRoot} && nerve validate\` passes, confirming nerve.yaml is valid.