feat(workflow-utils): dryRun support for spawnSafe, cursorAgent, llmExtract

When dryRun=true, each function logs its parameters and returns a stub result without executing any subprocess or network call. Log output is captured by log-store for analysis. - spawnSafe: returns { exitCode: 0, stdout: '[dryRun] skipped' } - cursorAgent: short-circuits before spawnSafe, returns ok('[dryRun] skipped') - llmExtract: skips fetch, returns ok({} as T) - Tests added for spawnSafe and llmExtract dryRun paths Fixes #104
Merge pull request 'feat(core,daemon,cli): add dryRun thread-level parameter to StartSignal' (#103 ) from feat/101-dry-run into main
2026-04-25 00:23:43 +00:00 · 2026-04-24 23:50:55 +00:00 · 2026-04-24 23:45:29 +00:00 · 2026-04-24 23:35:09 +00:00 · 2026-04-24 23:14:45 +00:00 · 2026-04-24 22:43:07 +00:00
40 changed files with 1488 additions and 299 deletions
@@ -7,28 +7,31 @@ Nerve is a lightweight daemon that continuously observes external state through
 ## Core Concepts

 ```
-External World → Sense → Signal → Reflex → Workflow → Log
-                  ↑                                     ↑
-              "what to observe"                  "what to do"
+External World → Sense ─┬→ Signal → Reflex → Sense (scheduled compute)
+                        │
+                        └→ Workflow (Sense return with workflow directive) → Log
 ```

 | Concept | Metaphor | Role |
 |---------|----------|------|
 | **Sense** | 👁️ Perception | A `compute()` function that samples or derives data. Each sense has its own SQLite database. |
-| **Reflex** | ⚡ Reaction | Declarative trigger — interval-based, event-driven, or both. Connects senses to actions. |
-| **Signal** | 📡 Notification | Emitted when a sense returns non-null. Other reflexes can listen for signals. |
-| **Workflow** | 🔧 Action | Stateful multi-step execution with Roles (actors) and a Moderator (coordinator). |
+| **Reflex** | ⚡ Reaction | Declarative rules that **only schedule Sense computes** (interval and/or `on` signal names). Reflex YAML cannot reference workflows. |
+| **Signal** | 📡 Notification | Emitted when a sense returns a non-null value that is routed as a normal signal (see Sense → Workflow below). Other reflexes can listen via `on`. |
+| **Workflow** | 🔧 Action | Stateful multi-step execution with Roles and a Moderator. Started from a Sense return value or from CLI/daemon IPC—not from reflex YAML. |
 | **Log** | 📝 Record | Immutable audit trail. Queryable by senses, but **cannot** trigger reflexes (prevents feedback loops). |

-Three extension points, fully orthogonal — a Sense doesn't know when it runs, a Reflex doesn't know what it computes, a Workflow doesn't know why it was triggered.
+**Sense → Workflow:** if `compute()` returns a plain object with a string field `workflow` in the form `name|maxRounds|prompt` (only the first two `|` delimit name and rounds; the rest is the prompt), the engine starts that workflow and **does not** emit a Signal for that return. `workflow: null` or `""` means “emit a signal” and strip the key from the payload. Invalid `workflow` strings are treated like a normal signal (directive stripped). See `@uncaged/nerve-core` `routeSenseComputeOutput` / `parseSenseWorkflowDirective`.
+
+Three extension points for **what / when / multi-step action** — reflexes never replace Sense-driven workflow launches.

 ## Packages

 | Package | Description |
 |---------|-------------|
-| [`@uncaged/nerve-core`](./packages/core) | Shared types and config parser |
-| [`@uncaged/nerve-daemon`](./packages/daemon) | The observation engine — kernel, sense runtime, reflex scheduler, workflow manager |
-| [`@uncaged/nerve-cli`](./packages/cli) | CLI tool (`nerve`) — init, start, stop, logs, query |
+| [`@uncaged/nerve-core`](./packages/core) | Shared types, config parser, Sense→workflow routing, daemon IPC protocol |
+| [`@uncaged/nerve-store`](./packages/store) | Append-only log SQLite, JSONL archive, CAS blob store, workflow run rows |
+| [`@uncaged/nerve-daemon`](./packages/daemon) | Kernel, workers, signal bus, reflex scheduler, workflow manager, file watcher, IPC |
+| [`@uncaged/nerve-cli`](./packages/cli) | CLI (`nerve`) — init, validate, daemon, dev, logs, sense, store, workflow |

 ## Quick Start

@@ -70,15 +73,17 @@ nerve logs         # view logs

 ## Configuration

-`nerve.yaml` declares senses, reflexes, and workflows:
+`nerve.yaml` declares senses, reflexes (sense-only), optional workflows (concurrency), and optional engine `max_rounds`:

 ```yaml
+max_rounds: 100              # default moderator cap (e.g. CLI workflow trigger)
+
 senses:
  cpu-usage:
    group: system          # senses in the same group share a worker process
    throttle: 10s          # min interval between computes
    timeout: 30s           # max compute duration
-    gracePeriod: 5s        # wait before first compute after startup
+    grace_period: 5s       # wait before first compute after startup

 reflexes:
  - kind: sense
@@ -86,10 +91,6 @@ reflexes:
    interval: 30s          # periodic trigger
    on: [disk-pressure]    # also trigger on signals from other senses

-  - kind: workflow
-    workflow: cleanup
-    on: [disk-pressure]    # start a workflow when signal fires
-
 workflows:
  cleanup:
    concurrency: 1
@@ -97,43 +98,66 @@ workflows:
  code-review:
    concurrency: 3
    overflow: queue
-    maxQueue: 20
+    max_queue: 20
+```
+
+YAML must **not** include `workflow:` under `reflexes` — the parser rejects it. Declare workflows under `workflows:` and start them from Sense `compute()` or `nerve workflow trigger`.
+
+**Example — Sense starts a workflow** (`senses/disk-pressure/compute.ts`):
+
+```typescript
+export async function compute() {
+  const full = await diskNearlyFull();
+  if (!full) return null;
+  return {
+    path: "/data",
+    workflow: "cleanup|10|Disk partition nearly full", // name|maxRounds|prompt
+  };
+}
 ```

 ## Architecture

 ```
-┌─────────────────────────────────────────────────────────┐
-│  Kernel                                                 │
-│                                                         │
-│  ┌──────────┐   ┌──────────┐   ┌──────────┐           │
-│  │ Worker   │   │ Worker   │   │ Worker   │  (1 per   │
-│  │ (group A)│   │ (group B)│   │ (group C)│   group)  │
-│  │ sense-1  │   │ sense-3  │   │ sense-5  │           │
-│  │ sense-2  │   │ sense-4  │   │          │           │
-│  └────┬─────┘   └────┬─────┘   └────┬─────┘           │
-│       │              │              │                   │
-│       └──────────────┼──────────────┘                   │
-│                      ▼                                  │
-│              ┌──────────────┐                           │
-│              │  Signal Bus  │                           │
-│              └──────┬───────┘                           │
-│                     ▼                                   │
-│           ┌──────────────────┐                          │
-│           │ Reflex Scheduler │                          │
-│           └────────┬─────────┘                          │
-│                    ▼                                    │
-│          ┌───────────────────┐                          │
-│          │ Workflow Manager  │──→ Log Store (SQLite)    │
-│          └───────────────────┘                          │
-└─────────────────────────────────────────────────────────┘
+┌────────────────────────────────────────────────────────────────────────┐
+│  Kernel                                                                 │
+│                                                                         │
+│  ┌──────────────┐   watches nerve.yaml / senses / workflows            │
+│  │ File Watcher ├──────────────────────────────────────────┐           │
+│  └──────────────┘                                          │           │
+│  ┌──────────────┐   CLI ↔ newline JSON (trigger-workflow, │           │
+│  │ Daemon IPC   │   trigger-sense, list-senses)            │           │
+│  └──────┬───────┘                                          ▼           │
+│         │            ┌──────────┐   ┌──────────┐   ┌──────────┐        │
+│         │            │ Worker   │   │ Worker   │   │ Worker   │ (1 per│
+│         │            │ (group A)│   │ (group B)│   │ (group C)│ group) │
+│         │            │ sense-1  │   │ sense-3  │   │ sense-5  │        │
+│         │            │ sense-2  │   │ sense-4  │   │          │        │
+│         │            └────┬─────┘   └────┬─────┘   └────┬─────┘        │
+│         │                 │              │              │            │
+│         │                 └──────────────┼──────────────┘            │
+│         │                                ▼                            │
+│         │                        ┌──────────────┐                     │
+│         │                        │  Signal Bus  │                     │
+│         │                        └──────┬───────┘                     │
+│         │                               ▼                             │
+│         │                     ┌──────────────────┐                      │
+│         │                     │ Reflex Scheduler│                      │
+│         │                     └────────┬─────────┘                     │
+│         │                              ▼                              │
+│         │                    ┌───────────────────┐                    │
+│         └───────────────────►│ Workflow Manager  │──→ @uncaged/nerve-store │
+│                              └───────────────────┘    (logs.db, …)   │
+└────────────────────────────────────────────────────────────────────────┘
 ```

- **Worker processes** — one per sense group, forked by the kernel. Isolated compute execution.
+- **Worker pool** — one child process per sense group; isolation between groups.
 - **Signal Bus** — in-memory pub/sub for signal distribution.
 - **Reflex Scheduler** — interval timers + signal subscriptions, with throttle/coalesce.
- **Workflow Manager** — concurrency control (drop/queue), thread lifecycle tracking.
- **Log Store** — WAL-mode SQLite via `node:sqlite`, with archival and retention policies.
+- **Workflow Manager** — concurrency (drop/queue), per-workflow workers, crash recovery.
+- **File watcher** — hot reload for config, sense modules, and workflow modules.
+- **Daemon IPC** — Unix domain socket; used by the CLI when the daemon is running.
+- **Log / blob storage** — implemented in `@uncaged/nerve-store` (WAL SQLite, JSONL archive, CAS blobs).

 ## Tech Stack

@@ -21,41 +21,59 @@ nerve init                  # Initialize a nerve workspace (installs deps, scaff
 nerve validate              # Validate nerve.yaml configuration
 ```

-### Daemon Management
+### Daemon management

 ```bash
 nerve daemon start          # Start the daemon (background)
 nerve daemon stop           # Stop the daemon
-nerve daemon status         # Check daemon health
-nerve daemon restart        # Restart the daemon
-nerve daemon logs           # Tail daemon logs
+nerve daemon status         # Show pid, uptime, sense names from nerve.yaml (process must exist)
+nerve daemon restart        # Stop then start
+nerve daemon logs           # Tail daemon process logs (file under workspace logs/)
 ```

 ### Development

 ```bash
-nerve dev                   # Run in foreground mode (no daemon, Ctrl+C to stop)
+nerve dev                   # Foreground kernel with file watcher + IPC (Ctrl+C stops)
 ```

-### Querying
+### Querying & status

 ```bash
-nerve logs                  # View structured logs
-nerve sense query <name>    # Query a sense's SQLite database
-nerve sense schema <name>   # Show a sense's database schema
-nerve status                # Daemon health summary
+nerve logs                  # Tail or page the daemon text log file (path in footer; default ~/.uncaged-nerve/logs/nerve.log)
+nerve status                # Short daemon health summary (aliases daemon status)
+```
+
+Structured rows in `data/logs.db` are surfaced via **`nerve workflow inspect`** / **`nerve workflow list`** (and `LogStore` in code), not via `nerve logs`.
+
+### Sense
+
+```bash
+nerve sense list            # List senses (live fields from daemon IPC when running)
+nerve sense trigger <name>  # IPC trigger-sense — queue a compute for that sense
+nerve sense query <name>    # Read-only SQL on data/senses/<name>.db (optional SQL args)
+nerve sense schema <name>   # Print CREATE TABLE statements for that sense DB
+```
+
+### Store maintenance
+
+```bash
+nerve store archive         # Move old log rows to JSONL under data/archive/logs/… (optional --vacuum)
 ```

 ### Workflows

 ```bash
-nerve workflow list         # List workflow runs
-nerve workflow show <runId> # Show workflow run details
+nerve workflow list         # Queued/started runs (add --all for terminal states; --workflow, --limit, --offset)
+nerve workflow inspect <runId>   # Run metadata + paginated workflow log lines
+nerve workflow thread <runId>    # Role rounds from persisted messages (--before, --budget)
+nerve workflow trigger <name>    # IPC trigger-workflow (daemon must be running)
+                                   # Optional JSON: --payload '{"prompt":"…","maxRounds":50}'
 ```

-### Top-level Aliases
+`nerve workflow trigger` sends a `trigger-workflow` line on the daemon Unix socket (same protocol as `@uncaged/nerve-core` / `parseDaemonIpcRequest`). It does not read `nerve.yaml` workflow definitions beyond what the running daemon already loaded.

-For convenience, these aliases are available:
+### Top-level aliases

 ```bash
 nerve start    → nerve daemon start
@@ -3,7 +3,7 @@
  "engines": {
    "node": ">=22.5.0"
  },
-  "version": "0.3.0",
+  "version": "0.4.0",
  "type": "module",
  "bin": {
    "nerve": "dist/cli.js"
@@ -514,7 +514,7 @@ describe("triggerWorkflowViaDaemon", () => {
    await new Promise<void>((r) => server.listen(sockPath, r));

    try {
-      const result = await triggerWorkflowViaDaemon(sockPath, "my-workflow", {});
+      const result = await triggerWorkflowViaDaemon(sockPath, "my-workflow", "", 100);
      expect(result).toEqual({ ok: true });
    } finally {
      await new Promise<void>((r) => server.close(() => r()));
@@ -530,7 +530,7 @@ describe("triggerWorkflowViaDaemon", () => {
    await new Promise<void>((r) => server.listen(sockPath, r));

    try {
-      const result = await triggerWorkflowViaDaemon(sockPath, "missing", {});
+      const result = await triggerWorkflowViaDaemon(sockPath, "missing", "", 100);
      expect(result).toEqual({ ok: false, error: "unknown workflow" });
    } finally {
      await new Promise<void>((r) => server.close(() => r()));
@@ -538,7 +538,7 @@ describe("triggerWorkflowViaDaemon", () => {
  });

  it("rejects when no daemon is listening on the socket", async () => {
-    await expect(triggerWorkflowViaDaemon(sockPath, "my-workflow", {})).rejects.toThrow(
+    await expect(triggerWorkflowViaDaemon(sockPath, "my-workflow", "", 100)).rejects.toThrow(
      /Cannot connect to daemon/,
    );
  });
@@ -1,7 +1,8 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";

-import { isPlainRecord } from "@uncaged/nerve-core";
+import type { DaemonIpcTriggerResponse } from "@uncaged/nerve-core";
+import { DEFAULT_ENGINE_MAX_ROUNDS, isPlainRecord } from "@uncaged/nerve-core";
 import { defineCommand } from "citty";
 import { stringify } from "yaml";

@@ -513,7 +514,8 @@ const workflowTriggerCommand = defineCommand({
    },
    payload: {
      type: "string",
-      description: "JSON payload to pass as trigger payload (default: {})",
+      description:
+        'JSON with optional "prompt" (string), "maxRounds" (number), and "dryRun" (boolean) for the workflow run (default: {})',
      default: "{}",
    },
  },
@@ -526,15 +528,25 @@ const workflowTriggerCommand = defineCommand({
      process.exit(1);
    }

+    let prompt = "";
+    let maxRounds = DEFAULT_ENGINE_MAX_ROUNDS;
+    let dryRun = false;
+    if (isPlainRecord(triggerPayload)) {
+      const p = triggerPayload;
+      if (typeof p.prompt === "string") prompt = p.prompt;
+      if (typeof p.maxRounds === "number") maxRounds = p.maxRounds;
+      if (typeof p.dryRun === "boolean") dryRun = p.dryRun;
+    }
+
    if (!isRunning()) {
      process.stderr.write("❌ Nerve daemon is not running. Start it with `nerve start`.\n");
      process.exit(1);
    }

    const socketPath = getSocketPath();
-    let response: { ok: true } | { ok: false; error: string };
+    let response: DaemonIpcTriggerResponse;
    try {
-      response = await triggerWorkflowViaDaemon(socketPath, args.name, triggerPayload);
+      response = await triggerWorkflowViaDaemon(socketPath, args.name, prompt, maxRounds, dryRun);
    } catch (e) {
      const msg = e instanceof Error ? e.message : String(e);
      process.stderr.write(`❌ Failed to contact daemon: ${msg}\n`);
@@ -8,7 +8,12 @@
 import { connect } from "node:net";
 import type { Socket } from "node:net";

-import type { SenseInfo } from "@uncaged/nerve-core";
+import type {
+  DaemonIpcListSensesResponse,
+  DaemonIpcRequest,
+  DaemonIpcTriggerResponse,
+  SenseInfo,
+} from "@uncaged/nerve-core";
 import { isPlainRecord } from "@uncaged/nerve-core";

 const CONNECT_TIMEOUT_MS = 3_000;
@@ -16,10 +21,6 @@ const RESPONSE_TIMEOUT_MS = 5_000;

 export type { SenseInfo };

-type TriggerResponse = { ok: true } | { ok: false; error: string };
-
-type ListSensesResponse = { ok: true; senses: SenseInfo[] } | { ok: false; error: string };
-
 function isSenseInfo(value: unknown): value is SenseInfo {
  if (!isPlainRecord(value)) return false;
  return (
@@ -31,7 +32,7 @@ function isSenseInfo(value: unknown): value is SenseInfo {
  );
 }

-function parseDaemonResponse(line: string): TriggerResponse {
+function parseDaemonResponse(line: string): DaemonIpcTriggerResponse {
  try {
    const obj: unknown = JSON.parse(line);
    if (isPlainRecord(obj)) {
@@ -45,7 +46,7 @@ function parseDaemonResponse(line: string): TriggerResponse {
  return { ok: false, error: `Unexpected daemon response: ${line}` };
 }

-function parseListSensesResponse(line: string): ListSensesResponse {
+function parseListSensesResponse(line: string): DaemonIpcListSensesResponse {
  try {
    const obj: unknown = JSON.parse(line);
    if (isPlainRecord(obj)) {
@@ -67,7 +68,7 @@ function parseListSensesResponse(line: string): ListSensesResponse {
 */
 function sendAndReceive<T>(
  socketPath: string,
-  message: object,
+  message: DaemonIpcRequest,
  parseFirstLine: (trimmed: string) => T,
  responseTimeoutMs: number = RESPONSE_TIMEOUT_MS,
 ): Promise<T> {
@@ -132,27 +133,37 @@ function sendAndReceive<T>(
 export function triggerWorkflowViaDaemon(
  socketPath: string,
  workflow: string,
-  payload: unknown,
-): Promise<TriggerResponse> {
-  return sendAndReceive(
-    socketPath,
-    { type: "trigger-workflow", workflow, payload },
-    parseDaemonResponse,
-  );
+  prompt: string,
+  maxRounds: number,
+  dryRun = false,
+): Promise<DaemonIpcTriggerResponse> {
+  const message: DaemonIpcRequest = {
+    type: "trigger-workflow",
+    workflow,
+    prompt,
+    maxRounds,
+    dryRun,
+  };
+  return sendAndReceive(socketPath, message, parseDaemonResponse);
 }

 /**
 * Send a trigger-sense message to the running daemon via its Unix socket.
 * Resolves with the daemon's response or rejects on connection/timeout errors.
 */
-export function triggerSenseViaDaemon(socketPath: string, sense: string): Promise<TriggerResponse> {
-  return sendAndReceive(socketPath, { type: "trigger-sense", sense }, parseDaemonResponse);
+export function triggerSenseViaDaemon(
+  socketPath: string,
+  sense: string,
+): Promise<DaemonIpcTriggerResponse> {
+  const message: DaemonIpcRequest = { type: "trigger-sense", sense };
+  return sendAndReceive(socketPath, message, parseDaemonResponse);
 }

 /**
 * Send a list-senses message to the running daemon via its Unix socket.
 * Resolves with the list of registered senses or rejects on connection/timeout errors.
 */
-export function listSensesViaDaemon(socketPath: string): Promise<ListSensesResponse> {
-  return sendAndReceive(socketPath, { type: "list-senses" }, parseListSensesResponse);
+export function listSensesViaDaemon(socketPath: string): Promise<DaemonIpcListSensesResponse> {
+  const message: DaemonIpcRequest = { type: "list-senses" };
+  return sendAndReceive(socketPath, message, parseListSensesResponse);
 }
@@ -4,9 +4,12 @@ Shared types and configuration parser for the [nerve](../../README.md) observati

 ## What's Inside

- **Type definitions** — `Signal`, `SenseConfig`, `ReflexConfig`, `WorkflowConfig`, `NerveConfig`, and all related types
- **Config parser** — `parseNerveConfig(yaml)` validates and parses `nerve.yaml` into a typed `NerveConfig`
- **Result type** — `Result<T>` with `ok()` / `err()` helpers for explicit error handling (no thrown exceptions)
+- **Type definitions** — `Signal`, `SenseConfig`, `SenseInfo`, `SenseReflexConfig`, `ReflexConfig` (sense-only), `WorkflowConfig`, `NerveConfig`, and related types
+- **Config parser** — `parseNerveConfig(yaml)` validates and parses `nerve.yaml` into `NerveConfig` (rejects reflex entries that declare a `workflow` key; reflexes only schedule senses)
+- **Sense → workflow routing** — `parseSenseWorkflowDirective`, `routeSenseComputeOutput`, and types `ParsedSenseWorkflowDirective`, `SenseComputeRoute`
+- **Daemon IPC protocol** — request/response types (`DaemonIpcRequest`, `DaemonIpcResponse`, …) and `parseDaemonIpcRequest` for newline-delimited JSON on the CLI ↔ daemon socket
+- **Workflow automaton types** — `START` / `END` sentinel constants, `WorkflowMessage`, `StartSignal`, `RoleSignal`, `Moderator`, `WorkflowDefinition`, `Role`, `SenseResult`, plus `DEFAULT_ENGINE_MAX_ROUNDS`
+- **Result type** — `Result<T>` with `ok()` / `err()` helpers for explicit error handling (no thrown exceptions for parse paths)

 ## Usage

@@ -20,6 +23,29 @@ if (result.ok) {
 }
 ```

+### Sense return → signal vs workflow
+
+```typescript
+import { parseSenseWorkflowDirective, routeSenseComputeOutput } from "@uncaged/nerve-core";
+
+const directive = parseSenseWorkflowDirective("my-workflow|8|Hello from sense");
+if (directive.ok) {
+  console.log(directive.value.workflowName, directive.value.maxRounds, directive.value.prompt);
+}
+
+const route = routeSenseComputeOutput({
+  metric: 42,
+  workflow: "my-workflow|8|Run now",
+});
+if (route.kind === "launch") {
+  // engine starts workflow; no Signal to the bus for this return
+  console.log(route.launch);
+} else {
+  // normal signal with payload
+  console.log(route.payload);
+}
+```
+
 ## Duration Format

 Config fields like `throttle`, `timeout`, and `interval` accept human-readable durations:
@@ -1,6 +1,6 @@
 {
  "name": "@uncaged/nerve-core",
-  "version": "0.3.0",
+  "version": "0.4.0",
  "type": "module",
  "main": "dist/index.js",
  "files": ["dist"],
@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+
+import { parseDaemonIpcRequest } from "../daemon-ipc-protocol.js";
+
+describe("parseDaemonIpcRequest", () => {
+  it("parses trigger-workflow", () => {
+    expect(
+      parseDaemonIpcRequest(
+        JSON.stringify({
+          type: "trigger-workflow",
+          workflow: "wf",
+          prompt: "go",
+          maxRounds: 3,
+        }),
+      ),
+    ).toEqual({
+      type: "trigger-workflow",
+      workflow: "wf",
+      prompt: "go",
+      maxRounds: 3,
+      dryRun: false,
+    });
+  });
+
+  it("parses trigger-workflow with dryRun true", () => {
+    expect(
+      parseDaemonIpcRequest(
+        JSON.stringify({
+          type: "trigger-workflow",
+          workflow: "wf",
+          prompt: "go",
+          maxRounds: 3,
+          dryRun: true,
+        }),
+      ),
+    ).toEqual({
+      type: "trigger-workflow",
+      workflow: "wf",
+      prompt: "go",
+      maxRounds: 3,
+      dryRun: true,
+    });
+  });
+
+  it("rejects trigger-workflow with empty workflow", () => {
+    expect(
+      parseDaemonIpcRequest(
+        JSON.stringify({
+          type: "trigger-workflow",
+          workflow: "",
+          prompt: "",
+          maxRounds: 1,
+        }),
+      ),
+    ).toBeNull();
+  });
+
+  it("parses trigger-sense and list-senses", () => {
+    expect(parseDaemonIpcRequest(JSON.stringify({ type: "trigger-sense", sense: "x" }))).toEqual({
+      type: "trigger-sense",
+      sense: "x",
+    });
+    expect(parseDaemonIpcRequest(JSON.stringify({ type: "list-senses" }))).toEqual({
+      type: "list-senses",
+    });
+  });
+
+  it("returns null for invalid JSON or unknown type", () => {
+    expect(parseDaemonIpcRequest("not json")).toBeNull();
+    expect(parseDaemonIpcRequest(JSON.stringify({ type: "nope" }))).toBeNull();
+  });
+});
@@ -0,0 +1,94 @@
+/**
+ * Daemon Unix-socket IPC protocol (CLI → daemon).
+ * Newline-delimited JSON: one request object per line from the client,
+ * one response object per line from the daemon.
+ */
+
+import { isPlainRecord } from "./is-plain-record.js";
+import type { SenseInfo } from "./types.js";
+
+/** Client → daemon: start a workflow run. */
+export type DaemonIpcTriggerWorkflowRequest = {
+  type: "trigger-workflow";
+  workflow: string;
+  prompt: string;
+  maxRounds: number;
+  dryRun: boolean;
+};
+
+/** Client → daemon: run a sense compute on demand. */
+export type DaemonIpcTriggerSenseRequest = {
+  type: "trigger-sense";
+  sense: string;
+};
+
+/** Client → daemon: list registered senses. */
+export type DaemonIpcListSensesRequest = {
+  type: "list-senses";
+};
+
+/** Union of all JSON requests the daemon IPC server accepts. */
+export type DaemonIpcRequest =
+  | DaemonIpcTriggerWorkflowRequest
+  | DaemonIpcTriggerSenseRequest
+  | DaemonIpcListSensesRequest;
+
+/** Successful trigger / trigger-sense reply (no body). */
+export type DaemonIpcTriggerOkResponse = { ok: true };
+
+export type DaemonIpcErrorResponse = { ok: false; error: string };
+
+/** Replies for trigger-workflow and trigger-sense. */
+export type DaemonIpcTriggerResponse = DaemonIpcTriggerOkResponse | DaemonIpcErrorResponse;
+
+/** Reply for list-senses. */
+export type DaemonIpcListSensesResponse =
+  | { ok: true; senses: SenseInfo[] }
+  | DaemonIpcErrorResponse;
+
+/** Any JSON response the daemon may write on the IPC socket. */
+export type DaemonIpcResponse =
+  | DaemonIpcTriggerOkResponse
+  | DaemonIpcErrorResponse
+  | { ok: true; senses: SenseInfo[] };
+
+function parseTriggerWorkflowFields(
+  req: Record<string, unknown>,
+): DaemonIpcTriggerWorkflowRequest | null {
+  if (typeof req.workflow !== "string" || req.workflow.length === 0) return null;
+  if (typeof req.prompt !== "string") return null;
+  if (typeof req.maxRounds !== "number") return null;
+  const dryRun = typeof req.dryRun === "boolean" ? req.dryRun : false;
+  return {
+    type: "trigger-workflow",
+    workflow: req.workflow,
+    prompt: req.prompt,
+    maxRounds: req.maxRounds,
+    dryRun,
+  };
+}
+
+/**
+ * Parse a single line of JSON into a {@link DaemonIpcRequest}, or null if invalid.
+ * Kept in core with the request types so CLI and daemon stay aligned at compile time.
+ */
+export function parseDaemonIpcRequest(line: string): DaemonIpcRequest | null {
+  try {
+    const obj: unknown = JSON.parse(line);
+    if (!isPlainRecord(obj)) return null;
+    const req = obj;
+    if (req.type === "trigger-workflow") {
+      return parseTriggerWorkflowFields(req);
+    }
+    if (req.type === "trigger-sense") {
+      if (typeof req.sense !== "string" || req.sense.length === 0) return null;
+      return { type: "trigger-sense", sense: req.sense };
+    }
+    if (req.type === "list-senses") {
+      return { type: "list-senses" };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
@@ -14,6 +14,7 @@ export type {
  RoleMeta,
  StartSignal,
  RoleSignal,
+  ModeratorContext,
  Moderator,
  WorkflowDefinition,
  SenseResult,
@@ -32,3 +33,16 @@ export {
  parseSenseWorkflowDirective,
  routeSenseComputeOutput,
 } from "./sense-workflow-directive.js";
+
+export type {
+  DaemonIpcTriggerWorkflowRequest,
+  DaemonIpcTriggerSenseRequest,
+  DaemonIpcListSensesRequest,
+  DaemonIpcRequest,
+  DaemonIpcTriggerOkResponse,
+  DaemonIpcErrorResponse,
+  DaemonIpcTriggerResponse,
+  DaemonIpcListSensesResponse,
+  DaemonIpcResponse,
+} from "./daemon-ipc-protocol.js";
+export { parseDaemonIpcRequest } from "./daemon-ipc-protocol.js";
@@ -76,20 +76,24 @@ export type WorkflowMessage = {
 export type RoleResult<Meta> = { content: string; meta: Meta };

 /**
- * A Role is a pure async function: receives the full message chain,
- * returns typed content + meta. Implementation can be an agent, LLM call,
+ * A Role is a pure async function: receives the engine start frame plus prior
+ * role messages only (the start frame is not included in `messages`).
+ * Returns typed content + meta. Implementation can be an agent, LLM call,
 * script, HTTP request, etc.
 */
-export type Role<Meta> = (messages: WorkflowMessage[]) => Promise<RoleResult<Meta>>;
+export type Role<Meta> = (
+  start: StartSignal,
+  messages: WorkflowMessage[],
+) => Promise<RoleResult<Meta>>;

 /** Maps role names to their meta types — the single generic that drives all inference. */
 export type RoleMeta = Record<string, Record<string, unknown>>;

-/** First message in the thread chain (`messages[0]`) — passed to the moderator on start. */
+/** Engine start frame: prompt, max rounds cap, dry-run flag, and timestamps for the thread. */
 export type StartSignal = {
  role: START;
  content: string;
-  meta: { maxRounds: number };
+  meta: { maxRounds: number; dryRun: boolean };
  timestamp: number;
 };

@@ -99,11 +103,19 @@ export type RoleSignal<M extends RoleMeta> = {
 }[keyof M & string];

 /**
- * The moderator — a pure routing function. Receives the last signal,
+ * Moderator input: either the initial start frame or a role signal after a step.
+ * Lets implementations branch on `context.kind` with full typing for each arm.
+ */
+export type ModeratorContext<M extends RoleMeta> =
+  | { kind: "start"; start: StartSignal }
+  | { kind: "step"; signal: RoleSignal<M> };
+
+/**
+ * The moderator — a pure routing function. Receives start vs step context,
 * current round, and maxRounds. Returns the next role name or END.
 */
 export type Moderator<M extends RoleMeta> = (
-  signal: StartSignal | RoleSignal<M>,
+  context: ModeratorContext<M>,
  round: number,
  maxRounds: number,
 ) => (keyof M & string) | END;
@@ -4,18 +4,33 @@ The observation engine runtime for [nerve](../../README.md) — runs senses, rou

 ## Architecture

-| Module | Responsibility |
-|--------|---------------|
-| **Kernel** | Top-level orchestrator — spawns workers, wires up signal bus, scheduler, and workflow manager. Supports hot reload and graceful shutdown. |
-| **Sense Runtime** | Per-sense SQLite database (via `node:sqlite` + Drizzle ORM), migration runner, peer DB read access. |
-| **Sense Worker** | Forked child process — one per sense group. Runs compute functions in isolation. |
-| **Signal Bus** | In-memory pub/sub. Sense computes emit signals; reflexes and workflows subscribe. |
-| **Reflex Scheduler** | Drives compute triggers — interval timers, signal-based events, throttle/coalesce logic. |
-| **Workflow Manager** | Concurrency control (drop/queue), thread lifecycle, worker process management (RFC-002). |
-| **Log Store** | Structured log storage in WAL-mode SQLite. Supports retention policies, archival to JSONL, and workflow run tracking. |
-| **Blob Store** | Binary artifact storage for workflow outputs. |
-| **File Watcher** | Watches `nerve.yaml` and sense files for hot reload. |
-| **Daemon IPC** | Unix socket server for CLI ↔ daemon communication. |
+| Module | Source (indicative) | Responsibility |
+|--------|---------------------|----------------|
+| **Kernel** | `kernel.ts` | Orchestrator — worker pool, signal bus, reflex scheduler, workflow manager, optional file watcher and daemon IPC, config reload hooks |
+| **Worker pool** | `worker-pool.ts` | Fork and supervise one child process per sense group; restart/shutdown; crash cleanup hooks for scheduler state |
+| **Kernel sense groups** | `kernel-sense-groups.ts` | Derive sense groups from config; list senses per group for scheduling |
+| **Sense runtime** | sense worker + Drizzle | Per-sense SQLite (`node:sqlite`), migrations, peer DB reads |
+| **Sense worker** | `sense-worker.ts` (fork target) | Child process entry — runs `compute()` per sense in a group |
+| **Signal bus** | `signal-bus.ts` | In-memory pub/sub for sense signals |
+| **Reflex scheduler** | `reflex-scheduler.ts` | Interval + `on` subscriptions, throttle/coalesce |
+| **Workflow manager** | `workflow-manager.ts` | One worker per workflow name, concurrency (drop/queue), queue caps |
+| **Workflow worker** | `workflow-worker.ts` | Child process — runs RFC-002 threads (`start-thread`, `resume-thread` IPC) |
+| **IPC (parent ↔ workers)** | `ipc.ts` | Typed messages for sense and workflow workers (includes `resume-thread` for recovery) |
+| **Log / workflow persistence** | via `@uncaged/nerve-store` | Structured logs, `workflow_runs`, thread messages (used for recovery) |
+| **Blob store** | `@uncaged/nerve-store` | CAS under `data/blobs/` — sense workers construct `createBlobStore(join(nerveRoot, "data", "blobs"))` for artifact writes |
+| **File watcher** | `file-watcher.ts` | Watches workspace paths for config / sense / workflow file changes |
+| **Kernel file watch** | `kernel-file-watch.ts` | Maps watcher events to `reloadConfig`, sense group restart, workflow `drainAndRespawn` |
+| **Daemon IPC** | `daemon-ipc.ts` | Unix socket server — parses `@uncaged/nerve-core` `DaemonIpcRequest`, dispatches trigger-workflow / trigger-sense / list-senses |
+
+## Crash recovery (workflow workers)
+
+If a workflow worker exits unexpectedly while threads are active:
+
+- In-flight runs are marked **`crashed`** in the log store; the manager respawns a fresh worker.
+- Runs still in **`started`** state can be **`resume-thread`**’d: the manager rebuilds the message chain from persisted workflow log rows and sends `resume-thread` to the new worker.
+- **Crash-loop backoff:** repeated crashes for the same workflow name are counted in a sliding window (`60s`); after **`5`** crashes in that window, the manager **stops respawning** that worker and logs the condition (avoids tight crash loops).
+
+Hot reload (`drainAndRespawn`) uses a controlled drain: in-flight runs may be marked **`interrupted`** when the old worker is torn down after a timeout — that path is distinct from unexpected crash recovery.

 ## Key Design Decisions

@@ -26,24 +41,44 @@ The observation engine runtime for [nerve](../../README.md) — runs senses, rou

 ## Usage

-The daemon is typically started via the CLI (`nerve daemon start`), but can be used programmatically:
+The daemon is typically started via the CLI (`nerve daemon start` / `nerve dev`), but you can embed the kernel:

 ```typescript
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parseNerveConfig } from "@uncaged/nerve-core";
 import { createKernel } from "@uncaged/nerve-daemon";

-const kernel = await createKernel(nerveRoot);
+const nerveRoot = "/path/to/workspace";
+const yamlPath = join(nerveRoot, "nerve.yaml");
+const parsed = parseNerveConfig(readFileSync(yamlPath, "utf8"));
+if (!parsed.ok) {
+  throw parsed.error;
+}
+
+const kernel = createKernel(parsed.value, nerveRoot, {
+  enableFileWatcher: true,
+  ipcSocketPath: join(nerveRoot, "nerve.sock"),
+});
+
 await kernel.ready;

-// Trigger a sense manually
 kernel.triggerSense("cpu-usage");
-
-// Check health
 const health = kernel.getHealth();

-// Graceful shutdown
 await kernel.stop();
 ```

+`createKernel(config, nerveRoot, options?)` — `config` is a parsed `NerveConfig`; `nerveRoot` is the workspace root (contains `nerve.yaml`, `data/`, etc.). Optional `KernelOptions`:
+
+| Field | Meaning |
+|-------|---------|
+| `workerScript` | Override path to the sense worker entry script (defaults to the package’s resolved worker) |
+| `enableFileWatcher` | Watch config / senses / workflows for hot reload |
+| `logStore` | Inject a `LogStore` instance (defaults to `createLogStore(join(nerveRoot, "data", "logs.db"))`) |
+| `ipcSocketPath` | When non-null, listen for daemon IPC on this Unix socket path |
+
 ## Install

 ```bash
@@ -1,6 +1,6 @@
 {
  "name": "@uncaged/nerve-daemon",
-  "version": "0.3.0",
+  "version": "0.4.0",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
@@ -127,8 +127,8 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("my-wf", { prompt: "test 1", maxRounds: 10 });
-      mgr.startWorkflow("my-wf", { prompt: "test 2", maxRounds: 10 });
+      mgr.startWorkflow("my-wf", { prompt: "test 1", maxRounds: 10, dryRun: false });
+      mgr.startWorkflow("my-wf", { prompt: "test 2", maxRounds: 10, dryRun: false });
      expect(mgr.activeCount("my-wf")).toBe(2);

      // Simulate unexpected exit (not shutdown)
@@ -154,8 +154,8 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
-      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
+      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
      expect(mgr.activeCount("my-wf")).toBe(2);

      const child = mockChildren[0];
@@ -179,7 +179,7 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
      expect(mockChildren).toHaveLength(1);

      const child = mockChildren[0];
@@ -212,7 +212,7 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
      const firstChild = mockChildren[0];
      firstChild.exitCode = 1;
      firstChild.connected = false;
@@ -256,7 +256,7 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

      // Start one thread to fill the concurrency slot (so queued run stays queued on respawn)
-      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
      const firstChild = mockChildren[0];
      firstChild.exitCode = 1;
      firstChild.connected = false;
@@ -281,7 +281,7 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });

      const child = mockChildren[0];
      const startCall = (child.send as ReturnType<typeof vi.fn>).mock.calls[0];
@@ -317,7 +317,7 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      const launch = { prompt: "build-docker for myrepo", maxRounds: 10 };
+      const launch = { prompt: "build-docker for myrepo", maxRounds: 10, dryRun: false };
      mgr.startWorkflow("my-wf", launch);

      const startedCall = logStore.upsertWorkflowRun.mock.calls.find(
@@ -327,7 +327,11 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
      const logEntry = startedCall?.[0] as { payload: string | null };
      expect(logEntry.payload).not.toBeNull();
      const parsed = JSON.parse(logEntry.payload as string) as Record<string, unknown>;
-      expect(parsed).toMatchObject({ prompt: "build-docker for myrepo", maxRounds: 10 });
+      expect(parsed).toMatchObject({
+        prompt: "build-docker for myrepo",
+        maxRounds: 10,
+        dryRun: false,
+      });

      const stopPromise = mgr.stop();
      await vi.runAllTimersAsync();
@@ -349,7 +353,7 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

      // Start one thread to fill the concurrency slot
-      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
      const firstChild = mockChildren[0];

      // Crash once → respawn → crash again → second respawn
@@ -385,7 +389,7 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
      const firstChild = mockChildren[0];
      firstChild.exitCode = 1;
      firstChild.connected = false;
@@ -415,7 +419,7 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("crash-wf", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("crash-wf", { prompt: "test", maxRounds: 10, dryRun: false });

      // Crash the worker 6 times in rapid succession (within CRASH_WINDOW_MS = 60s)
      for (let i = 0; i < 6; i++) {
@@ -2,7 +2,7 @@
 * Unit + integration tests for daemon-ipc.ts — trigger-sense request type.
 *
 * Tests cover:
- *   - parseRequest correctly accepts/rejects trigger-sense messages
+ *   - parseDaemonIpcRequest (core) / server correctly accept or reject trigger-sense messages
 *   - createDaemonIpcServer routes trigger-sense to opts.triggerSense
 *   - Error response when triggerSense throws (unknown sense)
 *   - Success response on valid sense trigger
@@ -154,6 +154,7 @@ describe("daemon-ipc — trigger-sense", () => {
      workflow: "my-workflow",
      prompt: "test prompt",
      maxRounds: 10,
+      dryRun: false,
    });

    expect(resp).toEqual({ ok: true });
@@ -161,6 +162,7 @@ describe("daemon-ipc — trigger-sense", () => {
    expect(wfManager.startWorkflow).toHaveBeenCalledWith("my-workflow", {
      prompt: "test prompt",
      maxRounds: 10,
+      dryRun: false,
    });
  });

@@ -102,7 +102,7 @@ describe("WorkflowManager — drainAndRespawn (Phase 3 hot reload)", () => {
    const config = makeWfConfig({ "my-wf": { concurrency: 1, overflow: "drop" } });
    const mgr = createWorkflowManager("/nerve-root", config, logStore);

-    mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+    mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
    expect(mockChildren).toHaveLength(1);

    // Remove workflow from config before drain completes
@@ -121,8 +121,8 @@ describe("WorkflowManager — drainAndRespawn (Phase 3 hot reload)", () => {
    const config = makeWfConfig({ "my-wf": { concurrency: 2, overflow: "drop" } });
    const mgr = createWorkflowManager("/nerve-root", config, logStore);

-    mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
-    mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+    mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
+    mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
    expect(mgr.activeCount("my-wf")).toBe(2);

    const drainPromise = mgr.drainAndRespawn("my-wf", 5000);
@@ -153,7 +153,7 @@ describe("WorkflowManager — drainAndRespawn (Phase 3 hot reload)", () => {
    const config = makeWfConfig({ "my-wf": { concurrency: 1, overflow: "drop" } });
    const mgr = createWorkflowManager("/nerve-root", config, logStore);

-    mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+    mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
    expect(mockChildren).toHaveLength(1);

    const drainPromise = mgr.drainAndRespawn("my-wf", 5000);
@@ -169,7 +169,7 @@ describe("WorkflowManager — drainAndRespawn (Phase 3 hot reload)", () => {
    const config = makeWfConfig({ "my-wf": { concurrency: 1, overflow: "drop" } });
    const mgr = createWorkflowManager("/nerve-root", config, logStore);

-    mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+    mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
    expect(mockChildren).toHaveLength(1);

    const drainPromise = mgr.drainAndRespawn("my-wf", 5000);
@@ -186,7 +186,7 @@ describe("WorkflowManager — drainAndRespawn (Phase 3 hot reload)", () => {
    const config = makeWfConfig({ "my-wf": { concurrency: 1, overflow: "drop" } });
    const mgr = createWorkflowManager("/nerve-root", config, logStore);

-    mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+    mgr.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });

    const drainPromise = mgr.drainAndRespawn("my-wf", 5000);
    await vi.runAllTimersAsync();
@@ -211,14 +211,14 @@ describe("WorkflowManager — drainAndRespawn (Phase 3 hot reload)", () => {
    const config = makeWfConfig({ "my-wf": { concurrency: 1, overflow: "drop" } });
    const mgr = createWorkflowManager("/nerve-root", config, logStore);

-    mgr.startWorkflow("my-wf", { prompt: "first", maxRounds: 10 });
+    mgr.startWorkflow("my-wf", { prompt: "first", maxRounds: 10, dryRun: false });

    const drainPromise = mgr.drainAndRespawn("my-wf", 5000);
    await vi.runAllTimersAsync();
    await drainPromise;

    // Start a new thread on the fresh worker
-    mgr.startWorkflow("my-wf", { prompt: "second", maxRounds: 10 });
+    mgr.startWorkflow("my-wf", { prompt: "second", maxRounds: 10, dryRun: false });

    const newChild = mockChildren[1];
    const startCalls = (newChild.send as ReturnType<typeof vi.fn>).mock.calls.filter(
@@ -261,7 +261,7 @@ describe("Kernel — workflow hot reload via file-watcher (Phase 3)", () => {
    });

    // Trigger a workflow thread so a worker is spawned
-    kernel.workflowManager.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+    kernel.workflowManager.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });

    // Manually call drainAndRespawn (simulating what kernel does on workflow file change)
    const drainPromise = kernel.workflowManager.drainAndRespawn("my-wf", 1000);
@@ -296,7 +296,11 @@ describe("Kernel — workflow hot reload via file-watcher (Phase 3)", () => {
    });

    // Spawn a worker for old-wf
-    kernel.workflowManager.startWorkflow("old-wf", { prompt: "test", maxRounds: 10 });
+    kernel.workflowManager.startWorkflow("old-wf", {
+      prompt: "test",
+      maxRounds: 10,
+      dryRun: false,
+    });
    expect(mockChildren).toHaveLength(1);

    // Reload config without old-wf
@@ -334,7 +338,7 @@ describe("Kernel — workflow hot reload via file-watcher (Phase 3)", () => {
      logStore,
    });

-    kernel.workflowManager.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+    kernel.workflowManager.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
    const workersBefore = mockChildren.length;

    // Reload with updated concurrency — should NOT spawn a new workflow worker
@@ -354,8 +358,8 @@ describe("Kernel — workflow hot reload via file-watcher (Phase 3)", () => {
    expect(kernel.workflowManager.activeCount("my-wf")).toBe(1);

    // Can now start up to 5 concurrent threads (previously only 1)
-    kernel.workflowManager.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
-    kernel.workflowManager.startWorkflow("my-wf", { prompt: "test", maxRounds: 10 });
+    kernel.workflowManager.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
+    kernel.workflowManager.startWorkflow("my-wf", { prompt: "test", maxRounds: 10, dryRun: false });
    expect(kernel.workflowManager.activeCount("my-wf")).toBe(3);

    const stopPromise = kernel.stop();
@@ -202,6 +202,7 @@ describe("kernel + workflowManager integration", () => {
        workflow: "alert-workflow",
        prompt: "handle critical alert",
        maxRounds: 5,
+        dryRun: false,
      });

      const stopPromise = kernel.stop();
@@ -115,7 +115,7 @@ describe("WorkflowManager", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("my-workflow", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("my-workflow", { prompt: "test", maxRounds: 10, dryRun: false });

      expect(mockChildren).toHaveLength(1);
      expect(mockChildren[0].send).toHaveBeenCalledWith(
@@ -131,8 +131,8 @@ describe("WorkflowManager", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("my-workflow", { prompt: "test 1", maxRounds: 10 });
-      mgr.startWorkflow("my-workflow", { prompt: "test 2", maxRounds: 10 });
+      mgr.startWorkflow("my-workflow", { prompt: "test 1", maxRounds: 10, dryRun: false });
+      mgr.startWorkflow("my-workflow", { prompt: "test 2", maxRounds: 10, dryRun: false });

      // Only one forked child — worker is reused
      expect(mockChildren).toHaveLength(1);
@@ -147,7 +147,7 @@ describe("WorkflowManager", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("my-workflow", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("my-workflow", { prompt: "test", maxRounds: 10, dryRun: false });

      expect(logStore.upsertWorkflowRun).toHaveBeenCalledWith(
        expect.objectContaining({ source: "workflow", type: "started" }),
@@ -164,9 +164,9 @@ describe("WorkflowManager", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("drop-wf", { prompt: "first", maxRounds: 10 });
+      mgr.startWorkflow("drop-wf", { prompt: "first", maxRounds: 10, dryRun: false });
      // now at limit — second call should be dropped
-      mgr.startWorkflow("drop-wf", { prompt: "second", maxRounds: 10 });
+      mgr.startWorkflow("drop-wf", { prompt: "second", maxRounds: 10, dryRun: false });

      expect(mgr.activeCount("drop-wf")).toBe(1);
      expect(mgr.queueLength("drop-wf")).toBe(0);
@@ -181,8 +181,8 @@ describe("WorkflowManager", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("drop-wf", { prompt: "test", maxRounds: 10 });
-      mgr.startWorkflow("drop-wf", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("drop-wf", { prompt: "test", maxRounds: 10, dryRun: false });
+      mgr.startWorkflow("drop-wf", { prompt: "test", maxRounds: 10, dryRun: false });

      const droppedCall = logStore.upsertWorkflowRun.mock.calls.find(
        ([entry]) => entry.type === "dropped",
@@ -199,8 +199,8 @@ describe("WorkflowManager", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("queue-wf", { prompt: "first", maxRounds: 10 });
-      mgr.startWorkflow("queue-wf", { prompt: "second", maxRounds: 10 });
+      mgr.startWorkflow("queue-wf", { prompt: "first", maxRounds: 10, dryRun: false });
+      mgr.startWorkflow("queue-wf", { prompt: "second", maxRounds: 10, dryRun: false });

      expect(mgr.activeCount("queue-wf")).toBe(1);
      expect(mgr.queueLength("queue-wf")).toBe(1);
@@ -213,8 +213,8 @@ describe("WorkflowManager", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("queue-wf", { prompt: "test", maxRounds: 10 });
-      mgr.startWorkflow("queue-wf", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("queue-wf", { prompt: "test", maxRounds: 10, dryRun: false });
+      mgr.startWorkflow("queue-wf", { prompt: "test", maxRounds: 10, dryRun: false });

      const queuedCall = logStore.upsertWorkflowRun.mock.calls.find(
        ([entry]) => entry.type === "queued",
@@ -233,12 +233,12 @@ describe("WorkflowManager", () => {
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

      // Fill the concurrency slot
-      mgr.startWorkflow("queue-wf", { prompt: "test 0", maxRounds: 10 });
+      mgr.startWorkflow("queue-wf", { prompt: "test 0", maxRounds: 10, dryRun: false });
      // Fill the queue to maxQueue
-      mgr.startWorkflow("queue-wf", { prompt: "test 1", maxRounds: 10 });
-      mgr.startWorkflow("queue-wf", { prompt: "test 2", maxRounds: 10 });
+      mgr.startWorkflow("queue-wf", { prompt: "test 1", maxRounds: 10, dryRun: false });
+      mgr.startWorkflow("queue-wf", { prompt: "test 2", maxRounds: 10, dryRun: false });
      // This one should push out the oldest
-      mgr.startWorkflow("queue-wf", { prompt: "test 3", maxRounds: 10 });
+      mgr.startWorkflow("queue-wf", { prompt: "test 3", maxRounds: 10, dryRun: false });

      // Queue should still be at maxQueue (2)
      expect(mgr.queueLength("queue-wf")).toBe(2);
@@ -259,8 +259,8 @@ describe("WorkflowManager", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("queue-wf", { prompt: "first", maxRounds: 10 });
-      mgr.startWorkflow("queue-wf", { prompt: "second", maxRounds: 10 });
+      mgr.startWorkflow("queue-wf", { prompt: "first", maxRounds: 10, dryRun: false });
+      mgr.startWorkflow("queue-wf", { prompt: "second", maxRounds: 10, dryRun: false });

      expect(mgr.activeCount("queue-wf")).toBe(1);
      expect(mgr.queueLength("queue-wf")).toBe(1);
@@ -294,8 +294,8 @@ describe("WorkflowManager", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("queue-wf", { prompt: "first", maxRounds: 10 });
-      mgr.startWorkflow("queue-wf", { prompt: "second", maxRounds: 10 });
+      mgr.startWorkflow("queue-wf", { prompt: "first", maxRounds: 10, dryRun: false });
+      mgr.startWorkflow("queue-wf", { prompt: "second", maxRounds: 10, dryRun: false });

      const child = mockChildren[0];
      const firstRunId = (child.send as ReturnType<typeof vi.fn>).mock.calls[0][0].runId as string;
@@ -321,8 +321,8 @@ describe("WorkflowManager", () => {
      });
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("wf-a", { prompt: "test", maxRounds: 10 });
-      mgr.startWorkflow("wf-b", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("wf-a", { prompt: "test", maxRounds: 10, dryRun: false });
+      mgr.startWorkflow("wf-b", { prompt: "test", maxRounds: 10, dryRun: false });

      // Two distinct workers should have been forked
      expect(mockChildren).toHaveLength(2);
@@ -348,7 +348,7 @@ describe("WorkflowManager", () => {
      await vi.runAllTimersAsync();
      await stopPromise;

-      mgr.startWorkflow("wf-a", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("wf-a", { prompt: "test", maxRounds: 10, dryRun: false });

      // No worker should have been spawned
      expect(mockChildren).toHaveLength(0);
@@ -361,7 +361,7 @@ describe("WorkflowManager", () => {
      const config = makeConfig({});
      const mgr = createWorkflowManager("/nerve-root", config, logStore);

-      mgr.startWorkflow("no-such-workflow", { prompt: "test", maxRounds: 10 });
+      mgr.startWorkflow("no-such-workflow", { prompt: "test", maxRounds: 10, dryRun: false });

      expect(mockChildren).toHaveLength(0);
      expect(logStore.upsertWorkflowRun).not.toHaveBeenCalled();
@@ -2,83 +2,24 @@
 * Daemon IPC server — listens on a Unix domain socket so that the CLI
 * can send commands (e.g. trigger-workflow, trigger-sense) to the running daemon process.
 *
- * Protocol: newline-delimited JSON messages.
- * Each request: { type: "trigger-workflow"; workflow: string; payload: unknown }
- *             | { type: "trigger-sense"; sense: string }
- *             | { type: "list-senses" }
- * Each response: { ok: true } | { ok: false; error: string }
- *              | { ok: true; senses: SenseInfo[] }  (for list-senses)
+ * Protocol: newline-delimited JSON — request/response types and
+ * `parseDaemonIpcRequest` live in `@uncaged/nerve-core`.
 */

 import { rmSync } from "node:fs";
 import { type Server, type Socket, createServer } from "node:net";

-import type { SenseInfo } from "@uncaged/nerve-core";
-import { isPlainRecord } from "@uncaged/nerve-core";
+import type { DaemonIpcResponse, SenseInfo } from "@uncaged/nerve-core";
+import { parseDaemonIpcRequest } from "@uncaged/nerve-core";

 import type { WorkflowManager } from "./workflow-manager.js";

 export type { SenseInfo };

-/** JSON message sent by the CLI to trigger a workflow. */
-export type TriggerWorkflowRequest = {
-  type: "trigger-workflow";
-  workflow: string;
-  prompt: string;
-  maxRounds: number;
-};
-
-/** JSON message sent by the CLI to trigger a sense compute on-demand. */
-export type TriggerSenseRequest = {
-  type: "trigger-sense";
-  sense: string;
-};
-
-/** JSON message sent by the CLI to list registered senses. */
-export type ListSensesRequest = {
-  type: "list-senses";
-};
-
-type DaemonRequest = TriggerWorkflowRequest | TriggerSenseRequest | ListSensesRequest;
-
-type DaemonResponse =
-  | { ok: true }
-  | { ok: false; error: string }
-  | { ok: true; senses: SenseInfo[] };
-
 export type DaemonIpcServer = {
  close: () => Promise<void>;
 };

-function parseRequest(line: string): DaemonRequest | null {
-  try {
-    const obj: unknown = JSON.parse(line);
-    if (!isPlainRecord(obj)) return null;
-    const req = obj;
-    if (req.type === "trigger-workflow") {
-      if (typeof req.workflow !== "string" || req.workflow.length === 0) return null;
-      if (typeof req.prompt !== "string") return null;
-      if (typeof req.maxRounds !== "number") return null;
-      return {
-        type: "trigger-workflow",
-        workflow: req.workflow,
-        prompt: req.prompt,
-        maxRounds: req.maxRounds,
-      };
-    }
-    if (req.type === "trigger-sense") {
-      if (typeof req.sense !== "string" || req.sense.length === 0) return null;
-      return { type: "trigger-sense", sense: req.sense };
-    }
-    if (req.type === "list-senses") {
-      return { type: "list-senses" };
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
 export type DaemonIpcServerOptions = {
  /** Called when a trigger-sense request arrives. Should throw if the sense is unknown. */
  triggerSense: (senseName: string) => void;
@@ -102,9 +43,9 @@ export function createDaemonIpcServer(
    const trimmed = line.trim();
    if (trimmed.length === 0) return;

-    const req = parseRequest(trimmed);
+    const req = parseDaemonIpcRequest(trimmed);
    if (req === null) {
-      const resp: DaemonResponse = { ok: false, error: "Invalid request" };
+      const resp: DaemonIpcResponse = { ok: false, error: "Invalid request" };
      socket.write(`${JSON.stringify(resp)}\n`);
      return;
    }
@@ -114,21 +55,25 @@ export function createDaemonIpcServer(
        workflowManager.startWorkflow(req.workflow, {
          prompt: req.prompt,
          maxRounds: req.maxRounds,
+          dryRun: req.dryRun,
        });
-        const resp: DaemonResponse = { ok: true };
+        const resp: DaemonIpcResponse = { ok: true };
        socket.write(`${JSON.stringify(resp)}\n`);
      } else if (req.type === "trigger-sense") {
        opts.triggerSense(req.sense);
-        const resp: DaemonResponse = { ok: true };
+        const resp: DaemonIpcResponse = { ok: true };
        socket.write(`${JSON.stringify(resp)}\n`);
      } else if (req.type === "list-senses") {
        const senses = opts.listSenses();
-        const resp: DaemonResponse = { ok: true, senses };
+        const resp: DaemonIpcResponse = { ok: true, senses };
        socket.write(`${JSON.stringify(resp)}\n`);
+      } else {
+        const _exhaustive: never = req;
+        void _exhaustive;
      }
    } catch (err) {
      const msg = err instanceof Error ? err.message : String(err);
-      const resp: DaemonResponse = { ok: false, error: msg };
+      const resp: DaemonIpcResponse = { ok: false, error: msg };
      socket.write(`${JSON.stringify(resp)}\n`);
    }
  }
@@ -30,7 +30,7 @@ export {
 export { createKernel } from "./kernel.js";
 export type { Kernel, KernelOptions, KernelHealth } from "./kernel.js";

-export type { SenseInfo } from "./daemon-ipc.js";
+export type { SenseInfo } from "@uncaged/nerve-core";

 export { createFileWatcher } from "./file-watcher.js";
 export type { FileWatcher, FileChange, FileChangeHandler } from "./file-watcher.js";
@@ -34,6 +34,8 @@ export type StartThreadMessage = {
  prompt: string;
  /** Safety-valve: max moderator rounds for this thread (engine launch parameter). */
  maxRounds: number;
+  /** When true, roles may skip side effects (thread-level hint on the start frame). */
+  dryRun: boolean;
 };

 /** Parent → Workflow Worker: resume an existing thread after crash recovery */
@@ -44,6 +46,8 @@ export type ResumeThreadMessage = {
  messages: Array<{ role: string; content: string; meta: unknown; timestamp: number }>;
  /** Safety-valve: max moderator rounds for this thread. */
  maxRounds: number;
+  /** Thread-level dry-run hint (aligns with persisted `__start__` meta when replaying). */
+  dryRun: boolean;
 };

 /** Union of all messages the parent sends to a worker */
@@ -135,6 +139,7 @@ function validateStartThreadMsg(obj: Record<string, unknown>): string | null {
  if (typeof obj.workflow !== "string") return "'start-thread' message missing string 'workflow'";
  if (typeof obj.prompt !== "string") return "'start-thread' message missing string 'prompt'";
  if (typeof obj.maxRounds !== "number") return "'start-thread' message missing number 'maxRounds'";
+  if (typeof obj.dryRun !== "boolean") return "'start-thread' message missing boolean 'dryRun'";
  return null;
 }

@@ -143,6 +148,7 @@ function validateResumeThreadMsg(obj: Record<string, unknown>): string | null {
  if (!Array.isArray(obj.messages)) return "'resume-thread' message missing 'messages' array";
  if (typeof obj.maxRounds !== "number")
    return "'resume-thread' message missing number 'maxRounds'";
+  if (typeof obj.dryRun !== "boolean") return "'resume-thread' message missing boolean 'dryRun'";
  return null;
 }

@@ -180,6 +186,7 @@ export function parseParentMessage(raw: unknown): Result<ParentToWorkerMessage>
      workflow: obj.workflow,
      prompt: obj.prompt,
      maxRounds: obj.maxRounds,
+      dryRun: obj.dryRun,
    } as StartThreadMessage);
  }
  if (obj.type === "resume-thread") {
@@ -191,6 +198,7 @@ export function parseParentMessage(raw: unknown): Result<ParentToWorkerMessage>
      runId: obj.runId,
      messages: obj.messages as ResumeThreadMessage["messages"],
      maxRounds: obj.maxRounds,
+      dryRun: obj.dryRun,
    } as ResumeThreadMessage);
  }
  return err(new Error(`Unhandled IPC message type: "${obj.type}"`));
@@ -148,7 +148,7 @@ export function createKernel(
      const route = routeSenseComputeOutput(msg.payload);
      if (route.kind === "launch") {
        const { workflowName, maxRounds, prompt } = route.launch;
-        workflowManager.startWorkflow(workflowName, { prompt, maxRounds });
+        workflowManager.startWorkflow(workflowName, { prompt, maxRounds, dryRun: false });
        logStore.append({
          source: "sense",
          type: "workflow-launch",
@@ -31,6 +31,7 @@ import {
 export type WorkflowLaunchParams = {
  prompt: string;
  maxRounds: number;
+  dryRun: boolean;
 };

 export type WorkflowManager = {
@@ -58,6 +59,7 @@ type PendingThread = {
  runId: string;
  prompt: string;
  maxRounds: number;
+  dryRun: boolean;
 };

 type WorkflowState = {
@@ -90,20 +92,22 @@ const DEFAULT_MAX_QUEUE = 100;
 function readLaunchFromTriggerPayload(
  raw: unknown,
  engineDefaultMaxRounds: number,
-): { prompt: string; maxRounds: number } {
+): { prompt: string; maxRounds: number; dryRun: boolean } {
  if (isPlainRecord(raw)) {
    const o = raw;
    if (typeof o.prompt === "string" && typeof o.maxRounds === "number") {
-      return { prompt: o.prompt, maxRounds: o.maxRounds };
+      const dryRun = typeof o.dryRun === "boolean" ? o.dryRun : false;
+      return { prompt: o.prompt, maxRounds: o.maxRounds, dryRun };
    }
  }
-  return { prompt: "", maxRounds: engineDefaultMaxRounds };
+  return { prompt: "", maxRounds: engineDefaultMaxRounds, dryRun: false };
 }

 function ensureThreadMessagesWithStart(
  messages: Array<{ role: string; content: string; meta: unknown; timestamp: number }>,
  fallbackPrompt: string,
  fallbackMaxRounds: number,
+  fallbackDryRun: boolean,
 ): WorkflowMessage[] {
  const mapped: WorkflowMessage[] = messages.map((m) => ({
    role: m.role,
@@ -117,7 +121,7 @@ function ensureThreadMessagesWithStart(
  const start: WorkflowMessage = {
    role: START,
    content: fallbackPrompt,
-    meta: { maxRounds: fallbackMaxRounds },
+    meta: { maxRounds: fallbackMaxRounds, dryRun: fallbackDryRun },
    timestamp: Date.now(),
  };
  return [start, ...mapped];
@@ -260,6 +264,7 @@ export function createWorkflowManager(
    runId: string,
    prompt: string,
    maxRounds: number,
+    dryRun: boolean,
  ): void {
    const state = getOrCreateState(workflowName);
    state.active.add(runId);
@@ -271,9 +276,10 @@ export function createWorkflowManager(
      workflow: workflowName,
      prompt,
      maxRounds,
+      dryRun,
    };
    sendStartThread(worker.process, msg);
-    logWorkflowEvent(workflowName, runId, "started", { prompt, maxRounds });
+    logWorkflowEvent(workflowName, runId, "started", { prompt, maxRounds, dryRun });
  }

  function dequeueNext(workflowName: string): void {
@@ -286,7 +292,7 @@ export function createWorkflowManager(
    if (state.active.size < concurrency) {
      const next = state.queue.shift();
      if (next !== undefined) {
-        dispatchThread(workflowName, next.runId, next.prompt, next.maxRounds);
+        dispatchThread(workflowName, next.runId, next.prompt, next.maxRounds, next.dryRun);
      }
    }
  }
@@ -311,7 +317,12 @@ export function createWorkflowManager(
      logStore.getTriggerPayload(runId),
      config.maxRounds,
    );
-    state.queue.push({ runId, prompt: launch.prompt, maxRounds: launch.maxRounds });
+    state.queue.push({
+      runId,
+      prompt: launch.prompt,
+      maxRounds: launch.maxRounds,
+      dryRun: launch.dryRun,
+    });
    process.stderr.write(
      `[workflow-manager] crash-recovery: re-queued thread "${runId}" for "${workflowName}"\n`,
    );
@@ -329,13 +340,19 @@ export function createWorkflowManager(
      logStore.getTriggerPayload(runId),
      config.maxRounds,
    );
-    const messages = ensureThreadMessagesWithStart(rawMessages, launch.prompt, launch.maxRounds);
+    const messages = ensureThreadMessagesWithStart(
+      rawMessages,
+      launch.prompt,
+      launch.maxRounds,
+      launch.dryRun,
+    );
    state.active.add(runId);
    const msg: ResumeThreadMessage = {
      type: "resume-thread",
      runId,
      messages,
      maxRounds: launch.maxRounds,
+      dryRun: launch.dryRun,
    };
    sendResumeThread(worker.process, msg);
    process.stderr.write(
@@ -531,10 +548,10 @@ export function createWorkflowManager(

    const state = getOrCreateState(workflowName);
    const runId = crypto.randomUUID();
-    const { prompt, maxRounds } = launch;
+    const { prompt, maxRounds, dryRun } = launch;

    if (state.active.size < wfConfig.concurrency) {
-      dispatchThread(workflowName, runId, prompt, maxRounds);
+      dispatchThread(workflowName, runId, prompt, maxRounds, dryRun);
      return;
    }

@@ -559,7 +576,7 @@ export function createWorkflowManager(
      }
    }

-    state.queue.push({ runId, prompt, maxRounds });
+    state.queue.push({ runId, prompt, maxRounds, dryRun });
    logWorkflowEvent(workflowName, runId, "queued");
    process.stderr.write(
      `[workflow-manager] queued thread for "${workflowName}" runId "${runId}" (queue length: ${state.queue.length})\n`,
@@ -13,7 +13,7 @@ import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";

 import type {
-  Moderator,
+  ModeratorContext,
  RoleMeta,
  StartSignal,
  WorkflowDefinition,
@@ -29,8 +29,6 @@ import type {
 import { parseParentMessage } from "./ipc.js";
 import { ignoreSessionBroadcastSignals } from "./worker-fork-support.js";

-type ModeratorInput = Parameters<Moderator<RoleMeta>>[0];
-
 // ---------------------------------------------------------------------------
 // IPC helpers
 // ---------------------------------------------------------------------------
@@ -87,42 +85,95 @@ function validateRoleResult(
  return true;
 }

-function buildInitialLastSignal(lastMsg: WorkflowMessage): ModeratorInput {
-  if (lastMsg.role === START) {
-    return {
-      role: START,
-      content: lastMsg.content,
-      meta: lastMsg.meta as StartSignal["meta"],
-      timestamp: lastMsg.timestamp,
-    };
-  }
-  return { role: lastMsg.role, meta: lastMsg.meta as Record<string, unknown> };
+function isStartMeta(meta: unknown): meta is StartSignal["meta"] {
+  return (
+    isPlainRecord(meta) && typeof meta.maxRounds === "number" && typeof meta.dryRun === "boolean"
+  );
 }

-function initChain(
+function normalizeStartMeta(meta: unknown, maxRoundsFallback: number): StartSignal["meta"] {
+  if (!isPlainRecord(meta)) {
+    return { maxRounds: maxRoundsFallback, dryRun: false };
+  }
+  const maxRounds = typeof meta.maxRounds === "number" ? meta.maxRounds : maxRoundsFallback;
+  const dryRun = typeof meta.dryRun === "boolean" ? meta.dryRun : false;
+  return { maxRounds, dryRun };
+}
+
+function startSignalFromWorkflowMessage(
+  msg: WorkflowMessage,
+  maxRoundsFallback: number,
+): StartSignal {
+  if (msg.role !== START) {
+    return {
+      role: START,
+      content: "",
+      meta: { maxRounds: maxRoundsFallback, dryRun: false },
+      timestamp: Date.now(),
+    };
+  }
+  const meta = isStartMeta(msg.meta) ? msg.meta : normalizeStartMeta(msg.meta, maxRoundsFallback);
+  return {
+    role: START,
+    content: msg.content,
+    meta,
+    timestamp: msg.timestamp,
+  };
+}
+
+type ThreadMessagesState = {
+  start: StartSignal;
+  /** Role outputs only; never includes the `__start__` frame. */
+  messages: WorkflowMessage[];
+};
+
+function initThreadMessages(
  runId: string,
  resumeMessages: WorkflowMessage[],
  freshPrompt: string | null,
  maxRounds: number,
-): WorkflowMessage[] {
+  dryRun: boolean,
+): ThreadMessagesState {
  if (resumeMessages.length > 0) {
-    return [...resumeMessages];
+    const [first, ...rest] = resumeMessages;
+    if (first.role === START) {
+      return {
+        start: startSignalFromWorkflowMessage(first, maxRounds),
+        messages: [...rest],
+      };
+    }
+    const prompt = freshPrompt ?? "";
+    return {
+      start: {
+        role: START,
+        content: prompt,
+        meta: { maxRounds, dryRun },
+        timestamp: Date.now(),
+      },
+      messages: [...resumeMessages],
+    };
  }
  const prompt = freshPrompt ?? "";
-  const startMsg: WorkflowMessage = {
+  const start: StartSignal = {
    role: START,
    content: prompt,
-    meta: { maxRounds },
+    meta: { maxRounds, dryRun },
    timestamp: Date.now(),
  };
-  sendWorkflowMessage(runId, startMsg);
-  return [startMsg];
+  sendWorkflowMessage(runId, {
+    role: start.role,
+    content: start.content,
+    meta: start.meta,
+    timestamp: start.timestamp,
+  });
+  return { start, messages: [] };
 }

 async function executeRole(
  def: WorkflowDefinition<RoleMeta>,
  nextRole: string,
-  chain: WorkflowMessage[],
+  start: StartSignal,
+  messages: WorkflowMessage[],
  runId: string,
 ): Promise<{ content: string; meta: Record<string, unknown> } | null> {
  const role = def.roles[nextRole];
@@ -133,7 +184,7 @@ async function executeRole(

  let result: { content: string; meta: Record<string, unknown> };
  try {
-    result = await role(chain);
+    result = await role(start, messages);
  } catch (e: unknown) {
    const errMsg = e instanceof Error ? e.message : String(e);
    sendThreadEvent(runId, "failed", { error: errMsg });
@@ -150,17 +201,18 @@ async function runThread(
  maxRounds: number,
  resumeMessages: WorkflowMessage[] = [],
  freshPrompt: string | null = null,
+  dryRun = false,
 ): Promise<void> {
-  const chain = initChain(runId, resumeMessages, freshPrompt, maxRounds);
+  const { start, messages: roleMessages } = initThreadMessages(
+    runId,
+    resumeMessages,
+    freshPrompt,
+    maxRounds,
+    dryRun,
+  );

-  let roleRound = chain.filter((m) => m.role !== START).length;
-  const lastMsg = chain[chain.length - 1];
-  if (lastMsg === undefined) {
-    sendWorkflowError(runId, "empty workflow message chain");
-    return;
-  }
-
-  let nextRole = def.moderator(buildInitialLastSignal(lastMsg), roleRound, maxRounds);
+  let roleRound = roleMessages.length;
+  let nextRole = def.moderator({ kind: "start", start }, roleRound, maxRounds);

  if (nextRole === END) {
    sendThreadEvent(runId, "completed", null);
@@ -168,7 +220,7 @@ async function runThread(
  }

  while (roleRound < maxRounds) {
-    const result = await executeRole(def, nextRole, chain, runId);
+    const result = await executeRole(def, nextRole, start, roleMessages, runId);
    if (result === null) return;

    const message: WorkflowMessage = {
@@ -177,13 +229,16 @@ async function runThread(
      meta: result.meta,
      timestamp: Date.now(),
    };
-    chain.push(message);
+    roleMessages.push(message);
    sendWorkflowMessage(runId, message);

    roleRound += 1;

-    const signal: ModeratorInput = { role: nextRole, meta: result.meta };
-    nextRole = def.moderator(signal, roleRound, maxRounds);
+    const stepContext: ModeratorContext<RoleMeta> = {
+      kind: "step",
+      signal: { role: nextRole, meta: result.meta },
+    };
+    nextRole = def.moderator(stepContext, roleRound, maxRounds);

    if (nextRole === END) {
      sendThreadEvent(runId, "completed", null);
@@ -267,11 +322,11 @@ function handleMessage(

  if (msg.type === "start-thread") {
    if (shuttingDown.value) return;
-    const { runId, prompt, maxRounds } = msg;
+    const { runId, prompt, maxRounds, dryRun } = msg;

    const previous = inFlight.get(runId) ?? Promise.resolve();
    const next = previous
-      .then(() => runThread(def, runId, maxRounds, [], prompt))
+      .then(() => runThread(def, runId, maxRounds, [], prompt, dryRun))
      .catch((e: unknown) => {
        const errMsg = e instanceof Error ? e.message : String(e);
        sendWorkflowError(runId, errMsg);
@@ -286,11 +341,11 @@ function handleMessage(

  if (msg.type === "resume-thread") {
    if (shuttingDown.value) return;
-    const { runId, messages, maxRounds } = msg;
+    const { runId, messages, maxRounds, dryRun } = msg;

    const previous = inFlight.get(runId) ?? Promise.resolve();
    const next = previous
-      .then(() => runThread(def, runId, maxRounds, messages, null))
+      .then(() => runThread(def, runId, maxRounds, messages, null, dryRun))
      .catch((e: unknown) => {
        const errMsg = e instanceof Error ? e.message : String(e);
        sendWorkflowError(runId, errMsg);
@@ -0,0 +1,48 @@
+# @uncaged/nerve-store
+
+Persistent storage for the [nerve](../../README.md) daemon — append-only structured logs, optional JSONL cold archive, and content-addressable blobs.
+
+## LogStore (`createLogStore`, `log-store.ts`)
+
+- **Append-only log table** — rows with `source`, `type`, `refId`, `payload`, `ts` (string payloads for ad hoc fields)
+- **SQLite WAL** — `DatabaseSync` from `node:sqlite`
+- **Workflow run tracking** — materialized `workflow_runs` table plus helpers to list active runs, upsert status transitions, and read **thread messages** / **role rounds** for CLI and crash recovery
+- **Meta key-value** — small `meta` table (e.g. archive watermarks)
+
+Public exports include `LogStore`, `LogEntry`, `LogQuery`, `WorkflowRun`, `WorkflowRunStatus`, `ThreadRoundRow`, `GetThreadRoundsParams`, and archive-related types re-exported from `log-archive`.
+
+## WorkflowRunStatus
+
+Runs progress through a small state machine. Typical paths:
+
+1. **`queued`** → **`started`** when a worker picks up the thread
+2. **`started`** → **`completed`** | **`failed`** | **`crashed`** | **`interrupted`** | **`dropped`**
+
+Semantics in the daemon/store layer:
+
+- **`completed` / `failed`** — normal terminal outcomes from the workflow worker
+- **`crashed`** — worker exited unexpectedly; manager may respawn and **`resume-thread`** eligible **`started`** runs
+- **`interrupted`** — e.g. hot-reload drain killed an in-flight thread after timeout
+- **`dropped`** — concurrency **`overflow: drop`** rejected a new run, or **`overflow: queue`** evicted an queued item when the queue was full
+
+## LogArchive (`log-archive.ts`)
+
+- **`archiveLogs`** / helpers — export eligible UTC days of old rows to **`data/archive/logs/YYYY-MM-DD.jsonl`**, delete archived rows from SQLite, optional **`VACUUM`**
+- Used by **`nerve store archive`** in `@uncaged/nerve-cli`
+
+## BlobStore (`createBlobStore`, `blob-store.ts`)
+
+- **Content-addressable storage** — `write` returns lowercase **sha256** hex; files live under **`data/blobs/<2-hex>/<62-hex>`**
+- **`read` / `exists`** — path must match digest on disk (tamper detection)
+
+## Install
+
+```bash
+pnpm add @uncaged/nerve-store
+```
+
+Requires Node.js ≥ 22.5 (same as the rest of the stack).
+
+## License
+
+MIT
@@ -1,6 +1,6 @@
 {
  "name": "@uncaged/nerve-store",
-  "version": "0.3.0",
+  "version": "0.4.0",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
@@ -242,6 +242,41 @@ function runInTransaction<T>(db: DatabaseSync, fn: () => T): T {
  }
 }

+function launchShapeFromRecord(rec: Record<string, unknown>): {
+  prompt: string;
+  maxRounds: number;
+  dryRun: boolean;
+} | null {
+  if (typeof rec.prompt !== "string" || typeof rec.maxRounds !== "number") return null;
+  return {
+    prompt: rec.prompt,
+    maxRounds: rec.maxRounds,
+    dryRun: typeof rec.dryRun === "boolean" ? rec.dryRun : false,
+  };
+}
+
+/** Parse JSON from a workflow `started` log row into a trigger / launch payload for crash recovery. */
+function triggerPayloadFromStartedLogJson(payload: string): unknown | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    return null;
+  }
+  if (!isPlainRecord(parsed)) return null;
+
+  const direct = launchShapeFromRecord(parsed);
+  if (direct !== null) return direct;
+
+  const inner = parsed.triggerPayload;
+  if (inner !== null && isPlainRecord(inner)) {
+    const fromInner = launchShapeFromRecord(inner);
+    if (fromInner !== null) return fromInner;
+    return inner;
+  }
+  return null;
+}
+
 function runOptionalVacuum(sqlite: DatabaseSync, vacuum?: boolean): boolean {
  if (vacuum !== true) return false;
  sqlite.exec("VACUUM");
@@ -513,15 +548,7 @@ export function createLogStore(dbPath: string): LogStore {
  function getTriggerPayload(runId: string): unknown {
    const row = getTriggerPayloadStmt.get(runId) as { payload: string | null } | undefined;
    if (row === undefined || row.payload === null) return null;
-    try {
-      const parsed: unknown = JSON.parse(row.payload);
-      if (isPlainRecord(parsed)) {
-        return parsed.triggerPayload ?? null;
-      }
-    } catch {
-      // malformed
-    }
-    return null;
+    return triggerPayloadFromStartedLogJson(row.payload);
  }

  function getThreadEvents(runId: string): Array<{ type: string; [key: string]: unknown }> {
@@ -0,0 +1,25 @@
+{
+  "name": "@uncaged/nerve-workflow-utils",
+  "version": "0.4.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "bash ../../scripts/prepublish-check.sh",
+    "build": "rslib build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@uncaged/nerve-core": "workspace:*",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@rslib/core": "^0.21.3",
+    "@types/node": "^22.0.0",
+    "vitest": "^4.1.5"
+  }
+}
@@ -0,0 +1,19 @@
+import { defineConfig } from "@rslib/core";
+
+export default defineConfig({
+  lib: [
+    {
+      format: "esm",
+      dts: true,
+    },
+  ],
+  source: {
+    entry: {
+      index: "src/index.ts",
+    },
+  },
+  output: {
+    target: "node",
+    cleanDistPath: true,
+  },
+});
@@ -0,0 +1,133 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+
+import { llmExtract } from "../llm-extract.js";
+
+describe("llmExtract", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("parses tool call arguments and validates with the zod schema", async () => {
+    const schema = z
+      .object({
+        name: z.string(),
+        description: z.string(),
+      })
+      .describe("Extract sense metadata from plan");
+
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: async () =>
+        JSON.stringify({
+          choices: [
+            {
+              message: {
+                tool_calls: [
+                  {
+                    function: {
+                      name: "extract",
+                      arguments: JSON.stringify({ name: "cpu-usage", description: "CPU load" }),
+                    },
+                  },
+                ],
+              },
+            },
+          ],
+        }),
+    });
+
+    vi.stubGlobal("fetch", fetchMock);
+
+    const result = await llmExtract({
+      text: "some plan",
+      schema,
+      provider: {
+        baseUrl: "https://example.com/v1",
+        apiKey: "k",
+        model: "m",
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual({ name: "cpu-usage", description: "CPU load" });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(init.method).toBe("POST");
+    expect(init.headers).toMatchObject({
+      Authorization: "Bearer k",
+      "Content-Type": "application/json",
+    });
+    const body = JSON.parse(init.body as string) as {
+      model: string;
+      tool_choice: { function: { name: string } };
+    };
+    expect(body.model).toBe("m");
+    expect(body.tool_choice.function.name).toBeDefined();
+  });
+
+  it("returns schema_validation_failed when arguments do not match the schema", async () => {
+    const schema = z.object({ n: z.number() });
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        text: async () =>
+          JSON.stringify({
+            choices: [
+              {
+                message: {
+                  tool_calls: [
+                    { function: { name: "extract", arguments: JSON.stringify({ n: "oops" }) } },
+                  ],
+                },
+              },
+            ],
+          }),
+      }),
+    );
+
+    const result = await llmExtract({
+      text: "x",
+      schema,
+      provider: { baseUrl: "https://example.com", apiKey: "k", model: "m" },
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.kind).toBe("schema_validation_failed");
+  });
+
+  it("dryRun skips fetch and returns an empty stub value", async () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+
+    const schema = z.object({ n: z.number() });
+    const result = await llmExtract({
+      text: "ignored",
+      schema,
+      provider: { baseUrl: "https://example.com", apiKey: "k", model: "m" },
+      dryRun: true,
+    });
+
+    logSpy.mockRestore();
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual({});
+  });
+});
@@ -0,0 +1,63 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { spawnSafe } from "../spawn-safe.js";
+
+describe("spawnSafe", () => {
+  it("passes argv literally without shell interpretation (injection-safe)", async () => {
+    const injection = "$(echo BAD)";
+    const result = await spawnSafe(
+      process.execPath,
+      ["-e", "process.stdout.write(process.argv[1] ?? '')", injection],
+      { cwd: null, env: null, timeoutMs: 10_000 },
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value.stdout).toBe(injection);
+    expect(result.value.exitCode).toBe(0);
+  });
+
+  it("returns err on non-zero exit", async () => {
+    const result = await spawnSafe(process.execPath, ["-e", "process.exit(7)"], {
+      cwd: null,
+      env: null,
+      timeoutMs: 10_000,
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.kind).toBe("non_zero_exit");
+    if (result.error.kind !== "non_zero_exit") {
+      return;
+    }
+    expect(result.error.exitCode).toBe(7);
+  });
+
+  it("dryRun skips spawn and returns a zero-exit stub", async () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const result = await spawnSafe(process.execPath, ["-e", "process.exit(1)"], {
+      cwd: null,
+      env: null,
+      timeoutMs: 10_000,
+      dryRun: true,
+    });
+
+    logSpy.mockRestore();
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual({
+      stdout: "[dryRun] skipped",
+      stderr: "",
+      exitCode: 0,
+      signal: null,
+    });
+  });
+});
@@ -0,0 +1,47 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { type Result, err, ok } from "@uncaged/nerve-core";
+
+export type ReadNerveYamlOptions = {
+  nerveRoot: string;
+};
+
+export type NerveYamlError = {
+  code: "PATH_TRAVERSAL" | "READ_FAILED";
+  message: string;
+};
+
+/**
+ * Reads `nerve.yaml` from a Nerve data directory (typically `~/.uncaged-nerve`).
+ * Returns Result to avoid throwing on expected failures (missing file, bad perms).
+ * Validates that the resolved path stays within nerveRoot to prevent path traversal.
+ */
+export function readNerveYaml(options: ReadNerveYamlOptions): Result<string, NerveYamlError> {
+  const root = resolve(options.nerveRoot);
+  const target = resolve(root, "nerve.yaml");
+
+  if (!target.startsWith(root)) {
+    return err({
+      code: "PATH_TRAVERSAL",
+      message: `Resolved path "${target}" escapes nerveRoot "${root}"`,
+    });
+  }
+
+  try {
+    return ok(readFileSync(target, "utf-8"));
+  } catch (e) {
+    return err({
+      code: "READ_FAILED",
+      message: e instanceof Error ? e.message : String(e),
+    });
+  }
+}
+
+/**
+ * Shared context for workflow agents: how Nerve fits together and common CLI verbs.
+ */
+export const nerveAgentContext = `
+Nerve observes the world through **Senses** (each has its own SQLite DB and a \`compute()\` function).
+**Reflexes** (YAML) schedule sense runs or start **Workflows** on intervals or signals.
+The \`nerve\` CLI manages config, triggers, and queries; keep paths and commands aligned with the host nerve.yaml and senses directory.
+`.trim();
@@ -0,0 +1,62 @@
+import { type Result, ok } from "@uncaged/nerve-core";
+
+import { type SpawnEnv, type SpawnError, spawnSafe } from "./spawn-safe.js";
+
+export type CursorAgentMode = "plan" | "ask" | "default";
+
+export type CursorAgentOptions = {
+  prompt: string;
+  mode: CursorAgentMode;
+  cwd: string;
+  env: SpawnEnv | null;
+  timeoutMs: number | null;
+  dryRun: boolean;
+};
+
+type CursorAgentOptionsInput = CursorAgentOptions | Omit<CursorAgentOptions, "dryRun">;
+
+function resolveCursorAgentDryRun(options: CursorAgentOptionsInput): boolean {
+  return "dryRun" in options ? options.dryRun : false;
+}
+
+/**
+ * Invokes `cursor-agent` with the prompt passed as a single argv slot (`shell: false`).
+ */
+export async function cursorAgent(
+  options: CursorAgentOptionsInput,
+): Promise<Result<string, SpawnError>> {
+  const dryRun = resolveCursorAgentDryRun(options);
+  if (dryRun) {
+    console.log("[dryRun] cursorAgent:", options.prompt, JSON.stringify(options));
+    return ok("[dryRun] skipped");
+  }
+
+  const args: string[] = [
+    "-p",
+    options.prompt,
+    "--model",
+    "auto",
+    "--output-format",
+    "text",
+    "--trust",
+    "--force",
+  ];
+  if (options.mode === "plan") {
+    args.push("--mode=plan");
+  } else if (options.mode === "ask") {
+    args.push("--mode=ask");
+  }
+
+  const run = await spawnSafe("cursor-agent", args, {
+    cwd: options.cwd,
+    env: options.env,
+    timeoutMs: options.timeoutMs,
+    dryRun: false,
+  });
+
+  if (!run.ok) {
+    return run;
+  }
+
+  return ok(run.value.stdout);
+}
@@ -0,0 +1,22 @@
+export { cursorAgent, type CursorAgentMode, type CursorAgentOptions } from "./cursor-agent.js";
+export {
+  nerveAgentContext,
+  readNerveYaml,
+  type NerveYamlError,
+  type ReadNerveYamlOptions,
+} from "./context.js";
+export {
+  llmExtract,
+  type LlmError,
+  type LlmExtractOptions,
+  type LlmProvider,
+} from "./llm-extract.js";
+export {
+  nerveCommandEnv,
+  spawnSafe,
+  type SpawnEnv,
+  type SpawnError,
+  type SpawnResult,
+  type SpawnSafeOptions,
+} from "./spawn-safe.js";
+export { isDryRun } from "./start-signal.js";
@@ -0,0 +1,189 @@
+import { type Result, err, ok } from "@uncaged/nerve-core";
+import { toJSONSchema, type z } from "zod";
+
+export type LlmProvider = {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+};
+
+export type LlmExtractOptions<T> = {
+  text: string;
+  schema: z.ZodType<T>;
+  provider: LlmProvider;
+  dryRun: boolean;
+};
+
+type LlmExtractOptionsInput<T> = LlmExtractOptions<T> | Omit<LlmExtractOptions<T>, "dryRun">;
+
+function resolveLlmExtractDryRun<T>(options: LlmExtractOptionsInput<T>): boolean {
+  return "dryRun" in options ? options.dryRun : false;
+}
+
+export type LlmError =
+  | { kind: "http_error"; status: number; body: string }
+  | { kind: "invalid_response_json"; message: string }
+  | { kind: "no_tool_call"; preview: string }
+  | { kind: "tool_arguments_invalid_json"; message: string }
+  | { kind: "schema_validation_failed"; message: string }
+  | { kind: "network_error"; message: string };
+
+function chatCompletionsUrl(baseUrl: string): string {
+  const trimmed = baseUrl.replace(/\/+$/, "");
+  return `${trimmed}/chat/completions`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stripJsonSchemaMeta(json: Record<string, unknown>): Record<string, unknown> {
+  const { $schema: _drop, ...rest } = json;
+  return rest;
+}
+
+function readToolName(parametersSchema: Record<string, unknown>): string {
+  const title = parametersSchema.title;
+  if (typeof title === "string" && title.trim().length > 0) {
+    return title.trim();
+  }
+  return "extract";
+}
+
+function readToolArgumentsJson(parsed: unknown, previewSource: string): Result<string, LlmError> {
+  if (!isRecord(parsed)) {
+    return err({ kind: "invalid_response_json", message: "Top-level JSON is not an object" });
+  }
+
+  const choices = parsed.choices;
+  if (!Array.isArray(choices) || choices.length === 0) {
+    return err({ kind: "no_tool_call", preview: previewSource.slice(0, 500) });
+  }
+
+  const first = choices[0];
+  if (!isRecord(first)) {
+    return err({ kind: "no_tool_call", preview: previewSource.slice(0, 500) });
+  }
+
+  const messageObj = first.message;
+  if (!isRecord(messageObj)) {
+    return err({ kind: "no_tool_call", preview: previewSource.slice(0, 500) });
+  }
+
+  const toolCalls = messageObj.tool_calls;
+  if (!Array.isArray(toolCalls) || toolCalls.length === 0) {
+    return err({ kind: "no_tool_call", preview: previewSource.slice(0, 500) });
+  }
+
+  const call0 = toolCalls[0];
+  if (!isRecord(call0)) {
+    return err({ kind: "no_tool_call", preview: previewSource.slice(0, 500) });
+  }
+
+  const fn = call0.function;
+  if (!isRecord(fn)) {
+    return err({ kind: "no_tool_call", preview: previewSource.slice(0, 500) });
+  }
+
+  const argsRaw = fn.arguments;
+  if (typeof argsRaw !== "string") {
+    return err({ kind: "no_tool_call", preview: previewSource.slice(0, 500) });
+  }
+
+  return ok(argsRaw);
+}
+
+/**
+ * Calls an OpenAI-compatible chat completions API with `tool_choice` forced to a single function
+ * derived from a Zod v4 schema (`toJSONSchema`). Uses `fetch()` only (no shell).
+ */
+export async function llmExtract<T>(
+  options: LlmExtractOptionsInput<T>,
+): Promise<Result<T, LlmError>> {
+  const dryRun = resolveLlmExtractDryRun(options);
+  if (dryRun) {
+    console.log("[dryRun] llmExtract:", options.text, JSON.stringify(options.schema));
+    return ok({} as T);
+  }
+
+  const rawJsonSchema = toJSONSchema(options.schema) as Record<string, unknown>;
+  const parameters = stripJsonSchemaMeta(rawJsonSchema);
+  const toolName = readToolName(parameters);
+  const toolDescription =
+    typeof options.schema.description === "string" && options.schema.description.trim().length > 0
+      ? options.schema.description.trim()
+      : "Extract structured data from the input text.";
+
+  const body = {
+    model: options.provider.model,
+    messages: [
+      {
+        role: "system" as const,
+        content: "Extract the requested information from the provided text. Be precise.",
+      },
+      { role: "user" as const, content: options.text },
+    ],
+    tools: [
+      {
+        type: "function" as const,
+        function: {
+          name: toolName,
+          description: toolDescription,
+          parameters,
+        },
+      },
+    ],
+    tool_choice: { type: "function" as const, function: { name: toolName } },
+  };
+
+  let response: Response;
+  try {
+    response = await fetch(chatCompletionsUrl(options.provider.baseUrl), {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${options.provider.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return err({ kind: "network_error", message });
+  }
+
+  const responseText = await response.text();
+  if (!response.ok) {
+    return err({ kind: "http_error", status: response.status, body: responseText.slice(0, 4000) });
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(responseText) as unknown;
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return err({ kind: "invalid_response_json", message });
+  }
+
+  const argsJson = readToolArgumentsJson(parsed, responseText);
+  if (!argsJson.ok) {
+    return argsJson;
+  }
+
+  let argsParsed: unknown;
+  try {
+    argsParsed = JSON.parse(argsJson.value) as unknown;
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return err({ kind: "tool_arguments_invalid_json", message });
+  }
+
+  const validated = options.schema.safeParse(argsParsed);
+  if (!validated.success) {
+    return err({
+      kind: "schema_validation_failed",
+      message: validated.error.message,
+    });
+  }
+
+  return ok(validated.data);
+}
@@ -0,0 +1,160 @@
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { type Result, err, ok } from "@uncaged/nerve-core";
+
+/** Compatible with `process.env` for `child_process.spawn`. */
+export type SpawnEnv = Record<string, string | undefined>;
+
+export type SpawnResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  /** OS signal name (e.g. `"SIGTERM"`) when terminated by signal; otherwise `null`. */
+  signal: string | null;
+};
+
+export type SpawnError =
+  | {
+      kind: "non_zero_exit";
+      stdout: string;
+      stderr: string;
+      exitCode: number;
+      signal: string | null;
+    }
+  | { kind: "timeout"; stdout: string; stderr: string }
+  | { kind: "spawn_failed"; message: string };
+
+export type SpawnSafeOptions = {
+  cwd: string | null;
+  /** When null, merges {@link nerveCommandEnv} over `process.env`. When set, merges over that default. */
+  env: SpawnEnv | null;
+  timeoutMs: number | null;
+  dryRun: boolean;
+};
+
+type SpawnSafeOptionsInput = SpawnSafeOptions | Omit<SpawnSafeOptions, "dryRun">;
+
+const DEFAULT_TIMEOUT_MS = 300_000;
+
+/**
+ * PATH and PNPM_HOME for running `pnpm` and `nerve` from workflow roles.
+ * Uses the pnpm store home only (no npm user bin); binaries must resolve via PATH.
+ */
+export function nerveCommandEnv(): SpawnEnv {
+  const home = homedir();
+  const pnpmHome = join(home, ".local/share/pnpm");
+  return {
+    ...process.env,
+    PNPM_HOME: pnpmHome,
+    PATH: `${pnpmHome}:${process.env.PATH ?? ""}`,
+  };
+}
+
+function mergeEnv(user: SpawnEnv | null): SpawnEnv {
+  const base = nerveCommandEnv();
+  if (user === null) {
+    return base;
+  }
+  return { ...base, ...user };
+}
+
+function resolveTimeout(timeoutMs: number | null): number {
+  if (timeoutMs === null) {
+    return DEFAULT_TIMEOUT_MS;
+  }
+  return timeoutMs;
+}
+
+function resolveDryRun(options: SpawnSafeOptionsInput): boolean {
+  return "dryRun" in options ? options.dryRun : false;
+}
+
+/**
+ * Spawn a process with `shell: false` (argv only), default {@link nerveCommandEnv}, and optional timeout.
+ * Returns `ok` only when the process exits with code 0.
+ */
+export function spawnSafe(
+  command: string,
+  args: ReadonlyArray<string>,
+  options: SpawnSafeOptionsInput,
+): Promise<Result<SpawnResult, SpawnError>> {
+  const dryRun = resolveDryRun(options);
+  if (dryRun) {
+    console.log("[dryRun] spawnSafe:", command, args, JSON.stringify(options));
+    return Promise.resolve(
+      ok({
+        stdout: "[dryRun] skipped",
+        stderr: "",
+        exitCode: 0,
+        signal: null,
+      }),
+    );
+  }
+
+  return new Promise((resolve) => {
+    const cwd = options.cwd === null ? process.cwd() : options.cwd;
+    const env = mergeEnv(options.env);
+    const timeoutMs = resolveTimeout(options.timeoutMs);
+
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const finish = (outcome: Result<SpawnResult, SpawnError>) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      resolve(outcome);
+    };
+
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish(err({ kind: "timeout", stdout, stderr }));
+    }, timeoutMs);
+
+    child.stdout?.on("data", (chunk: Buffer | string) => {
+      stdout += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+    });
+    child.stderr?.on("data", (chunk: Buffer | string) => {
+      stderr += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+    });
+
+    child.on("error", (cause: Error) => {
+      finish(err({ kind: "spawn_failed", message: cause.message }));
+    });
+
+    child.on("close", (code, signal) => {
+      const exitCode = code ?? 1;
+      const sig = signal === undefined || signal === null ? null : String(signal);
+      const result: SpawnResult = {
+        stdout: stdout.trimEnd(),
+        stderr: stderr.trimEnd(),
+        exitCode,
+        signal: sig,
+      };
+      if (exitCode !== 0) {
+        finish(
+          err({
+            kind: "non_zero_exit",
+            stdout: result.stdout,
+            stderr: result.stderr,
+            exitCode,
+            signal: sig,
+          }),
+        );
+        return;
+      }
+      finish(ok(result));
+    });
+  });
+}
@@ -0,0 +1,6 @@
+import type { StartSignal } from "@uncaged/nerve-core";
+
+/** Returns the thread-level dry-run flag from the workflow start frame. */
+export function isDryRun(start: StartSignal): boolean {
+  return start.meta.dryRun;
+}
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "composite": false
+  },
+  "include": ["src"]
+}
@@ -69,7 +69,7 @@ importers:
        version: link:../store
      drizzle-orm:
        specifier: 1.0.0-beta.23-c10d10c
-        version: 1.0.0-beta.23-c10d10c(@types/better-sqlite3@7.6.13)(@types/mssql@9.1.11(@azure/core-client@1.10.1))(better-sqlite3@11.10.0)(mssql@11.0.1(@azure/core-client@1.10.1))(sql.js@1.14.1)
+        version: 1.0.0-beta.23-c10d10c(@types/better-sqlite3@7.6.13)(@types/mssql@9.1.11(@azure/core-client@1.10.1))(better-sqlite3@11.10.0)(mssql@11.0.1(@azure/core-client@1.10.1))(sql.js@1.14.1)(zod@4.3.6)
      yaml:
        specifier: ^2.8.3
        version: 2.8.3
@@ -100,6 +100,25 @@ importers:
        specifier: ^4.1.5
        version: 4.1.5(@types/node@22.19.17)(vite@8.0.9(@types/node@22.19.17)(esbuild@0.27.7)(yaml@2.8.3))

+  packages/workflow-utils:
+    dependencies:
+      '@uncaged/nerve-core':
+        specifier: workspace:*
+        version: link:../core
+      zod:
+        specifier: ^4.3.6
+        version: 4.3.6
+    devDependencies:
+      '@rslib/core':
+        specifier: ^0.21.3
+        version: 0.21.3(typescript@5.9.3)
+      '@types/node':
+        specifier: ^22.0.0
+        version: 22.19.17
+      vitest:
+        specifier: ^4.1.5
+        version: 4.1.5(@types/node@22.19.17)(vite@8.0.9(@types/node@22.19.17)(esbuild@0.27.7)(yaml@2.8.3))
+
 packages:

  '@ast-grep/napi-darwin-arm64@0.37.0':
@@ -1472,6 +1491,9 @@ packages:
    engines: {node: '>= 14.6'}
    hasBin: true

+  zod@4.3.6:
+    resolution: {integrity: sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==}
+
 snapshots:

  '@ast-grep/napi-darwin-arm64@0.37.0':
@@ -2169,13 +2191,14 @@ snapshots:

  detect-libc@2.1.2: {}

-  drizzle-orm@1.0.0-beta.23-c10d10c(@types/better-sqlite3@7.6.13)(@types/mssql@9.1.11(@azure/core-client@1.10.1))(better-sqlite3@11.10.0)(mssql@11.0.1(@azure/core-client@1.10.1))(sql.js@1.14.1):
+  drizzle-orm@1.0.0-beta.23-c10d10c(@types/better-sqlite3@7.6.13)(@types/mssql@9.1.11(@azure/core-client@1.10.1))(better-sqlite3@11.10.0)(mssql@11.0.1(@azure/core-client@1.10.1))(sql.js@1.14.1)(zod@4.3.6):
    optionalDependencies:
      '@types/better-sqlite3': 7.6.13
      '@types/mssql': 9.1.11(@azure/core-client@1.10.1)
      better-sqlite3: 11.10.0
      mssql: 11.0.1(@azure/core-client@1.10.1)
      sql.js: 1.14.1
+      zod: 4.3.6

  ecdsa-sig-formatter@1.0.11:
    dependencies:
@@ -2772,3 +2795,5 @@ snapshots:
    optional: true

  yaml@2.8.3: {}
+
+  zod@4.3.6: {}
Author	SHA1	Message	Date
xiaoju	70bea92133	feat(workflow-utils): dryRun support for spawnSafe, cursorAgent, llmExtract When dryRun=true, each function logs its parameters and returns a stub result without executing any subprocess or network call. Log output is captured by log-store for analysis. - spawnSafe: returns { exitCode: 0, stdout: '[dryRun] skipped' } - cursorAgent: short-circuits before spawnSafe, returns ok('[dryRun] skipped') - llmExtract: skips fetch, returns ok({} as T) - Tests added for spawnSafe and llmExtract dryRun paths Fixes #104	2026-04-25 00:23:43 +00:00
xiaomo	6f2cddd695	Merge pull request 'feat(core,daemon,cli): add dryRun thread-level parameter to StartSignal' (#103 ) from feat/101-dry-run into main	2026-04-24 23:50:55 +00:00
xiaoju	c4dc707eb0	feat(core,daemon,cli): add dryRun thread-level parameter to StartSignal - StartSignal.meta gains dryRun: boolean (alongside maxRounds) - DaemonIpcTriggerWorkflowRequest includes dryRun, parsed with default false - CLI parses dryRun from --payload JSON, passes through daemon client - workflow-worker/workflow-manager propagate dryRun through full IPC chain - Sense-triggered workflows default to dryRun: false - workflow-utils exports isDryRun(start) helper - All tests updated, 376 pass Fixes #101	2026-04-24 23:45:29 +00:00
xiaomo	a7ce8401ce	Merge pull request 'refactor(core,daemon): extract StartSignal as independent Role parameter' (#102 ) from refactor/100-extract-start-signal into main	2026-04-24 23:35:09 +00:00
xiaoju	e9e6df2f5a	refactor(core,daemon): extract StartSignal as independent Role parameter - Role<Meta> now takes (start: StartSignal, messages: WorkflowMessage[]) - messages no longer contains the __start__ frame - Add ModeratorContext<M> discriminated union (kind: start \| step) - Moderator receives typed context instead of raw StartSignal \| RoleSignal union - workflow-worker separates start from role messages throughout Refs #100	2026-04-24 23:14:45 +00:00
xingyue	b3b0dad2bb	Merge pull request 'feat: add workflow-utils package' (#98 ) from feat/97-workflow-utils into main	2026-04-24 22:43:07 +00:00
xiaoju	e0ce1d995c	fix: readNerveYaml returns Result + path traversal guard Address review feedback: - Return Result<string, NerveYamlError> instead of throwing - Add path traversal protection via resolve + startsWith check - Export NerveYamlError type - Update sense-generator to handle Result	2026-04-24 22:41:27 +00:00
xiaoju	0a4a2330dc	feat: add workflow-utils package Closes #97	2026-04-24 22:32:29 +00:00
xiaomo	d3088c623b	Merge pull request 'docs: update all README files to match actual code' (#96 ) from docs/95-update-readme-to-match-code into main	2026-04-24 21:49:33 +00:00
xiaoju	a7e6caf6e7	docs: update all README files to match actual code Rewrite documentation across all packages to reflect current architecture, APIs, and CLI commands. - README.md: fix reflex examples, add store package, update config - core/README.md: add Sense→workflow routing, IPC types - daemon/README.md: complete module table, crash recovery, createKernel - cli/README.md: add workflow/sense/store subcommands - store/README.md: new file documenting LogStore/BlobStore Fixes #95	2026-04-24 21:47:37 +00:00
xiaomo	d4dcd9722f	Merge pull request 'refactor: share IPC message types between CLI and daemon' (#94 ) from refactor/93-shared-ipc-types into main	2026-04-24 15:14:50 +00:00
xiaoju	3082568b85	refactor(daemon): exhaustive IPC request dispatch Ensure new DaemonIpcRequest variants require an explicit handler branch. Made-with: Cursor	2026-04-24 15:11:58 +00:00
xiaoju	830b0aa762	refactor(core): shared daemon IPC request/response types Move wire protocol types and parseDaemonIpcRequest into @uncaged/nerve-core so CLI and daemon share one definition. Type sendAndReceive message as DaemonIpcRequest. Align workflow trigger CLI with daemon (prompt, maxRounds from --payload JSON). Made-with: Cursor	2026-04-24 15:10:00 +00:00
xiaoju	777d51cc73	chore: bump version to 0.4.0 小橘 🍊（NEKO Team）	2026-04-24 13:22:30 +00:00