docs: add core concepts (sense, signal, reflex, workflow) to agent rules

- .cursor/rules/global.mdc: coding conventions as Cursor agent rules
- CLAUDE.md: same conventions for Claude Code / Hermes agents
- Content derived from docs/coding-conventions.md
- Includes no-dynamic-import rule in CLAUDE.md for completeness

.cursor/rules/global.mdc

@@ -0,0 +1,189 @@
+---
+description: Nerve project coding conventions — style, patterns, and toolchain
+globs: packages/*/src/**/*.ts
+alwaysApply: true
+---
+
+# Nerve Coding Conventions
+
+## Core Concepts
+
+```
+External World → Sense → Signal → Reflex → Workflow → Log
+                  ↑                                     ↑
+              "what to observe"                  "what to do"
+```
+
+**Nerve** is a lightweight observation engine daemon for autonomous agents. It continuously observes external state, reacts to changes via declarative rules, and orchestrates multi-step workflows.
+
+### Key Terms
+
+| Concept | What it is |
+|---------|-----------|
+| **Sense** | A `compute()` function that samples or derives data. Returns `T \| null` — non-null emits a Signal, null is silent. Each Sense has its own SQLite database. |
+| **Signal** | A notification emitted when a Sense returns non-null. Pure fact, no intent. Distributed via an in-memory Signal Bus. Not persisted. |
+| **Reflex** | A declarative trigger (YAML) connecting Senses to actions. Trigger types: `interval` (periodic), `on` (react to Signals). Action types: trigger a Sense, or start a Workflow. |
+| **Workflow** | A stateful multi-step execution. Contains **Roles** (actors with side effects) and a **Moderator** (pure router). Each instance is a **Thread** with a unique `runId`. |
+| **Log** | Immutable audit trail. Records executions, state transitions, errors. **Cannot trigger Reflexes** — prevents feedback loops. |
+| **Engine** | The kernel orchestrating everything. Holds Signal Bus, Reflex Scheduler, Process Manager, Workflow Manager. Never loads user code directly — all user code runs in isolated Workers. |
+| **Daemon** | The `nerve-daemon` package — engine runtime. Runs as a background process. |
+
+### Architecture Rules
+
+- **Three orthogonal extension points**: Sense (what to compute), Reflex (when to compute), Workflow (what to do)
+- **Process isolation**: One worker per Sense group (long-lived), one per Workflow type (on-demand). Workers never talk to each other.
+- **Causality is one-directional**: External world → Sense → Signal → Reflex → Action + Log. Logs are the end of the chain.
+
+
+
+## Language & Paradigm
+
+### Functional-first
+
+Use `function` + `type`, not `class` + `interface`.
+
+```typescript
+// ✅ Good
+type Signal = {
+  senseId: string;
+  value: unknown;
+  ts: number;
+};
+
+function createSignal(senseId: string, value: unknown): Signal {
+  return { senseId, value, ts: Date.now() };
+}
+
+// ❌ Bad — no class, no interface
+class Signal implements ISignal { ... }
+```
+
+### Rules
+
+| Rule | Description |
+|------|-------------|
+| `type` over `interface` | All type definitions use `type` |
+| `function` over `class` | Pure functions + closures, no class |
+| No `this` | Functions must not depend on `this` context |
+| No inheritance | No `extends`, `implements`, `abstract` |
+| Composition over inheritance | Use function composition |
+| Immutability first | Use `Readonly<T>`, `as const`, avoid mutation |
+| No optional properties | Use `T \| null` instead of `?:` — see below |
+
+### Exceptions
+
+Classes are allowed when:
+- Required by a third-party library (e.g. Drizzle's `sqliteTable`)
+- Error subclasses (`class NerveError extends Error`)
+
+### No Optional Properties
+
+Never use `?:`. All nullable fields must be explicit `T | null`.
+
+```typescript
+// ✅ Good
+type SenseConfig = {
+  group: string;
+  throttle: string | null;
+  timeout: string | null;
+};
+
+// ❌ Bad
+type SenseConfig = {
+  group: string;
+  throttle?: string;
+  timeout?: string;
+};
+```
+
+For mutually exclusive fields, use discriminated unions:
+
+```typescript
+// ✅ Good
+type ReflexConfig =
+  | { kind: "sense"; sense: string; interval: string | null; on: string[] | null }
+  | { kind: "workflow"; workflow: string; on: string[] | null };
+```
+
+## Modules & Exports
+
+- Always named exports, never default exports
+- One module = one responsibility, filename = purpose
+
+```typescript
+// ✅ Named exports only
+export function startEngine(config: EngineConfig): Engine { ... }
+export type EngineConfig = { ... };
+
+// ❌ No default exports
+export default function startEngine() { ... }
+```
+
+## Naming
+
+| Type | Style | Example |
+|------|-------|---------|
+| Files | kebab-case | `signal-bus.ts` |
+| Types | PascalCase | `SignalBus` |
+| Functions/variables | camelCase | `createSignalBus` |
+| Constants | UPPER_SNAKE | `MAX_RETRY_COUNT` |
+| Generics | Single letter or descriptive | `T`, `TValue` |
+
+## Error Handling
+
+- Use `Result` type for expected failures
+- `throw` only for unrecoverable bugs (programmer errors)
+- No try-catch for flow control
+
+```typescript
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+function parseSenseConfig(raw: unknown): Result<SenseConfig> { ... }
+```
+
+## Async
+
+- Always `async/await`, never `.then()` chains
+
+## Toolchain
+
+| Tool | Purpose |
+|------|---------|
+| **pnpm** | Package manager |
+| **TypeScript** | Type checking (strict mode) |
+| **Biome** | Lint + format (replaces ESLint + Prettier) |
+| **tsup** | Bundling |
+
+### Commands
+
+```bash
+pnpm run check      # biome check (lint + format)
+pnpm run format     # biome format --write
+pnpm run build      # full build
+pnpm test           # run tests
+```
+
+## Monorepo Structure
+
+```
+nerve/
+  packages/
+    core/           # @nerve/core — shared types and utils
+    cli/            # @nerve/cli — CLI entry point
+    daemon/         # @nerve/daemon — engine runtime
+  docs/             # RFCs, conventions
+  biome.json        # root Biome config
+  tsconfig.json     # root TypeScript config (composite project references)
+```
+
+- `core` is the shared layer; `cli` and `daemon` both depend on it
+- `cli` and `daemon` must NOT depend on each other
+
+## Commit Convention
+
+```
+<type>(<scope>): <description>
+
+type: feat | fix | refactor | docs | chore | test
+scope: core | cli | daemon | rfc-001 | ...
+```

.github/copilot-instructions.md

@@ -0,0 +1,180 @@
+# Nerve Coding Conventions
+
+## Core Concepts
+
+```
+External World → Sense → Signal → Reflex → Workflow → Log
+                  ↑                                     ↑
+              "what to observe"                  "what to do"
+```
+
+**Nerve** is a lightweight observation engine daemon for autonomous agents. It continuously observes external state, reacts to changes via declarative rules, and orchestrates multi-step workflows.
+
+### Key Terms
+
+| Concept | What it is |
+|---------|-----------|
+| **Sense** | A `compute()` function that samples or derives data. Returns `T \| null` — non-null emits a Signal, null is silent. Each Sense has its own SQLite database. |
+| **Signal** | A notification emitted when a Sense returns non-null. Pure fact, no intent. Distributed via an in-memory Signal Bus. Not persisted. |
+| **Reflex** | A declarative trigger (YAML) connecting Senses to actions. Trigger types: `interval` (periodic), `on` (react to Signals). Action types: trigger a Sense, or start a Workflow. |
+| **Workflow** | A stateful multi-step execution. Contains **Roles** (actors with side effects) and a **Moderator** (pure router). Each instance is a **Thread** with a unique `runId`. |
+| **Log** | Immutable audit trail. Records executions, state transitions, errors. **Cannot trigger Reflexes** — prevents feedback loops. |
+| **Engine** | The kernel orchestrating everything. Holds Signal Bus, Reflex Scheduler, Process Manager, Workflow Manager. Never loads user code directly — all user code runs in isolated Workers. |
+| **Daemon** | The `nerve-daemon` package — engine runtime. Runs as a background process. |
+
+### Architecture Rules
+
+- **Three orthogonal extension points**: Sense (what to compute), Reflex (when to compute), Workflow (what to do)
+- **Process isolation**: One worker per Sense group (long-lived), one per Workflow type (on-demand). Workers never talk to each other.
+- **Causality is one-directional**: External world → Sense → Signal → Reflex → Action + Log. Logs are the end of the chain.
+
+
+
+## Language & Paradigm
+
+### Functional-first
+
+Use `function` + `type`, not `class` + `interface`.
+
+```typescript
+// ✅ Good
+type Signal = {
+  senseId: string;
+  value: unknown;
+  ts: number;
+};
+
+function createSignal(senseId: string, value: unknown): Signal {
+  return { senseId, value, ts: Date.now() };
+}
+
+// ❌ Bad — no class, no interface
+class Signal implements ISignal { ... }
+```
+
+### Rules
+
+| Rule | Description |
+|------|-------------|
+| `type` over `interface` | All type definitions use `type` |
+| `function` over `class` | Pure functions + closures, no class |
+| No `this` | Functions must not depend on `this` context |
+| No inheritance | No `extends`, `implements`, `abstract` |
+| Composition over inheritance | Use function composition |
+| Immutability first | Use `Readonly<T>`, `as const`, avoid mutation |
+| No optional properties | Use `T \| null` instead of `?:` — see below |
+
+### Exceptions
+
+Classes are allowed when:
+- Required by a third-party library (e.g. Drizzle's `sqliteTable`)
+- Error subclasses (`class NerveError extends Error`)
+
+### No Optional Properties
+
+Never use `?:`. All nullable fields must be explicit `T | null`.
+
+```typescript
+// ✅ Good
+type SenseConfig = {
+  group: string;
+  throttle: string | null;
+  timeout: string | null;
+};
+
+// ❌ Bad
+type SenseConfig = {
+  group: string;
+  throttle?: string;
+  timeout?: string;
+};
+```
+
+For mutually exclusive fields, use discriminated unions:
+
+```typescript
+// ✅ Good
+type ReflexConfig =
+  | { kind: "sense"; sense: string; interval: string | null; on: string[] | null }
+  | { kind: "workflow"; workflow: string; on: string[] | null };
+```
+
+## Modules & Exports
+
+- Always named exports, never default exports
+- One module = one responsibility, filename = purpose
+
+## Naming
+
+| Type | Style | Example |
+|------|-------|---------|
+| Files | kebab-case | `signal-bus.ts` |
+| Types | PascalCase | `SignalBus` |
+| Functions/variables | camelCase | `createSignalBus` |
+| Constants | UPPER_SNAKE | `MAX_RETRY_COUNT` |
+| Generics | Single letter or descriptive | `T`, `TValue` |
+
+## Error Handling
+
+- Use `Result` type for expected failures
+- `throw` only for unrecoverable bugs (programmer errors)
+- No try-catch for flow control
+
+```typescript
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+```
+
+## Async
+
+- Always `async/await`, never `.then()` chains
+
+## No Dynamic Import
+
+Do NOT use `await import()` in production code. Always use static top-level `import`.
+
+Exceptions (must include a comment):
+1. `sense-runtime.ts` — user module paths known only at runtime
+2. `workflow-worker.ts` — user module paths known only at runtime
+
+Test files (`__tests__/**`) are exempt.
+
+## Toolchain
+
+| Tool | Purpose |
+|------|---------|
+| **pnpm** | Package manager |
+| **TypeScript** | Type checking (strict mode) |
+| **Biome** | Lint + format (replaces ESLint + Prettier) |
+| **tsup** | Bundling |
+
+### Commands
+
+```bash
+pnpm run check      # biome check (lint + format)
+pnpm run format     # biome format --write
+pnpm run build      # full build
+pnpm test           # run tests
+```
+
+## Monorepo Structure
+
+```
+nerve/
+  packages/
+    core/           # @nerve/core — shared types and utils
+    cli/            # @nerve/cli — CLI entry point
+    daemon/         # @nerve/daemon — engine runtime
+  docs/             # RFCs, conventions
+```
+
+- `core` is the shared layer; `cli` and `daemon` both depend on it
+- `cli` and `daemon` must NOT depend on each other
+
+## Commit Convention
+
+```
+<type>(<scope>): <description>
+
+type: feat | fix | refactor | docs | chore | test
+scope: core | cli | daemon | rfc-001 | ...
+```

CLAUDE.md

@@ -0,0 +1,180 @@
+# Nerve Coding Conventions
+
+## Core Concepts
+
+```
+External World → Sense → Signal → Reflex → Workflow → Log
+                  ↑                                     ↑
+              "what to observe"                  "what to do"
+```
+
+**Nerve** is a lightweight observation engine daemon for autonomous agents. It continuously observes external state, reacts to changes via declarative rules, and orchestrates multi-step workflows.
+
+### Key Terms
+
+| Concept | What it is |
+|---------|-----------|
+| **Sense** | A `compute()` function that samples or derives data. Returns `T \| null` — non-null emits a Signal, null is silent. Each Sense has its own SQLite database. |
+| **Signal** | A notification emitted when a Sense returns non-null. Pure fact, no intent. Distributed via an in-memory Signal Bus. Not persisted. |
+| **Reflex** | A declarative trigger (YAML) connecting Senses to actions. Trigger types: `interval` (periodic), `on` (react to Signals). Action types: trigger a Sense, or start a Workflow. |
+| **Workflow** | A stateful multi-step execution. Contains **Roles** (actors with side effects) and a **Moderator** (pure router). Each instance is a **Thread** with a unique `runId`. |
+| **Log** | Immutable audit trail. Records executions, state transitions, errors. **Cannot trigger Reflexes** — prevents feedback loops. |
+| **Engine** | The kernel orchestrating everything. Holds Signal Bus, Reflex Scheduler, Process Manager, Workflow Manager. Never loads user code directly — all user code runs in isolated Workers. |
+| **Daemon** | The `nerve-daemon` package — engine runtime. Runs as a background process. |
+
+### Architecture Rules
+
+- **Three orthogonal extension points**: Sense (what to compute), Reflex (when to compute), Workflow (what to do)
+- **Process isolation**: One worker per Sense group (long-lived), one per Workflow type (on-demand). Workers never talk to each other.
+- **Causality is one-directional**: External world → Sense → Signal → Reflex → Action + Log. Logs are the end of the chain.
+
+
+
+## Language & Paradigm
+
+### Functional-first
+
+Use `function` + `type`, not `class` + `interface`.
+
+```typescript
+// ✅ Good
+type Signal = {
+  senseId: string;
+  value: unknown;
+  ts: number;
+};
+
+function createSignal(senseId: string, value: unknown): Signal {
+  return { senseId, value, ts: Date.now() };
+}
+
+// ❌ Bad — no class, no interface
+class Signal implements ISignal { ... }
+```
+
+### Rules
+
+| Rule | Description |
+|------|-------------|
+| `type` over `interface` | All type definitions use `type` |
+| `function` over `class` | Pure functions + closures, no class |
+| No `this` | Functions must not depend on `this` context |
+| No inheritance | No `extends`, `implements`, `abstract` |
+| Composition over inheritance | Use function composition |
+| Immutability first | Use `Readonly<T>`, `as const`, avoid mutation |
+| No optional properties | Use `T \| null` instead of `?:` — see below |
+
+### Exceptions
+
+Classes are allowed when:
+- Required by a third-party library (e.g. Drizzle's `sqliteTable`)
+- Error subclasses (`class NerveError extends Error`)
+
+### No Optional Properties
+
+Never use `?:`. All nullable fields must be explicit `T | null`.
+
+```typescript
+// ✅ Good
+type SenseConfig = {
+  group: string;
+  throttle: string | null;
+  timeout: string | null;
+};
+
+// ❌ Bad
+type SenseConfig = {
+  group: string;
+  throttle?: string;
+  timeout?: string;
+};
+```
+
+For mutually exclusive fields, use discriminated unions:
+
+```typescript
+// ✅ Good
+type ReflexConfig =
+  | { kind: "sense"; sense: string; interval: string | null; on: string[] | null }
+  | { kind: "workflow"; workflow: string; on: string[] | null };
+```
+
+## Modules & Exports
+
+- Always named exports, never default exports
+- One module = one responsibility, filename = purpose
+
+## Naming
+
+| Type | Style | Example |
+|------|-------|---------|
+| Files | kebab-case | `signal-bus.ts` |
+| Types | PascalCase | `SignalBus` |
+| Functions/variables | camelCase | `createSignalBus` |
+| Constants | UPPER_SNAKE | `MAX_RETRY_COUNT` |
+| Generics | Single letter or descriptive | `T`, `TValue` |
+
+## Error Handling
+
+- Use `Result` type for expected failures
+- `throw` only for unrecoverable bugs (programmer errors)
+- No try-catch for flow control
+
+```typescript
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+```
+
+## Async
+
+- Always `async/await`, never `.then()` chains
+
+## No Dynamic Import
+
+Do NOT use `await import()` in production code. Always use static top-level `import`.
+
+Exceptions (must include a comment):
+1. `sense-runtime.ts` — user module paths known only at runtime
+2. `workflow-worker.ts` — user module paths known only at runtime
+
+Test files (`__tests__/**`) are exempt.
+
+## Toolchain
+
+| Tool | Purpose |
+|------|---------|
+| **pnpm** | Package manager |
+| **TypeScript** | Type checking (strict mode) |
+| **Biome** | Lint + format (replaces ESLint + Prettier) |
+| **tsup** | Bundling |
+
+### Commands
+
+```bash
+pnpm run check      # biome check (lint + format)
+pnpm run format     # biome format --write
+pnpm run build      # full build
+pnpm test           # run tests
+```
+
+## Monorepo Structure
+
+```
+nerve/
+  packages/
+    core/           # @nerve/core — shared types and utils
+    cli/            # @nerve/cli — CLI entry point
+    daemon/         # @nerve/daemon — engine runtime
+  docs/             # RFCs, conventions
+```
+
+- `core` is the shared layer; `cli` and `daemon` both depend on it
+- `cli` and `daemon` must NOT depend on each other
+
+## Commit Convention
+
+```
+<type>(<scope>): <description>
+
+type: feat | fix | refactor | docs | chore | test
+scope: core | cli | daemon | rfc-001 | ...
+```

README.md

@@ -1,3 +1,165 @@
 # nerve
 
-Observation engine — Sense, Reflex, Workflow
+**Observation engine for autonomous agents** — sense the world, react to changes, run workflows.
+
+Nerve is a lightweight daemon that continuously observes external state through **Senses**, reacts via declarative **Reflexes**, and orchestrates multi-step **Workflows**. Built for the [Uncaged](https://github.com/uncaged) agent framework.
+
+## Core Concepts
+
+```
+External World → Sense → Signal → Reflex → Workflow → Log
+                  ↑                                     ↑
+              "what to observe"                  "what to do"
+```
+
+| 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). |
+| **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.
+
+## 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 |
+
+## Quick Start
+
+```bash
+# Requirements: Node.js ≥ 22.5, pnpm
+pnpm add -g @uncaged/nerve-cli
+
+# Initialize a workspace
+mkdir my-agent && cd my-agent
+nerve init
+
+# Write a sense
+cat > senses/cpu-usage/compute.ts << 'EOF'
+export async function compute() {
+  const [load] = (await import("node:os")).loadavg();
+  return load > 2.0 ? { load } : null;  // signal only when load is high
+}
+EOF
+
+# Configure reflexes in nerve.yaml
+cat > nerve.yaml << 'EOF'
+senses:
+  cpu-usage:
+    group: system
+    throttle: 10s
+
+reflexes:
+  - kind: sense
+    sense: cpu-usage
+    interval: 30s
+EOF
+
+# Run
+nerve dev          # foreground (development)
+nerve daemon start # background (production)
+nerve status       # check health
+nerve logs         # view logs
+```
+
+## Configuration
+
+`nerve.yaml` declares senses, reflexes, and workflows:
+
+```yaml
+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
+
+reflexes:
+  - kind: sense
+    sense: cpu-usage
+    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
+    overflow: drop         # discard if already running
+  code-review:
+    concurrency: 3
+    overflow: queue
+    maxQueue: 20
+```
+
+## 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)    │
+│          └───────────────────┘                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+- **Worker processes** — one per sense group, forked by the kernel. Isolated compute execution.
+- **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.
+
+## Tech Stack
+
+- **Zero native addons** — uses Node.js built-in `node:sqlite` (DatabaseSync)
+- **Drizzle ORM** v1.0 for sense databases
+- **rslib** (rspack) for building
+- **Biome** for formatting/linting
+- **Vitest** for testing
+- **pnpm** workspaces for monorepo management
+
+## Development
+
+```bash
+git clone https://git.shazhou.work/uncaged/nerve.git
+cd nerve
+pnpm install
+pnpm build
+pnpm -r test     # run all tests
+```
+
+## Design Documents
+
+- [RFC-001: Observation Engine](./docs/rfc-001-observation-engine.md) — Sense, Signal, Reflex model
+- [RFC-002: Workflow Engine](./docs/rfc-002-workflow-engine.md) — Stateful workflow execution
+- [Coding Conventions](./docs/coding-conventions.md)
+
+## License
+
+MIT

package.json

@@ -1,6 +1,9 @@
 {
   "name": "nerve",
   "private": true,
+  "engines": {
+    "node": ">=22.5.0"
+  },
   "scripts": {
     "build": "pnpm -r run build",
     "check": "biome check .",
@@ -8,7 +11,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.0",
-    "tsup": "^8.0.0",
+    "@rslib/core": "^0.21.3",
     "typescript": "^5.5.0"
   }
 }

packages/cli/README.md

@@ -0,0 +1,69 @@
+# @uncaged/nerve-cli
+
+Command-line interface for the [nerve](../../README.md) observation engine.
+
+## Install
+
+```bash
+pnpm add -g @uncaged/nerve-cli
+# or
+npx @uncaged/nerve-cli
+```
+
+Requires Node.js ≥ 22.5.
+
+## Commands
+
+### Workspace
+
+```bash
+nerve init                  # Initialize a nerve workspace (installs deps, scaffolds config)
+nerve validate              # Validate nerve.yaml configuration
+```
+
+### 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
+```
+
+### Development
+
+```bash
+nerve dev                   # Run in foreground mode (no daemon, Ctrl+C to stop)
+```
+
+### Querying
+
+```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
+```
+
+### Workflows
+
+```bash
+nerve workflow list         # List workflow runs
+nerve workflow show <runId> # Show workflow run details
+```
+
+### Top-level Aliases
+
+For convenience, these aliases are available:
+
+```bash
+nerve start    → nerve daemon start
+nerve stop     → nerve daemon stop
+nerve status   → nerve daemon status
+nerve logs     → nerve daemon logs
+```
+
+## License
+
+MIT

packages/cli/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@uncaged/nerve-cli",
-  "version": "0.1.8",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "version": "0.2.0",
   "type": "module",
   "bin": {
     "nerve": "dist/cli.js"
@@ -15,7 +18,7 @@
   },
   "scripts": {
     "prepublishOnly": "bash ../../scripts/prepublish-check.sh",
-    "build": "tsup",
+    "build": "rslib build",
     "test": "vitest run"
   },
   "dependencies": {
@@ -23,7 +26,7 @@
     "citty": "^0.1.6"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
+    "@rslib/core": "^0.21.3",
     "@types/node": "^22.0.0",
     "@uncaged/nerve-daemon": "workspace:*",
     "vitest": "^4.1.5"

packages/cli/rslib.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from "@rslib/core";
+
+export default defineConfig({
+  lib: [
+    {
+      format: "esm",
+      dts: true,
+      banner: {
+        js: "#!/usr/bin/env node",
+      },
+    },
+  ],
+  source: {
+    entry: {
+      index: "src/index.ts",
+      cli: "src/cli.ts",
+      "daemon-bootstrap": "src/daemon-bootstrap.ts",
+    },
+  },
+  output: {
+    target: "node",
+    cleanDistPath: true,
+    externals: ["@uncaged/nerve-daemon"],
+  },
+});

packages/cli/src/cli.ts

@@ -12,6 +12,26 @@ import { storeCommand } from "./commands/store.js";
 import { validateCommand } from "./commands/validate.js";
 import { workflowCommand } from "./commands/workflow.js";
 
+/**
+ * Citty picks the first non-flag token as a subcommand name. Rewrite
+ * `nerve init --from <url>` so the URL is not mistaken for `workflow`/`workspace`.
+ */
+function normalizeNerveArgv(argv: string[]): string[] {
+  const initIdx = argv.indexOf("init");
+  if (initIdx === -1) return argv;
+  const tail = argv.slice(initIdx + 1);
+  const fromAt = tail.indexOf("--from");
+  if (fromAt === -1) return argv;
+  const beforeFrom = tail.slice(0, fromAt);
+  if (beforeFrom.some((a) => !a.startsWith("-"))) return argv;
+  const next = tail[fromAt + 1];
+  if (next === undefined || next.startsWith("-")) return argv;
+  const reserved = new Set(["workflow", "workspace"]);
+  if (reserved.has(next)) return argv;
+  const mergedTail = [...tail.slice(0, fromAt), `--from=${next}`, ...tail.slice(fromAt + 2)];
+  return [...argv.slice(0, initIdx + 1), ...mergedTail];
+}
+
 const main = defineCommand({
   meta: {
     name: "nerve",
@@ -32,4 +52,4 @@ const main = defineCommand({
   },
 });
 
-runMain(main);
+runMain(main, { rawArgs: normalizeNerveArgv(process.argv.slice(2)) });

packages/cli/src/commands/init.ts

@@ -1,5 +1,5 @@
-import { spawn, execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 
@@ -35,7 +35,7 @@ const PACKAGE_JSON = `{
     "drizzle-kit": "latest"
   },
   "pnpm": {
-    "onlyBuiltDependencies": ["better-sqlite3", "esbuild"]
+    "onlyBuiltDependencies": ["esbuild"]
   }
 }
 `;
@@ -218,20 +218,94 @@ const initWorkspaceCommand = defineCommand({
   },
 });
 
-async function tryRequireSqlite(nerveRoot: string): Promise<boolean> {
+/** Verify built-in `node:sqlite` (Node.js ≥22.5) loads in a child process. */
+async function verifyNodeSqlite(): Promise<boolean> {
   try {
-    const modulePath = join(nerveRoot, "node_modules", "better-sqlite3");
+    await execFileAsync(
-    // Use a child process to test if the native module loads
+      "node",
-    await execFileAsync("node", ["-e", `require(${JSON.stringify(modulePath)})`], {
+      [
-      cwd: nerveRoot,
+        "--input-type=module",
-      timeout: 10_000,
+        "-e",
-    });
+        "import { DatabaseSync } from 'node:sqlite'; new DatabaseSync(':memory:').exec('SELECT 1');",
+      ],
+      { timeout: 10_000 },
+    );
     return true;
   } catch {
     return false;
   }
 }
 
+function isNerveRootNonEmpty(nerveRoot: string): boolean {
+  if (!existsSync(nerveRoot)) return false;
+  return readdirSync(nerveRoot).length > 0;
+}
+
+async function runInitFromGit(url: string): Promise<void> {
+  const trimmed = url.trim();
+  if (trimmed.length === 0) {
+    process.stderr.write("❌ --from requires a non-empty git URL.\n");
+    process.exit(1);
+  }
+
+  const nerveRoot = getNerveRoot();
+  if (isNerveRootNonEmpty(nerveRoot)) {
+    process.stderr.write(
+      `❌ ${nerveRoot} already exists and is not empty. Remove it (or empty it) before using --from.\n`,
+    );
+    process.exit(1);
+  }
+
+  try {
+    await execFileAsync("git", ["--version"]);
+  } catch {
+    process.stderr.write("❌ git is not available. Install git and retry.\n");
+    process.exit(1);
+  }
+
+  try {
+    await execFileAsync("pnpm", ["--version"]);
+  } catch {
+    process.stderr.write("❌ pnpm is not available. Install pnpm and retry.\n");
+    process.exit(1);
+  }
+
+  process.stdout.write(`Cloning ${trimmed} → ${nerveRoot} …\n`);
+  try {
+    await runCommand("git", ["clone", trimmed, nerveRoot], process.cwd());
+  } catch {
+    process.stderr.write("❌ git clone failed.\n");
+    process.exit(1);
+  }
+
+  if (!existsSync(join(nerveRoot, "nerve.yaml"))) {
+    process.stdout.write(`⚠️ ${join(nerveRoot, "nerve.yaml")} not found after clone.\n`);
+  }
+  if (!existsSync(join(nerveRoot, "package.json"))) {
+    process.stdout.write(`⚠️ ${join(nerveRoot, "package.json")} not found after clone.\n`);
+  }
+
+  process.stdout.write("Installing dependencies with pnpm …\n");
+  try {
+    await runCommand("pnpm", ["install", "--no-cache"], nerveRoot);
+  } catch {
+    process.stdout.write(
+      `⚠️ pnpm install failed. Try manually:\n   cd ${nerveRoot} && pnpm install --no-cache\n`,
+    );
+  }
+
+  if (!(await verifyNodeSqlite())) {
+    process.stdout.write(
+      "⚠️ Built-in SQLite (node:sqlite) is not available in this Node.js build. " +
+        "The daemon requires Node.js 22.5 or newer with SQLite enabled.\n",
+    );
+  }
+
+  process.stdout.write(
+    `✅ Workspace cloned to ${nerveRoot}\n\n💡 Next steps:\n   1. Review nerve.yaml and install any missing tooling.\n   2. Run \`nerve start\` to launch the daemon.\n`,
+  );
+}
+
 async function runInitWorkspace(force: boolean): Promise<void> {
   const nerveRoot = getNerveRoot();
 
@@ -264,27 +338,11 @@ async function runInitWorkspace(force: boolean): Promise<void> {
     );
   }
 
