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

README.md

@@ -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
 

packages/cli/README.md

@@ -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

packages/cli/package.json

@@ -10,9 +10,7 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "publishConfig": {
     "access": "public"
   },

packages/cli/src/__tests__/workflow.test.ts

@@ -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/,
     );
   });

packages/cli/src/commands/workflow.ts

@@ -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) and "maxRounds" (number) for the workflow run (default: {})',
       default: "{}",
     },
   },
@@ -526,15 +528,23 @@ const workflowTriggerCommand = defineCommand({
       process.exit(1);
     }
 
+    let prompt = "";
+    let maxRounds = DEFAULT_ENGINE_MAX_ROUNDS;
+    if (isPlainRecord(triggerPayload)) {
+      const p = triggerPayload;
+      if (typeof p.prompt === "string") prompt = p.prompt;
+      if (typeof p.maxRounds === "number") maxRounds = p.maxRounds;
+    }
+
     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);
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
       process.stderr.write(`❌ Failed to contact daemon: ${msg}\n`);

packages/cli/src/daemon-client.ts

@@ -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,35 @@ 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,
+): Promise<DaemonIpcTriggerResponse> {
+  const message: DaemonIpcRequest = {
+    type: "trigger-workflow",
+    workflow,
+    prompt,
+    maxRounds,
+  };
+  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);
 }

packages/core/README.md

@@ -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:

packages/core/package.json

@@ -3,9 +3,7 @@
   "version": "0.4.0",
   "type": "module",
   "main": "dist/index.js",
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "publishConfig": {
     "access": "public"
   },

packages/core/src/__tests__/daemon-ipc-protocol.test.ts

@@ -0,0 +1,51 @@
+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,
+    });
+  });
+
+  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();
+  });
+});

packages/core/src/daemon-ipc-protocol.ts

@@ -0,0 +1,85 @@
+/**
+ * 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;
+};
+
+/** 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[] };
+
+/**
+ * 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") {
+      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;
+  }
+}

packages/core/src/index.ts

@@ -32,3 +32,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";

packages/daemon/README.md

@@ -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

packages/daemon/package.json

@@ -4,9 +4,7 @@
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "publishConfig": {
     "access": "public"
   },

packages/daemon/src/__tests__/daemon-ipc.test.ts

@@ -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

packages/daemon/src/daemon-ipc.ts

@@ -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;
     }
@@ -115,20 +56,23 @@ export function createDaemonIpcServer(
           prompt: req.prompt,
           maxRounds: req.maxRounds,
         });
-        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`);
     }
   }

packages/daemon/src/index.ts

@@ -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";

packages/store/README.md

@@ -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

packages/store/package.json

@@ -4,9 +4,7 @@
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "publishConfig": {
     "access": "public"
   },