-  // Verify better-sqlite3 native module — rebuild up to 2 times if broken
+  if (!(await verifyNodeSqlite())) {
-  const sqlitePath = join(nerveRoot, "node_modules", "better-sqlite3");
+    process.stdout.write(
-  if (existsSync(sqlitePath)) {
+      "⚠️ Built-in SQLite (node:sqlite) is not available in this Node.js build. " +
-    for (let attempt = 1; attempt <= 2; attempt++) {
+        "The daemon requires Node.js 22.5 or newer with SQLite enabled.\n",
-      if (await tryRequireSqlite(nerveRoot)) break;
+    );
-      process.stdout.write(
-        `${attempt === 1 ? "Building" : "Retrying build of"} native module better-sqlite3 (attempt ${attempt}/2)…\n`,
-      );
-      try {
-        await runCommand(cmd, ["rebuild", "better-sqlite3"], nerveRoot);
-      } catch {
-        // will be caught by the verify below
-      }
-    }
-    if (!(await tryRequireSqlite(nerveRoot))) {
-      process.stdout.write(
-        `⚠️ better-sqlite3 native module is not working. The daemon will fail to start.\n` +
-          `   Fix: cd ${nerveRoot} && ${cmd} rebuild better-sqlite3\n` +
-          `   Or:  npm install --build-from-source better-sqlite3\n`,
-      );
-    }
   }
 
   if (!existsSync(join(nerveRoot, ".git"))) {
@@ -306,7 +364,7 @@ export const initCommand = defineCommand({
   meta: {
     name: "init",
     description:
-      "Initialize workspace (nerve init) or scaffold templates (nerve init workflow <name>)",
+      "Initialize workspace (nerve init), clone from git (nerve init --from <url>), or scaffold templates (nerve init workflow <name>)",
   },
   args: {
     force: {
@@ -314,12 +372,21 @@ export const initCommand = defineCommand({
       description: "Reinitialize even if workspace already exists (preserves data/)",
       default: false,
     },
+    from: {
+      type: "string",
+      description: "Clone an existing git repo into ~/.uncaged-nerve instead of scaffolding",
+      required: false,
+    },
   },
   subCommands: {
     workflow: initWorkflowCommand,
     workspace: initWorkspaceCommand,
   },
   async run({ args }) {
+    if (args.from !== undefined) {
+      await runInitFromGit(String(args.from));
+      return;
+    }
     await runInitWorkspace(args.force);
   },
 });

packages/cli/src/commands/start.ts

@@ -76,7 +76,7 @@ async function runDaemon(nerveRoot: string): Promise<void> {
 
   const child = spawn(process.execPath, [bootstrapPath], {
     detached: true,
-    stdio: ["ignore", logStream.fd, logStream.fd],
+    stdio: ["ignore", (logStream as any).fd, (logStream as any).fd],
     env: { ...process.env, NERVE_ROOT: nerveRoot },
     cwd: nerveRoot,
   });

packages/cli/tsconfig.json

@@ -6,5 +6,6 @@
     "composite": false,
     "types": ["node"]
   },
-  "include": ["src"]
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
 }

packages/cli/tsup.config.ts

@@ -1,13 +0,0 @@
-import { defineConfig } from "tsup";
-
-export default defineConfig({
-  entry: ["src/index.ts", "src/cli.ts", "src/daemon-bootstrap.ts"],
-  format: ["esm"],
-  dts: true,
-  clean: true,
-  banner: {
-    js: "#!/usr/bin/env node",
-  },
-  /** Daemon is loaded from workspace node_modules at runtime — never bundle it. */
-  external: ["@uncaged/nerve-daemon"],
-});

packages/core/README.md

@@ -0,0 +1,39 @@
+# @uncaged/nerve-core
+
+Shared types and configuration parser for the [nerve](../../README.md) observation engine.
+
+## 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)
+
+## Usage
+
+```typescript
+import { parseNerveConfig, ok, err } from "@uncaged/nerve-core";
+import type { NerveConfig, Signal, Result } from "@uncaged/nerve-core";
+
+const result: Result<NerveConfig> = parseNerveConfig(yamlString);
+if (result.ok) {
+  console.log(result.value.senses);
+}
+```
+
+## Duration Format
+
+Config fields like `throttle`, `timeout`, and `interval` accept human-readable durations:
+
+- `5s` — 5 seconds
+- `10m` — 10 minutes
+- `1h` — 1 hour
+
+## Install
+
+```bash
+pnpm add @uncaged/nerve-core
+```
+
+## License
+
+MIT

packages/core/package.json

@@ -1,18 +1,25 @@
 {
   "name": "@uncaged/nerve-core",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "types": "dist/index.d.ts",
   "scripts": {
     "prepublishOnly": "bash ../../scripts/prepublish-check.sh",
-    "build": "tsup",
+    "build": "rslib build",
     "test": "vitest run"
   },
   "dependencies": {
     "yaml": "^2.8.3"
   },
   "devDependencies": {
+    "@rslib/core": "^0.21.3",
     "vitest": "^4.1.5"
   }
 }

packages/core/rslib.config.ts

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

packages/core/tsup.config.ts

@@ -1,8 +0,0 @@
-import { defineConfig } from "tsup";
-
-export default defineConfig({
-  entry: ["src/index.ts"],
-  format: ["esm"],
-  dts: true,
-  clean: true,
-});

packages/daemon/README.md

@@ -0,0 +1,57 @@
+# @uncaged/nerve-daemon
+
+The observation engine runtime for [nerve](../../README.md) — runs senses, routes signals, schedules reflexes, and manages workflows.
+
+## 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. |
+
+## Key Design Decisions
+
+- **One worker process per sense group** — isolation between groups, shared compute within a group
+- **`node:sqlite` (DatabaseSync)** — zero native addons, WAL mode, built into Node.js ≥ 22.5
+- **Throttle + coalesce** — if compute is in-flight, at most one pending trigger is queued (no unbounded accumulation)
+- **Log ≠ Signal** — logs are queryable data assets but cannot trigger reflexes (prevents feedback loops)
+
+## Usage
+
+The daemon is typically started via the CLI (`nerve daemon start`), but can be used programmatically:
+
+```typescript
+import { createKernel } from "@uncaged/nerve-daemon";
+
+const kernel = await createKernel(nerveRoot);
+await kernel.ready;
+
+// Trigger a sense manually
+kernel.triggerSense("cpu-usage");
+
+// Check health
+const health = kernel.getHealth();
+
+// Graceful shutdown
+await kernel.stop();
+```
+
+## Install
+
+```bash
+pnpm add @uncaged/nerve-daemon
+```
+
+Requires Node.js ≥ 22.5 (for `node:sqlite`).
+
+## License
+
+MIT

packages/daemon/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/nerve-daemon",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,17 +12,17 @@
   },
   "scripts": {
     "prepublishOnly": "bash ../../scripts/prepublish-check.sh",
-    "build": "tsup",
+    "build": "rslib build",
     "test": "vitest run"
   },
   "dependencies": {
     "@uncaged/nerve-core": "workspace:*",
-    "better-sqlite3": "^11.10.0",
+    "drizzle-orm": "1.0.0-beta.23-c10d10c",
-    "drizzle-orm": "^0.43.1",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
+    "@rslib/core": "^0.21.3",
+    "@types/node": "^22.0.0",
     "vitest": "^4.1.5"
   }
 }

packages/daemon/rslib.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "@rslib/core";
+
+export default defineConfig({
+  lib: [
+    {
+      format: "esm",
+      dts: true,
+    },
+  ],
+  source: {
+    entry: {
+      index: "src/index.ts",
+      "sense-worker": "src/sense-worker.ts",
+    },
+  },
+  output: {
+    target: "node",
+    cleanDistPath: true,
+  },
+});

packages/daemon/src/__tests__/crash-recovery.test.ts

@@ -89,10 +89,11 @@ function makeLogStore(
       }
       return activeRuns;
     }),
-    getTriggerPayload: vi.fn(() => ({ value: 42 })),
+    getTriggerPayload: vi.fn((): unknown => ({ value: 42 })),
-    getThreadEvents: vi.fn(() => [{ type: "thread_start", triggerPayload: {} }]),
+    getThreadEvents: vi.fn((): Array<{ type: string; [key: string]: unknown }> => [{ type: "thread_start", triggerPayload: {} }]),
     archiveLogs: vi.fn(() => ({ days: [], vacuumed: false })),
     close: vi.fn(),
+    getAllWorkflowRuns: vi.fn(() => []),
   };
   return store;
 }
@@ -127,7 +128,7 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
       child.emit("exit", 1, null);
 
       const crashedCalls = logStore.upsertWorkflowRun.mock.calls.filter(
-        ([entry]: [{ type: string }]) => entry.type === "crashed",
+        (args: any[]) => (args[0] as { type: string }).type === "crashed",
       );
       expect(crashedCalls).toHaveLength(2);
 
@@ -216,10 +217,10 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
 
       // resume-thread should have been sent
       const resumeCalls = (secondChild.send as ReturnType<typeof vi.fn>).mock.calls.filter(
-        ([msg]: [unknown]) =>
+        (args: any[]) =>
-          msg !== null &&
+          args[0] !== null &&
-          typeof msg === "object" &&
+          typeof args[0] === "object" &&
-          (msg as Record<string, unknown>).type === "resume-thread",
+          (args[0] as Record<string, unknown>).type === "resume-thread",
       );
       expect(resumeCalls).toHaveLength(1);
       expect(resumeCalls[0][0]).toMatchObject({
@@ -286,7 +287,7 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
       });
 
       const appendCalls = logStore.append.mock.calls.filter(
-        ([entry]: [{ type: string }]) => entry.type === "thread_command_event",
+        (args: any[]) => (args[0] as { type: string }).type === "thread_command_event",
       );
       expect(appendCalls).toHaveLength(1);
       expect(appendCalls[0][0]).toMatchObject({
@@ -313,7 +314,7 @@ describe("WorkflowManager — crash recovery (Phase 3)", () => {
       mgr.startWorkflow("my-wf", payload);
 
       const startedCall = logStore.upsertWorkflowRun.mock.calls.find(
-        ([entry]: [{ type: string }]) => entry.type === "started",
+        (args: any[]) => (args[0] as { type: string }).type === "started",
       );
       expect(startedCall).toBeDefined();
       const logEntry = startedCall?.[0] as { payload: string | null };

packages/daemon/src/__tests__/hot-reload.test.ts

@@ -79,6 +79,7 @@ function makeLogStore() {
     getThreadEvents: vi.fn(() => []),
     archiveLogs: vi.fn(() => ({ days: [], vacuumed: false })),
     close: vi.fn(),
+    getAllWorkflowRuns: vi.fn(() => []),
   };
 }
 
@@ -126,7 +127,7 @@ describe("WorkflowManager — drainAndRespawn (Phase 3 hot reload)", () => {
     await drainPromise;
 
     const interruptedCalls = logStore.upsertWorkflowRun.mock.calls.filter(
-      ([entry]: [{ type: string }]) => entry.type === "interrupted",
+      (args: any[]) => (args[0] as { type: string }).type === "interrupted",
     );
     expect(interruptedCalls).toHaveLength(2);
 
@@ -190,10 +191,10 @@ describe("WorkflowManager — drainAndRespawn (Phase 3 hot reload)", () => {
 
     const newChild = mockChildren[1];
     const resumeCalls = (newChild.send as ReturnType<typeof vi.fn>).mock.calls.filter(
-      ([msg]: [unknown]) =>
+      (args: any[]) =>
-        msg !== null &&
+        args[0] !== null &&
-        typeof msg === "object" &&
+        typeof args[0] === "object" &&
-        (msg as Record<string, unknown>).type === "resume-thread",
+        (args[0] as Record<string, unknown>).type === "resume-thread",
     );
     expect(resumeCalls).toHaveLength(0);
 
@@ -218,10 +219,10 @@ describe("WorkflowManager — drainAndRespawn (Phase 3 hot reload)", () => {
 
     const newChild = mockChildren[1];
     const startCalls = (newChild.send as ReturnType<typeof vi.fn>).mock.calls.filter(
-      ([msg]: [unknown]) =>
+      (args: any[]) =>
-        msg !== null &&
+        args[0] !== null &&
-        typeof msg === "object" &&
+        typeof args[0] === "object" &&
-        (msg as Record<string, unknown>).type === "start-thread",
+        (args[0] as Record<string, unknown>).type === "start-thread",
     );
     expect(startCalls).toHaveLength(1);
 
@@ -266,7 +267,7 @@ describe("Kernel — workflow hot reload via file-watcher (Phase 3)", () => {
     // Kernel's handleWorkflowFileChange should log a workflow_reload event
     // We test this via the kernel itself
     const appendCalls = logStore.append.mock.calls;
-    const startCall = appendCalls.find(([e]: [{ type: string }]) => e.type === "start");
+    const startCall = appendCalls.find((args: any[]) => (args[0] as { type: string }).type === "start");
     expect(startCall).toBeDefined();
 
     const stopPromise = kernel.stop();

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

@@ -2,7 +2,7 @@
  * Unit tests for kernel.triggerSense() — IPC issue #36.
  *
  * These tests use a mock child_process and a mock LogStore so they do NOT
- * require better-sqlite3 to be present in the test environment.
+ * require a real LogStore (node:sqlite) in integration tests.
  */
 
 import { EventEmitter } from "node:events";
@@ -58,7 +58,7 @@ vi.mock("node:child_process", () => ({
 const { createKernel } = await import("../kernel.js");
 
 // ---------------------------------------------------------------------------
-// Mock LogStore factory (avoids better-sqlite3 dependency)
+// Mock LogStore factory (avoids SQLite I/O in this unit test)
 // ---------------------------------------------------------------------------
 
 function makeMockLogStore() {

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

@@ -78,6 +78,7 @@ function makeLogStore() {
     appendWithWorkflowUpdate: vi.fn(),
     getWorkflowRun: vi.fn(() => null),
     getActiveWorkflowRuns: vi.fn(() => []),
+    getAllWorkflowRuns: vi.fn(() => []),
     getTriggerPayload: vi.fn(() => null),
     getThreadEvents: vi.fn(() => []),
     archiveLogs: vi.fn(() => ({ days: [], vacuumed: false })),
@@ -137,10 +138,10 @@ describe("kernel + workflowManager integration", () => {
       // We need to check that a start-thread message was sent to the workflow worker
       const workflowWorker = mockChildren.find((c) =>
         (c.send as ReturnType<typeof vi.fn>).mock.calls.some(
-          ([msg]: [unknown]) =>
+          (args: unknown[]) =>
-            msg !== null &&
+            args[0] !== null &&
-            typeof msg === "object" &&
+            typeof args[0] === "object" &&
-            (msg as Record<string, unknown>).type === "start-thread",
+            (args[0] as Record<string, unknown>).type === "start-thread",
         ),
       );
       expect(workflowWorker).toBeDefined();
@@ -212,10 +213,10 @@ describe("kernel + workflowManager integration", () => {
       // No workflow worker should have been spawned (only the sense group worker)
       const workflowWorkerSpawned = mockChildren.some((c) =>
         (c.send as ReturnType<typeof vi.fn>).mock.calls.some(
-          ([msg]: [unknown]) =>
+          (args: unknown[]) =>
-            msg !== null &&
+            args[0] !== null &&
-            typeof msg === "object" &&
+            typeof args[0] === "object" &&
-            (msg as Record<string, unknown>).type === "start-thread",
+            (args[0] as Record<string, unknown>).type === "start-thread",
         ),
       );
       expect(workflowWorkerSpawned).toBe(false);

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

@@ -2,15 +2,15 @@ import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import Database from "better-sqlite3";
+import { DatabaseSync } from "node:sqlite";
-import { drizzle } from "drizzle-orm/better-sqlite3";
+import { drizzle } from "drizzle-orm/node-sqlite";
 import { integer, real, sqliteTable } from "drizzle-orm/sqlite-core";
 import { describe, expect, it } from "vitest";
 
 import { createBlobStore } from "../blob-store.js";
 import { parseParentMessage } from "../ipc.js";
 import { executeCompute, openPeerDb, openSenseDb, runMigrations } from "../sense-runtime.js";
-import type { DrizzleDB, PeerMap, SenseRuntime } from "../sense-runtime.js";
+import type { ComputeFn, DrizzleDB, PeerMap, SenseRuntime } from "../sense-runtime.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -49,7 +49,7 @@ const samples = sqliteTable("samples", {
 
 describe("runMigrations", () => {
   it("creates table via SQL migration file", () => {
-    const sqlite = new Database(":memory:");
+    const sqlite = new DatabaseSync(":memory:");
     const migrationsDir = makeTempMigrationsDir(INIT_SQL);
     const result = runMigrations(sqlite, migrationsDir);
 
@@ -64,7 +64,7 @@ describe("runMigrations", () => {
   });
 
   it("runs multiple migrations in lexicographic order", () => {
-    const sqlite = new Database(":memory:");
+    const sqlite = new DatabaseSync(":memory:");
     const dir = mkdtempSync(join(tmpdir(), "nerve-multi-"));
 
     writeFileSync(join(dir, "0001_init.sql"), INIT_SQL);
@@ -81,7 +81,7 @@ describe("runMigrations", () => {
   });
 
   it("returns ok when migrations directory is empty", () => {
-    const sqlite = new Database(":memory:");
+    const sqlite = new DatabaseSync(":memory:");
     const dir = makeTempMigrationsDirEmpty();
     const result = runMigrations(sqlite, dir);
     expect(result.ok).toBe(true);
@@ -89,14 +89,14 @@ describe("runMigrations", () => {
   });
 
   it("returns err when migrations directory does not exist", () => {
-    const sqlite = new Database(":memory:");
+    const sqlite = new DatabaseSync(":memory:");
     const result = runMigrations(sqlite, "/nonexistent/path/migrations");
     expect(result.ok).toBe(false);
     sqlite.close();
   });
 
   it("returns err when a migration SQL is invalid", () => {
-    const sqlite = new Database(":memory:");
+    const sqlite = new DatabaseSync(":memory:");
     const dir = mkdtempSync(join(tmpdir(), "nerve-bad-sql-"));
     writeFileSync(join(dir, "0001_bad.sql"), "NOT VALID SQL !!!;");
     const result = runMigrations(sqlite, dir);
@@ -141,7 +141,7 @@ describe("openPeerDb", () => {
   it("opens an existing db in read-only mode", () => {
     // Create a writable db first
     const dbPath = makeTempDbPath();
-    const sqlite = new Database(dbPath);
+    const sqlite = new DatabaseSync(dbPath);
     sqlite.exec(INIT_SQL);
     sqlite.prepare("INSERT INTO samples (ts, value) VALUES (1, 42.0)").run();
     sqlite.close();
@@ -168,13 +168,13 @@ describe("openPeerDb", () => {
 // ---------------------------------------------------------------------------
 
 describe("executeCompute", () => {
-  function makeRuntime(computeFn: (db: DrizzleDB, peers: PeerMap) => Promise<unknown | null>): {
+  function makeRuntime(computeFn: ComputeFn): {
     runtime: SenseRuntime;
-    sqlite: Database.Database;
+    sqlite: DatabaseSync;
   } {
-    const sqlite = new Database(":memory:");
+    const sqlite = new DatabaseSync(":memory:");
     sqlite.exec(INIT_SQL);
-    const db = drizzle(sqlite) as DrizzleDB;
+    const db = drizzle({ client: sqlite }) as DrizzleDB;
     return {
       runtime: { name: "test-sense", db, compute: computeFn },
       sqlite,
@@ -226,10 +226,10 @@ describe("executeCompute", () => {
 
   it("compute can read from peers", async () => {
     // Set up a peer db with data
-    const peerSqlite = new Database(":memory:");
+    const peerSqlite = new DatabaseSync(":memory:");
     peerSqlite.exec(INIT_SQL);
     peerSqlite.prepare("INSERT INTO samples (ts, value) VALUES (100, 3.14)").run();
-    const peerDb = drizzle(peerSqlite) as DrizzleDB;
+    const peerDb = drizzle({ client: peerSqlite }) as DrizzleDB;
 
     const peers: PeerMap = { "other-sense": peerDb };
 
@@ -248,9 +248,9 @@ describe("executeCompute", () => {
   });
 
   it("write to own db does not affect peer db (isolation)", async () => {
-    const peerSqlite = new Database(":memory:");
+    const peerSqlite = new DatabaseSync(":memory:");
     peerSqlite.exec(INIT_SQL);
-    const peerDb = drizzle(peerSqlite) as DrizzleDB;
+    const peerDb = drizzle({ client: peerSqlite }) as DrizzleDB;
     const peers: PeerMap = { "peer-sense": peerDb };
 
     const { runtime, sqlite } = makeRuntime(async (db) => {
@@ -403,7 +403,7 @@ describe("parseParentMessage", () => {
 
 describe("runMigrations journal", () => {
   it("does not re-run an already-applied migration", () => {
-    const sqlite = new Database(":memory:");
+    const sqlite = new DatabaseSync(":memory:");
     const dir = mkdtempSync(join(tmpdir(), "nerve-journal-"));
     writeFileSync(join(dir, "0001_init.sql"), INIT_SQL);
 
@@ -430,7 +430,7 @@ describe("runMigrations journal", () => {
   });
 
   it("tracks migrations in _migrations table", () => {
-    const sqlite = new Database(":memory:");
+    const sqlite = new DatabaseSync(":memory:");
     const dir = mkdtempSync(join(tmpdir(), "nerve-journal2-"));
     writeFileSync(join(dir, "0001_init.sql"), INIT_SQL);
 

packages/daemon/src/__tests__/workflow-manager.test.ts

@@ -76,6 +76,7 @@ function makeLogStore() {
     getThreadEvents: vi.fn(() => []),
     archiveLogs: vi.fn(() => ({ days: [], vacuumed: false })),
     close: vi.fn(),
+    getAllWorkflowRuns: vi.fn(() => []),
   };
 }
 

packages/daemon/src/log-store.ts

@@ -9,8 +9,7 @@
 
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import Database from "better-sqlite3";
+import { DatabaseSync, type StatementSync } from "node:sqlite";
-import type BetterSqlite3 from "better-sqlite3";
 
 import {
   DEFAULT_LOG_RETENTION_MS,
@@ -184,7 +183,23 @@ function buildJsonlBody(rows: SqlLogRow[]): string {
   return `${lines.join("\n")}\n`;
 }
 
-function runOptionalVacuum(sqlite: BetterSqlite3.Database, vacuum?: boolean): boolean {
+function runInTransaction<T>(db: DatabaseSync, fn: () => T): T {
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const out = fn();
+    db.exec("COMMIT");
+    return out;
+  } catch (e) {
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+      // ignore rollback errors
+    }
+    throw e;
+  }
+}
+
+function runOptionalVacuum(sqlite: DatabaseSync, vacuum?: boolean): boolean {
   if (vacuum !== true) return false;
   sqlite.exec("VACUUM");
   return true;
@@ -199,7 +214,7 @@ function resolveArchiveStartDay(watermark: string | null, minDay: string): strin
 function runArchiveDayLoop(
   dbPath: string,
   options: ArchiveLogsOptions,
-  selectLogsForDayStmt: BetterSqlite3.Statement,
+  selectLogsForDayStmt: StatementSync,
   archiveDayTx: (day: string, start: number, endExclusive: number) => void,
   startDay: string,
   lastDay: string,
@@ -235,8 +250,8 @@ function runArchiveDayLoop(
 export function createLogStore(dbPath: string): LogStore {
   mkdirSync(dirname(dbPath), { recursive: true });
 
-  const sqlite: BetterSqlite3.Database = new Database(dbPath);
+  const sqlite = new DatabaseSync(dbPath);
-  sqlite.pragma("journal_mode = WAL");
+  sqlite.exec("PRAGMA journal_mode=WAL");
   sqlite.exec(SCHEMA_SQL);
 
   const insertStmt = sqlite.prepare(
@@ -288,8 +303,8 @@ export function createLogStore(dbPath: string): LogStore {
     "DELETE FROM logs WHERE ts >= @start AND ts < @endExclusive",
   );
 
-  const upsertWorkflowRunTx = sqlite.transaction(
+  function upsertWorkflowRunTx(entry: Omit<LogEntry, "id">, run: WorkflowRun): LogEntry {
-    (entry: Omit<LogEntry, "id">, run: WorkflowRun) => {
+    return runInTransaction(sqlite, () => {
       const info = insertStmt.run({
         source: entry.source,
         type: entry.type,
@@ -304,8 +319,8 @@ export function createLogStore(dbPath: string): LogStore {
         ts: run.ts,
       });
       return { ...entry, id: Number(info.lastInsertRowid) };
-    },
+    });
-  );
+  }
 
   function append(entry: Omit<LogEntry, "id">): LogEntry {
     const info = insertStmt.run({
@@ -320,7 +335,7 @@ export function createLogStore(dbPath: string): LogStore {
 
   function query(filter: LogQuery = {}): LogEntry[] {
     const conditions: string[] = [];
-    const params: Record<string, unknown> = {};
+    const params: Record<string, string | number> = {};
 
     if (filter.source !== undefined) {
       conditions.push("source = @source");
@@ -376,11 +391,11 @@ export function createLogStore(dbPath: string): LogStore {
   }
 
   function upsertWorkflowRun(entry: Omit<LogEntry, "id">, run: WorkflowRun): LogEntry {
-    return upsertWorkflowRunTx(entry, run) as LogEntry;
+    return upsertWorkflowRunTx(entry, run);
   }
 
   function appendWithWorkflowUpdate(entry: Omit<LogEntry, "id">, run: WorkflowRun): LogEntry {
-    return upsertWorkflowRunTx(entry, run) as LogEntry;
+    return upsertWorkflowRunTx(entry, run);
   }
 
   function getWorkflowRun(runId: string): WorkflowRun | null {
@@ -460,10 +475,12 @@ export function createLogStore(dbPath: string): LogStore {
     return result;
   }
 
-  const archiveDayTx = sqlite.transaction((day: string, start: number, endExclusive: number) => {
+  function archiveDayTx(day: string, start: number, endExclusive: number): void {
-    deleteLogsForDayStmt.run({ start, endExclusive });
+    runInTransaction(sqlite, () => {
-    setMetaStmt.run({ key: LOG_ARCHIVE_META_KEY, value: day });
+      deleteLogsForDayStmt.run({ start, endExclusive });
-  });
+      setMetaStmt.run({ key: LOG_ARCHIVE_META_KEY, value: day });
+    });
+  }
 
   function readWatermark(): string | null {
     const raw = getMeta(LOG_ARCHIVE_META_KEY);

packages/daemon/src/sense-runtime.ts

@@ -1,9 +1,9 @@
 import { mkdirSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
 
-import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/node-sqlite";
-import { drizzle } from "drizzle-orm/better-sqlite3";
+import type { NodeSQLiteDatabase } from "drizzle-orm/node-sqlite";
-import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
 
 import type { Result } from "@uncaged/nerve-core";
 import { err, ok } from "@uncaged/nerve-core";
@@ -11,7 +11,7 @@ import { err, ok } from "@uncaged/nerve-core";
 import type { BlobStore } from "./blob-store.js";
 
 /** A Drizzle DB instance (schema-generic) */
-export type DrizzleDB = BetterSQLite3Database<Record<string, never>>;
+export type DrizzleDB = NodeSQLiteDatabase<Record<string, never>>;
 
 /** Read-only map of peer sense name → their Drizzle DB */
 export type PeerMap = Readonly<Record<string, DrizzleDB>>;
@@ -42,7 +42,7 @@ export type SenseRuntime = {
   compute: ComputeFn;
 };
 
-function ensureMigrationsTable(sqlite: Database.Database): Result<void> {
+function ensureMigrationsTable(sqlite: DatabaseSync): Result<void> {
   try {
     sqlite.exec(
       `CREATE TABLE IF NOT EXISTS _migrations (
@@ -69,11 +69,7 @@ function listMigrationFiles(migrationsDir: string): Result<string[]> {
   }
 }
 
-function applyMigrationFile(
+function applyMigrationFile(sqlite: DatabaseSync, file: string, filePath: string): Result<void> {
-  sqlite: Database.Database,
-  file: string,
-  filePath: string,
-): Result<void> {
   let sql: string;
   try {
     sql = readFileSync(filePath, "utf8");
@@ -83,13 +79,18 @@ function applyMigrationFile(
   }
 
   const insertJournal = sqlite.prepare("INSERT INTO _migrations (name, applied_at) VALUES (?, ?)");
+  sqlite.exec("BEGIN IMMEDIATE");
   try {
-    sqlite.transaction(() => {
+    sqlite.exec(sql);
-      sqlite.exec(sql);
+    insertJournal.run(file, Date.now());
-      insertJournal.run(file, Date.now());
+    sqlite.exec("COMMIT");
-    })();
     return ok(undefined);
   } catch (e) {
+    try {
+      sqlite.exec("ROLLBACK");
+    } catch {
+      // ignore secondary errors during rollback
+    }
     const msg = e instanceof Error ? e.message : String(e);
     return err(new Error(`Migration "${file}" failed: ${msg}`));
   }
@@ -97,10 +98,10 @@ function applyMigrationFile(
 
 /**
  * Run all *.sql migration files in the given directory against a
- * better-sqlite3 Database, in lexicographic order.
+ * `node:sqlite` DatabaseSync, in lexicographic order.
  * Tracks applied migrations in _migrations table to avoid re-running.
  */
-export function runMigrations(sqlite: Database.Database, migrationsDir: string): Result<void> {
+export function runMigrations(sqlite: DatabaseSync, migrationsDir: string): Result<void> {
   const tableResult = ensureMigrationsTable(sqlite);
   if (!tableResult.ok) return tableResult;
 
@@ -129,14 +130,13 @@ export function runMigrations(sqlite: Database.Database, migrationsDir: string):
 export function openSenseDb(
   dbPath: string,
   migrationsDir: string,
-): Result<{ sqlite: Database.Database; db: DrizzleDB }> {
+): Result<{ sqlite: DatabaseSync; db: DrizzleDB }> {
-  let sqlite: Database.Database;
+  let sqlite: DatabaseSync;
 
   try {
     mkdirSync(dirname(dbPath), { recursive: true });
-    sqlite = new Database(dbPath);
+    sqlite = new DatabaseSync(dbPath);
-    // WAL mode for better concurrent read performance
+    sqlite.exec("PRAGMA journal_mode=WAL");
-    sqlite.pragma("journal_mode = WAL");
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
     return err(new Error(`Failed to open database "${dbPath}": ${msg}`));
@@ -145,7 +145,7 @@ export function openSenseDb(
   const migResult = runMigrations(sqlite, migrationsDir);
   if (!migResult.ok) return migResult;
 
-  const db = drizzle(sqlite) as DrizzleDB;
+  const db = drizzle({ client: sqlite }) as DrizzleDB;
   return ok({ sqlite, db });
 }
 
@@ -153,16 +153,16 @@ export function openSenseDb(
  * Open a peer sense DB in read-only mode (no migrations).
  */
 export function openPeerDb(dbPath: string): Result<DrizzleDB> {
-  let sqlite: Database.Database;
+  let sqlite: DatabaseSync;
 
   try {
-    sqlite = new Database(dbPath, { readonly: true });
+    sqlite = new DatabaseSync(dbPath, { readOnly: true });
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
     return err(new Error(`Failed to open peer database "${dbPath}" (readonly): ${msg}`));
   }
 
-  return ok(drizzle(sqlite) as DrizzleDB);
+  return ok(drizzle({ client: sqlite }) as DrizzleDB);
 }
 
 /**

packages/daemon/src/workflow-worker.ts

@@ -120,8 +120,7 @@ async function runThread(
 
   const initialEvent: CommandEvent = {
     type: "thread_start",
-    triggerPayload:
+    triggerPayload: triggerPayload ?? {},
-      triggerPayload != null && typeof triggerPayload === "object" ? triggerPayload : {},
   };
 
   // On resume: replay persisted events, run the next un-executed role, then continue.

packages/daemon/tsup.config.ts

@@ -1,8 +0,0 @@
-import { defineConfig } from "tsup";
-
-export default defineConfig({
-  entry: ["src/index.ts", "src/sense-worker.ts"],
-  format: ["esm"],
-  dts: true,
-  clean: true,
-});

pnpm-workspace.yaml

@@ -3,5 +3,4 @@ packages:
 
 onlyBuiltDependencies:
   - "@biomejs/biome"
-  - better-sqlite3
   - esbuild