feat(daemon): add log store archival with meta watermark + JSONL cold archive — closes #38

- Add meta table with archived_up_to watermark in logs.db
- Archive logs older than 30 days to data/archive/logs/YYYY-MM-DD.jsonl
- Idempotent: same-day re-export overwrites file
- Single transaction: DELETE + UPDATE meta
- Optional VACUUM after archive loop
- CLI: nerve store archive [--vacuum]
- 15+ new tests for archive logic

packages/cli/package.json

@@ -1,22 +1,30 @@
 {
   "name": "@uncaged/nerve-cli",
-  "version": "0.0.1",
-  "private": true,
+  "version": "0.1.4",
   "type": "module",
   "bin": {
     "nerve": "dist/cli.js"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "build": "tsup"
+    "build": "tsup",
+    "test": "vitest run"
   },
   "dependencies": {
     "@uncaged/nerve-core": "workspace:*",
-    "@uncaged/nerve-daemon": "workspace:*",
     "citty": "^0.1.6"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0"
+    "@uncaged/nerve-daemon": "workspace:*",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.0.0",
+    "vitest": "^4.1.5"
   }
 }

packages/cli/src/__tests__/daemon-types.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Compile-time check: daemon-types.ts stays in sync with @uncaged/nerve-daemon exports.
+ * If the daemon package changes its public API, this file will fail to compile.
+ */
+
+import type {
+  ArchiveLogsDayResult as DaemonArchiveLogsDayResult,
+  ArchiveLogsOptions as DaemonArchiveLogsOptions,
+  ArchiveLogsResult as DaemonArchiveLogsResult,
+  LogEntry as DaemonLogEntry,
+  LogQuery as DaemonLogQuery,
+  LogStore as DaemonLogStore,
+  WorkflowRun as DaemonWorkflowRun,
+  WorkflowRunStatus as DaemonWorkflowRunStatus,
+} from "@uncaged/nerve-daemon";
+import { describe, expectTypeOf, it } from "vitest";
+
+import type {
+  ArchiveLogsDayResult,
+  ArchiveLogsOptions,
+  ArchiveLogsResult,
+  LogEntry,
+  LogQuery,
+  LogStore,
+  WorkflowRun,
+  WorkflowRunStatus,
+} from "../daemon-types.js";
+
+describe("daemon-types drift guard", () => {
+  it("WorkflowRunStatus is assignable both ways", () => {
+    expectTypeOf<WorkflowRunStatus>().toMatchTypeOf<DaemonWorkflowRunStatus>();
+    expectTypeOf<DaemonWorkflowRunStatus>().toMatchTypeOf<WorkflowRunStatus>();
+  });
+
+  it("WorkflowRun is assignable both ways", () => {
+    expectTypeOf<WorkflowRun>().toMatchTypeOf<DaemonWorkflowRun>();
+    expectTypeOf<DaemonWorkflowRun>().toMatchTypeOf<WorkflowRun>();
+  });
+
+  it("LogEntry is assignable both ways", () => {
+    expectTypeOf<LogEntry>().toMatchTypeOf<DaemonLogEntry>();
+    expectTypeOf<DaemonLogEntry>().toMatchTypeOf<LogEntry>();
+  });
+
+  it("LogQuery is assignable both ways", () => {
+    expectTypeOf<LogQuery>().toMatchTypeOf<DaemonLogQuery>();
+    expectTypeOf<DaemonLogQuery>().toMatchTypeOf<LogQuery>();
+  });
+
+  it("LogStore has all required methods", () => {
+    expectTypeOf<LogStore>().toMatchTypeOf<
+      Pick<
+        DaemonLogStore,
+        | "query"
+        | "getWorkflowRun"
+        | "getActiveWorkflowRuns"
+        | "getAllWorkflowRuns"
+        | "upsertWorkflowRun"
+        | "archiveLogs"
+        | "close"
+      >
+    >();
+  });
+
+  it("ArchiveLogs types match daemon", () => {
+    expectTypeOf<ArchiveLogsOptions>().toMatchTypeOf<DaemonArchiveLogsOptions>();
+    expectTypeOf<DaemonArchiveLogsOptions>().toMatchTypeOf<ArchiveLogsOptions>();
+    expectTypeOf<ArchiveLogsResult>().toMatchTypeOf<DaemonArchiveLogsResult>();
+    expectTypeOf<DaemonArchiveLogsResult>().toMatchTypeOf<ArchiveLogsResult>();
+    expectTypeOf<ArchiveLogsDayResult>().toMatchTypeOf<DaemonArchiveLogsDayResult>();
+    expectTypeOf<DaemonArchiveLogsDayResult>().toMatchTypeOf<ArchiveLogsDayResult>();
+  });
+});

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

@@ -0,0 +1,81 @@
+/**
+ * Tests for nerve init workflow scaffold logic.
+ *
+ * We test the file-generation path by isolating the template rendering,
+ * not by invoking the full citty command (which calls process.exit).
+ */
+
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildWorkflowTemplate } from "../commands/init.js";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "nerve-cli-init-test-"));
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("buildWorkflowTemplate", () => {
+  it("includes the workflow name in the template", () => {
+    const tpl = buildWorkflowTemplate("my-workflow");
+    expect(tpl).toContain("my-workflow started");
+  });
+
+  it("contains WorkflowDefinition type import", () => {
+    const tpl = buildWorkflowTemplate("test");
+    expect(tpl).toContain("WorkflowDefinition");
+    expect(tpl).toContain("@uncaged/nerve-daemon");
+  });
+
+  it("contains a moderate function that returns null to signal completion", () => {
+    const tpl = buildWorkflowTemplate("test");
+    expect(tpl).toContain("return null");
+    expect(tpl).toContain("moderate");
+  });
+
+  it("contains a roles map with main role", () => {
+    const tpl = buildWorkflowTemplate("test");
+    expect(tpl).toContain("roles:");
+    expect(tpl).toContain("main:");
+  });
+
+  it("uses different names per call", () => {
+    const a = buildWorkflowTemplate("workflow-a");
+    const b = buildWorkflowTemplate("workflow-b");
+    expect(a).toContain("workflow-a started");
+    expect(b).toContain("workflow-b started");
+    expect(a).not.toContain("workflow-b");
+  });
+
+  it("produces valid TypeScript syntax (no unclosed braces)", () => {
+    const tpl = buildWorkflowTemplate("test");
+    const opens = (tpl.match(/\{/g) ?? []).length;
+    const closes = (tpl.match(/\}/g) ?? []).length;
+    expect(opens).toBe(closes);
+  });
+
+  it("ends with export default workflow", () => {
+    const tpl = buildWorkflowTemplate("test");
+    expect(tpl.trim().endsWith("export default workflow;")).toBe(true);
+  });
+});
+
+describe("workflow scaffold file writing (simulated)", () => {
+  it("writes the template to disk correctly", () => {
+    const { mkdirSync, writeFileSync } = require("node:fs");
+    const workflowDir = join(tmpDir, "workflows", "my-task");
+    mkdirSync(workflowDir, { recursive: true });
+    const content = buildWorkflowTemplate("my-task");
+    writeFileSync(join(workflowDir, "index.ts"), content, "utf8");
+
+    const read = readFileSync(join(workflowDir, "index.ts"), "utf8");
+    expect(read).toContain("my-task started");
+    expect(read).toContain("WorkflowDefinition");
+  });
+});

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

@@ -0,0 +1,250 @@
+/**
+ * Tests for nerve logs command — pure helper functions only.
+ *
+ * We test sliceLogs and buildLogFooter without touching the filesystem or
+ * spawning a real process.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { DEFAULT_LOG_LINES, buildLogFooter, readAllLines, sliceLogs } from "../commands/logs.js";
+import { logsCommand } from "../commands/logs.js";
+
+// ---------------------------------------------------------------------------
+// sliceLogs
+// ---------------------------------------------------------------------------
+
+describe("sliceLogs", () => {
+  const make = (n: number) => Array.from({ length: n }, (_, i) => `line ${i + 1}`);
+
+  it("returns empty result for empty array", () => {
+    const r = sliceLogs([], 0, 50);
+    expect(r.lines).toHaveLength(0);
+    expect(r.total).toBe(0);
+    expect(r.nextOffset).toBeNull();
+  });
+
+  it("tail mode (offset=0): returns last N lines", () => {
+    const lines = make(100);
+    const r = sliceLogs(lines, 0, 10);
+    expect(r.lines).toHaveLength(10);
+    expect(r.lines[0]).toBe("line 91");
+    expect(r.lines[9]).toBe("line 100");
+    expect(r.startLine).toBe(91);
+    expect(r.endLine).toBe(100);
+  });
+
+  it("tail mode: when file shorter than limit, returns all", () => {
+    const lines = make(20);
+    const r = sliceLogs(lines, 0, 50);
+    expect(r.lines).toHaveLength(20);
+    expect(r.startLine).toBe(1);
+    expect(r.endLine).toBe(20);
+    expect(r.nextOffset).toBeNull();
+  });
+
+  it("tail mode: provides nextOffset when earlier lines exist", () => {
+    const lines = make(200);
+    const r = sliceLogs(lines, 0, 50);
+    expect(r.nextOffset).not.toBeNull();
+    expect(r.nextOffset).toBe(151 - 50); // startLine=151, prev page starts at 101
+  });
+
+  it("tail mode: nextOffset is null when showing from line 1", () => {
+    const lines = make(40);
+    const r = sliceLogs(lines, 0, 50);
+    expect(r.nextOffset).toBeNull();
+  });
+
+  it("offset mode: starts at given 1-based line number", () => {
+    const lines = make(100);
+    const r = sliceLogs(lines, 10, 5);
+    expect(r.lines[0]).toBe("line 10");
+    expect(r.startLine).toBe(10);
+    expect(r.endLine).toBe(14);
+  });
+
+  it("offset mode: clamps start to 0 for offset=1", () => {
+    const lines = make(50);
+    const r = sliceLogs(lines, 1, 10);
+    expect(r.startLine).toBe(1);
+  });
+
+  it("offset mode: nextOffset is null when slice starts at line 1", () => {
+    const lines = make(50);
+    const r = sliceLogs(lines, 1, 20);
+    expect(r.nextOffset).toBeNull();
+  });
+
+  it("offset mode: nextOffset points to previous page", () => {
+    const lines = make(100);
+    const r = sliceLogs(lines, 51, 50); // lines 51-100
+    expect(r.nextOffset).toBe(1); // previous page starts at line 1
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildLogFooter
+// ---------------------------------------------------------------------------
+
+describe("buildLogFooter", () => {
+  it("returns empty-file message when total=0", () => {
+    const slice = { lines: [], total: 0, startLine: 0, endLine: 0, nextOffset: null };
+    expect(buildLogFooter(slice, 50, "/path/to/nerve.log")).toContain("empty");
+  });
+
+  it("includes range and path in footer", () => {
+    const slice = { lines: ["x"], total: 200, startLine: 151, endLine: 200, nextOffset: 101 };
+    const footer = buildLogFooter(slice, 50, "/var/log/nerve.log");
+    expect(footer).toContain("lines 151-200 of 200");
+    expect(footer).toContain("/var/log/nerve.log");
+  });
+
+  it("includes pagination hint when nextOffset is set", () => {
+    const slice = { lines: ["x"], total: 200, startLine: 151, endLine: 200, nextOffset: 101 };
+    const footer = buildLogFooter(slice, 50, "/path/nerve.log");
+    expect(footer).toContain("nerve logs --offset 101 -n 50");
+  });
+
+  it("no pagination hint when nextOffset is null", () => {
+    const slice = { lines: ["x"], total: 20, startLine: 1, endLine: 20, nextOffset: null };
+    const footer = buildLogFooter(slice, 50, "/path/nerve.log");
+    expect(footer).not.toContain("nerve logs --offset");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// DEFAULT_LOG_LINES constant
+// ---------------------------------------------------------------------------
+
+describe("DEFAULT_LOG_LINES", () => {
+  it("is 50", () => {
+    expect(DEFAULT_LOG_LINES).toBe(50);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// readAllLines
+// ---------------------------------------------------------------------------
+
+describe("readAllLines", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "nerve-logs-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns empty array for nonexistent file", async () => {
+    const result = await readAllLines(join(tmpDir, "missing.log"));
+    expect(result).toHaveLength(0);
+  });
+
+  it("reads all lines from a file", async () => {
+    const logFile = join(tmpDir, "test.log");
+    writeFileSync(logFile, "line1\nline2\nline3\n");
+    const result = await readAllLines(logFile);
+    expect(result).toEqual(["line1", "line2", "line3"]);
+  });
+
+  it("handles file with no trailing newline", async () => {
+    const logFile = join(tmpDir, "test.log");
+    writeFileSync(logFile, "a\nb\nc");
+    const result = await readAllLines(logFile);
+    expect(result).toEqual(["a", "b", "c"]);
+  });
+
+  it("returns empty array for empty file", async () => {
+    const logFile = join(tmpDir, "empty.log");
+    writeFileSync(logFile, "");
+    const result = await readAllLines(logFile);
+    expect(result).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Integration: readAllLines + sliceLogs end-to-end
+// ---------------------------------------------------------------------------
+
+describe("readAllLines + sliceLogs integration", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "nerve-logs-int-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("tail-paginates a large log file correctly", async () => {
+    const logFile = join(tmpDir, "big.log");
+    const content = Array.from({ length: 120 }, (_, i) => `entry ${i + 1}`).join("\n");
+    writeFileSync(logFile, content);
+
+    const all = await readAllLines(logFile);
+    const page1 = sliceLogs(all, 0, 50); // last 50: lines 71-120
+    expect(page1.startLine).toBe(71);
+    expect(page1.endLine).toBe(120);
+    expect(page1.nextOffset).toBe(21); // max(1, 71-50)
+
+    const page2 = sliceLogs(all, page1.nextOffset!, 50); // lines 21-70
+    expect(page2.startLine).toBe(21);
+    expect(page2.endLine).toBe(70);
+    expect(page2.nextOffset).toBe(1); // max(1, 21-50) = 1
+
+    const page3 = sliceLogs(all, page2.nextOffset!, 50); // lines 1-50
+    expect(page3.startLine).toBe(1);
+    expect(page3.endLine).toBe(50);
+    expect(page3.nextOffset).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// logsCommand: negative offset validation
+// ---------------------------------------------------------------------------
+
+describe("logsCommand negative offset", () => {
+  let stderrOutput: string;
+  let exitCode: number | undefined;
+
+  beforeEach(() => {
+    stderrOutput = "";
+    exitCode = undefined;
+    vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
+      stderrOutput += typeof chunk === "string" ? chunk : chunk.toString();
+      return true;
+    });
+    vi.spyOn(process, "exit").mockImplementation((code?: number | string | null) => {
+      exitCode = typeof code === "number" ? code : 1;
+      throw new Error(`process.exit(${exitCode})`);
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("exits with code 1 and writes to stderr when offset is negative", async () => {
+    await expect(
+      logsCommand.run!({ args: { n: "50", offset: "-5", follow: false }, rawArgs: [], cmd: logsCommand as never }),
+    ).rejects.toThrow("process.exit(1)");
+    expect(exitCode).toBe(1);
+    expect(stderrOutput).toContain("--offset must be a non-negative integer");
+    expect(stderrOutput).toContain("-5");
+  });
+
+  it("exits with code 1 for offset=-1", async () => {
+    await expect(
+      logsCommand.run!({ args: { n: "10", offset: "-1", follow: false }, rawArgs: [], cmd: logsCommand as never }),
+    ).rejects.toThrow("process.exit(1)");
+    expect(exitCode).toBe(1);
+  });
+});

packages/cli/src/__tests__/sense-list.test.ts

@@ -0,0 +1,295 @@
+/**
+ * Tests for `nerve sense list` — formatting helpers and IPC round-trip.
+ *
+ * Covers:
+ *   - formatDuration helper
+ *   - formatSenseList output
+ *   - sensesFromConfig (static fallback from nerve.yaml)
+ *   - listSensesViaDaemon IPC round-trip via real Unix socket
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { listSensesViaDaemon } from "../daemon-client.js";
+import type { SenseInfo } from "../daemon-client.js";
+import { formatDuration, formatSenseList, sensesFromConfig } from "../commands/sense.js";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const SAMPLE_SENSES: SenseInfo[] = [
+  { name: "cpu-usage", group: "system", throttle: 5000, timeout: 3000, lastSignalTs: 1_700_000_000_000 },
+  { name: "disk-usage", group: "system", throttle: 30000, timeout: null, lastSignalTs: null },
+  { name: "active-tasks", group: "tasks", throttle: 10000, timeout: 30000, lastSignalTs: null },
+];
+
+// ---------------------------------------------------------------------------
+// formatDuration
+// ---------------------------------------------------------------------------
+
+describe("formatDuration", () => {
+  it("returns '—' for null", () => {
+    expect(formatDuration(null)).toBe("—");
+  });
+
+  it("formats sub-minute durations as seconds", () => {
+    expect(formatDuration(0)).toBe("0s");
+    expect(formatDuration(1000)).toBe("1s");
+    expect(formatDuration(59000)).toBe("59s");
+  });
+
+  it("formats minute-range durations as Xm Ys", () => {
+    expect(formatDuration(60000)).toBe("1m 0s");
+    expect(formatDuration(90000)).toBe("1m 30s");
+    expect(formatDuration(3599000)).toBe("59m 59s");
+  });
+
+  it("formats hour-range durations as Xh Ym", () => {
+    expect(formatDuration(3600000)).toBe("1h 0m");
+    expect(formatDuration(3660000)).toBe("1h 1m");
+    expect(formatDuration(7200000)).toBe("2h 0m");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatSenseList
+// ---------------------------------------------------------------------------
+
+describe("formatSenseList", () => {
+  it("returns empty message when no senses", () => {
+    const output = formatSenseList([]);
+    expect(output).toContain("No senses registered");
+  });
+
+  it("shows sense count in header", () => {
+    const output = formatSenseList(SAMPLE_SENSES);
+    expect(output).toContain("3");
+  });
+
+  it("shows each sense name", () => {
+    const output = formatSenseList(SAMPLE_SENSES);
+    expect(output).toContain("cpu-usage");
+    expect(output).toContain("disk-usage");
+    expect(output).toContain("active-tasks");
+  });
+
+  it("shows group for each sense", () => {
+    const output = formatSenseList(SAMPLE_SENSES);
+    expect(output).toContain("system");
+    expect(output).toContain("tasks");
+  });
+
+  it("shows throttle and timeout durations", () => {
+    const output = formatSenseList(SAMPLE_SENSES);
+    // cpu-usage: throttle=5s, timeout=3s
+    expect(output).toContain("5s");
+    expect(output).toContain("3s");
+    // disk-usage: timeout=null → '—'
+    expect(output).toContain("—");
+  });
+
+  it("shows '(never)' when lastSignalTs is null", () => {
+    const output = formatSenseList(SAMPLE_SENSES);
+    expect(output).toContain("(never)");
+  });
+
+  it("shows ISO timestamp when lastSignalTs is set", () => {
+    const output = formatSenseList(SAMPLE_SENSES);
+    // cpu-usage has lastSignalTs = 1_700_000_000_000
+    expect(output).toContain(new Date(1_700_000_000_000).toISOString());
+  });
+});
+
+// ---------------------------------------------------------------------------
+// sensesFromConfig — static fallback from nerve.yaml
+// ---------------------------------------------------------------------------
+
+describe("sensesFromConfig", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "nerve-sense-list-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns empty array when file does not exist", () => {
+    const result = sensesFromConfig(join(tmpDir, "nonexistent.yaml"));
+    expect(result).toEqual([]);
+  });
+
+  it("returns empty array when file has invalid YAML", () => {
+    const path = join(tmpDir, "nerve.yaml");
+    writeFileSync(path, "not: valid: yaml: :::");
+    const result = sensesFromConfig(path);
+    expect(result).toEqual([]);
+  });
+
+  it("parses senses from valid nerve.yaml", () => {
+    const path = join(tmpDir, "nerve.yaml");
+    writeFileSync(
+      path,
+      `
+senses:
+  cpu-usage:
+    group: system
+    throttle: 5s
+    timeout: 3s
+  disk-usage:
+    group: system
+    throttle: 30s
+reflexes: []
+`.trim(),
+    );
+    const result = sensesFromConfig(path);
+    expect(result).toHaveLength(2);
+    expect(result[0]).toMatchObject({ name: "cpu-usage", group: "system", lastSignalTs: null });
+    expect(result[1]).toMatchObject({ name: "disk-usage", group: "system", lastSignalTs: null });
+  });
+
+  it("always sets lastSignalTs to null (static fallback)", () => {
+    const path = join(tmpDir, "nerve.yaml");
+    writeFileSync(
+      path,
+      `
+senses:
+  my-sense:
+    group: default
+reflexes: []
+`.trim(),
+    );
+    const result = sensesFromConfig(path);
+    expect(result[0].lastSignalTs).toBeNull();
+  });
+
+  it("populates throttle and timeout from config", () => {
+    const path = join(tmpDir, "nerve.yaml");
+    writeFileSync(
+      path,
+      `
+senses:
+  my-sense:
+    group: default
+    throttle: 10s
+    timeout: 5s
+reflexes: []
+`.trim(),
+    );
+    const result = sensesFromConfig(path);
+    expect(result[0].throttle).toBe(10000);
+    expect(result[0].timeout).toBe(5000);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// listSensesViaDaemon — IPC round-trip via real Unix socket
+// ---------------------------------------------------------------------------
+
+describe("listSensesViaDaemon", () => {
+  let sockDir: string;
+  let sockPath: string;
+
+  beforeEach(() => {
+    sockDir = mkdtempSync(join(tmpdir(), "nerve-sense-list-ipc-"));
+    sockPath = join(sockDir, "nerve.sock");
+  });
+
+  afterEach(() => {
+    rmSync(sockDir, { recursive: true, force: true });
+  });
+
+  it("resolves with { ok: true, senses: [] } when daemon returns empty list", async () => {
+    const server = createServer((s) => {
+      s.on("data", (chunk: Buffer) => {
+        const line = chunk.toString("utf8").trim();
+        try {
+          const req = JSON.parse(line) as { type: string };
+          if (req.type === "list-senses") {
+            s.write(`${JSON.stringify({ ok: true, senses: [] })}\n`);
+          }
+        } catch {
+          // ignore
+        }
+      });
+    });
+    await new Promise<void>((r) => server.listen(sockPath, r));
+
+    try {
+      const result = await listSensesViaDaemon(sockPath);
+      expect(result).toEqual({ ok: true, senses: [] });
+    } finally {
+      await new Promise<void>((r) => server.close(() => r()));
+    }
+  });
+
+  it("resolves with populated senses array", async () => {
+    const senses: SenseInfo[] = [
+      { name: "cpu-usage", group: "system", throttle: 5000, timeout: 3000, lastSignalTs: 12345 },
+    ];
+    const server = createServer((s) => {
+      s.on("data", () => {
+        s.write(`${JSON.stringify({ ok: true, senses })}\n`);
+      });
+    });
+    await new Promise<void>((r) => server.listen(sockPath, r));
+
+    try {
+      const result = await listSensesViaDaemon(sockPath);
+      expect(result).toEqual({ ok: true, senses });
+    } finally {
+      await new Promise<void>((r) => server.close(() => r()));
+    }
+  });
+
+  it("resolves with { ok: false, error } when daemon returns an error", async () => {
+    const server = createServer((s) => {
+      s.on("data", () => {
+        s.write(`${JSON.stringify({ ok: false, error: "something went wrong" })}\n`);
+      });
+    });
+    await new Promise<void>((r) => server.listen(sockPath, r));
+
+    try {
+      const result = await listSensesViaDaemon(sockPath);
+      expect(result).toEqual({ ok: false, error: "something went wrong" });
+    } finally {
+      await new Promise<void>((r) => server.close(() => r()));
+    }
+  });
+
+  it("rejects when no daemon is listening on the socket", async () => {
+    await expect(listSensesViaDaemon(sockPath)).rejects.toThrow(/Cannot connect to daemon/);
+  });
+
+  it("sends a list-senses IPC message to the daemon", async () => {
+    const received: unknown[] = [];
+    const server = createServer((s) => {
+      s.on("data", (chunk: Buffer) => {
+        const line = chunk.toString("utf8").trim();
+        try {
+          received.push(JSON.parse(line));
+        } catch {
+          // ignore
+        }
+        s.write(`${JSON.stringify({ ok: true, senses: [] })}\n`);
+      });
+    });
+    await new Promise<void>((r) => server.listen(sockPath, r));
+
+    try {
+      await listSensesViaDaemon(sockPath);
+      expect(received).toHaveLength(1);
+      expect(received[0]).toMatchObject({ type: "list-senses" });
+    } finally {
+      await new Promise<void>((r) => server.close(() => r()));
+    }
+  });
+});

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

@@ -0,0 +1,110 @@
+/**
+ * Tests for the sense CLI helper — triggerSenseViaDaemon IPC round-trip.
+ *
+ * Uses a real Unix socket server to validate the full client/server
+ * protocol without requiring a running daemon process.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { triggerSenseViaDaemon } from "../daemon-client.js";
+
+// ---------------------------------------------------------------------------
+// Test setup
+// ---------------------------------------------------------------------------
+
+let sockDir: string;
+let sockPath: string;
+
+beforeEach(() => {
+  sockDir = mkdtempSync(join(tmpdir(), "nerve-sense-test-"));
+  sockPath = join(sockDir, "nerve.sock");
+});
+
+afterEach(() => {
+  rmSync(sockDir, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// triggerSenseViaDaemon — IPC round-trip via real Unix socket
+// ---------------------------------------------------------------------------
+
+describe("triggerSenseViaDaemon", () => {
+  it("resolves { ok: true } when daemon responds ok", async () => {
+    const received: unknown[] = [];
+
+    const server = createServer((s) => {
+      s.on("data", (chunk: Buffer) => {
+        const line = chunk.toString("utf8").trim();
+        try {
+          received.push(JSON.parse(line));
+        } catch {
+          // ignore
+        }
+        s.write(`${JSON.stringify({ ok: true })}\n`);
+      });
+    });
+    await new Promise<void>((r) => server.listen(sockPath, r));
+
+    try {
+      const result = await triggerSenseViaDaemon(sockPath, "cpu-usage");
+      expect(result).toEqual({ ok: true });
+      // Verify the correct IPC message was sent
+      expect(received).toHaveLength(1);
+      expect(received[0]).toMatchObject({ type: "trigger-sense", sense: "cpu-usage" });
+    } finally {
+      await new Promise<void>((r) => server.close(() => r()));
+    }
+  });
+
+  it("resolves { ok: false, error } when daemon rejects the sense", async () => {
+    const server = createServer((s) => {
+      s.on("data", () => {
+        s.write(`${JSON.stringify({ ok: false, error: 'Unknown sense: "no-such-sense"' })}\n`);
+      });
+    });
+    await new Promise<void>((r) => server.listen(sockPath, r));
+
+    try {
+      const result = await triggerSenseViaDaemon(sockPath, "no-such-sense");
+      expect(result).toEqual({ ok: false, error: 'Unknown sense: "no-such-sense"' });
+    } finally {
+      await new Promise<void>((r) => server.close(() => r()));
+    }
+  });
+
+  it("rejects when no daemon is listening on the socket", async () => {
+    await expect(triggerSenseViaDaemon(sockPath, "cpu-usage")).rejects.toThrow(
+      /Cannot connect to daemon/,
+    );
+  });
+
+  it("sends the sense name exactly as provided", async () => {
+    const received: unknown[] = [];
+
+    const server = createServer((s) => {
+      s.on("data", (chunk: Buffer) => {
+        const line = chunk.toString("utf8").trim();
+        try {
+          received.push(JSON.parse(line));
+        } catch {
+          // ignore
+        }
+        s.write(`${JSON.stringify({ ok: true })}\n`);
+      });
+    });
+    await new Promise<void>((r) => server.listen(sockPath, r));
+
+    try {
+      await triggerSenseViaDaemon(sockPath, "my-custom-sense");
+      expect(received[0]).toMatchObject({ sense: "my-custom-sense" });
+    } finally {
+      await new Promise<void>((r) => server.close(() => r()));
+    }
+  });
+});

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

@@ -0,0 +1,449 @@
+/**
+ * Tests for workflow CLI commands — pure logic helpers.
+ *
+ * Tests do NOT invoke the citty command handlers directly (they would call
+ * process.exit / process.stdout.write against a real terminal). Instead we
+ * test the exported pure helper functions that the command handlers delegate
+ * to. The helpers use real LogStore / SQLite via temp directories.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createLogStore } from "@uncaged/nerve-daemon";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  buildInspectOutput,
+  buildListOutput,
+  formatTs,
+  getAllWorkflowRuns,
+  parseIntArg,
+  statusIcon,
+} from "../commands/workflow.js";
+import { triggerWorkflowViaDaemon } from "../daemon-client.js";
+import type { LogStore, WorkflowRun } from "../daemon-types.js";
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+let tmpDir: string;
+let store: LogStore;
+
+function upsertRun(
+  runId: string,
+  workflow: string,
+  status: WorkflowRun["status"],
+  ts: number,
+): void {
+  store.upsertWorkflowRun(
+    { source: "workflow", type: status, refId: runId, payload: null, ts },
+    { runId, workflow, status, ts },
+  );
+}
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "nerve-cli-wf-test-"));
+  store = createLogStore(join(tmpDir, "data", "logs.db"));
+});
+
+afterEach(() => {
+  store.close();
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// formatTs
+// ---------------------------------------------------------------------------
+
+describe("formatTs", () => {
+  it("returns ISO 8601 string", () => {
+    const ts = new Date("2026-01-01T00:00:00.000Z").getTime();
+    expect(formatTs(ts)).toBe("2026-01-01T00:00:00.000Z");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// statusIcon
+// ---------------------------------------------------------------------------
+
+describe("statusIcon", () => {
+  it.each([
+    ["started", "▶"],
+    ["queued", "⏳"],
+    ["completed", "✅"],
+    ["failed", "❌"],
+    ["crashed", "💥"],
+    ["dropped", "🗑"],
+    ["interrupted", "⚠️"],
+  ] as const)("maps status=%s to icon=%s", (status, icon) => {
+    expect(statusIcon(status)).toBe(icon);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getAllWorkflowRuns
+// ---------------------------------------------------------------------------
+
+describe("getAllWorkflowRuns", () => {
+  it("returns empty array when no runs exist", () => {
+    expect(getAllWorkflowRuns(store, null)).toHaveLength(0);
+  });
+
+  it("returns all runs across statuses", () => {
+    upsertRun("r1", "cleanup", "completed", 1000);
+    upsertRun("r2", "cleanup", "started", 2000);
+    upsertRun("r3", "deploy", "failed", 1500);
+
+    const runs = getAllWorkflowRuns(store, null);
+    expect(runs).toHaveLength(3);
+  });
+
+  it("deduplicates runs by runId (latest state only)", () => {
+    upsertRun("r1", "cleanup", "started", 1000);
+    upsertRun("r1", "cleanup", "completed", 2000);
+
+    const runs = getAllWorkflowRuns(store, null);
+    expect(runs).toHaveLength(1);
+    expect(runs[0].status).toBe("completed");
+  });
+
+  it("filters by workflow name", () => {
+    upsertRun("r1", "cleanup", "completed", 1000);
+    upsertRun("r2", "deploy", "started", 2000);
+    upsertRun("r3", "cleanup", "failed", 1500);
+
+    const runs = getAllWorkflowRuns(store, "cleanup");
+    expect(runs).toHaveLength(2);
+    for (const r of runs) {
+      expect(r.workflow).toBe("cleanup");
+    }
+  });
+
+  it("sorts by ts descending (newest first)", () => {
+    upsertRun("r1", "cleanup", "completed", 1000);
+    upsertRun("r2", "cleanup", "started", 3000);
+    upsertRun("r3", "cleanup", "failed", 2000);
+
+    const runs = getAllWorkflowRuns(store, null);
+    expect(runs[0].ts).toBeGreaterThan(runs[1].ts);
+    expect(runs[1].ts).toBeGreaterThan(runs[2].ts);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildListOutput
+// ---------------------------------------------------------------------------
+
+describe("buildListOutput", () => {
+  function makeRun(
+    runId: string,
+    workflow: string,
+    status: WorkflowRun["status"],
+    ts: number,
+  ): WorkflowRun {
+    return { runId, workflow, status, ts };
+  }
+
+  it("returns empty message when no runs and --all=false", () => {
+    const { lines, paginationHint } = buildListOutput([], 0, 20, false, null);
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toContain("--all");
+    expect(paginationHint).toBeNull();
+  });
+
+  it("returns empty message when no runs and --all=true", () => {
+    const { lines, paginationHint } = buildListOutput([], 0, 20, true, null);
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).not.toContain("--all");
+    expect(paginationHint).toBeNull();
+  });
+
+  it("shows correct run count in header", () => {
+    const runs = [
+      makeRun("r1", "cleanup", "started", 1000),
+      makeRun("r2", "cleanup", "queued", 2000),
+    ];
+    const { lines } = buildListOutput(runs, 0, 20, false, null);
+    expect(lines[0]).toContain("2 of 2");
+  });
+
+  it("includes run details in lines", () => {
+    const runs = [makeRun("run-abc", "my-workflow", "started", 1000)];
+    const { lines } = buildListOutput(runs, 0, 20, false, null);
+    const combined = lines.join("");
+    expect(combined).toContain("run-abc");
+    expect(combined).toContain("my-workflow");
+    expect(combined).toContain("started");
+    expect(combined).toContain("▶");
+  });
+
+  it("paginates: shows only limit entries and provides hint", () => {
+    const runs = Array.from({ length: 5 }, (_, i) => makeRun(`r${i}`, "wf", "completed", i * 1000));
+    const { lines, paginationHint } = buildListOutput(runs, 0, 2, true, null);
+    // header + 2 run lines
+    expect(lines).toHaveLength(3);
+    expect(paginationHint).not.toBeNull();
+    expect(paginationHint).toContain("--offset 2");
+    expect(paginationHint).toContain("3 more");
+  });
+
+  it("pagination hint includes --all flag when set", () => {
+    const runs = Array.from({ length: 3 }, (_, i) => makeRun(`r${i}`, "wf", "completed", i * 1000));
+    const { paginationHint } = buildListOutput(runs, 0, 1, true, null);
+    expect(paginationHint).toContain("--all");
+  });
+
+  it("pagination hint includes --workflow filter when set", () => {
+    const runs = Array.from({ length: 3 }, (_, i) =>
+      makeRun(`r${i}`, "cleanup", "completed", i * 1000),
+    );
+    const { paginationHint } = buildListOutput(runs, 0, 1, false, "cleanup");
+    expect(paginationHint).toContain("--workflow cleanup");
+  });
+
+  it("no pagination hint when all entries fit on one page", () => {
+    const runs = [makeRun("r1", "wf", "started", 1000)];
+    const { paginationHint } = buildListOutput(runs, 0, 20, false, null);
+    expect(paginationHint).toBeNull();
+  });
+
+  it("respects offset for pagination", () => {
+    const runs = Array.from({ length: 5 }, (_, i) => makeRun(`r${i}`, "wf", "completed", i * 1000));
+    const { lines, paginationHint } = buildListOutput(runs, 2, 2, true, null);
+    // header + 2 run lines (offset=2, limit=2 gives items 2 and 3)
+    expect(lines).toHaveLength(3);
+    // 1 item remaining (index 4)
+    expect(paginationHint).toContain("1 more");
+    expect(paginationHint).toContain("--offset 4");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildInspectOutput
+// ---------------------------------------------------------------------------
+
+describe("buildInspectOutput", () => {
+  const baseRun: WorkflowRun = {
+    runId: "run-xyz",
+    workflow: "cleanup",
+    status: "completed",
+    ts: 1_700_000_000_000,
+  };
+
+  it("shows header with run details", () => {
+    const { header } = buildInspectOutput(baseRun, [], 0, 20);
+    const headerText = header.join("");
+    expect(headerText).toContain("run-xyz");
+    expect(headerText).toContain("cleanup");
+    expect(headerText).toContain("completed");
+  });
+
+  it("shows '(no events recorded)' when log is empty", () => {
+    const { eventLines } = buildInspectOutput(baseRun, [], 0, 20);
+    expect(eventLines.join("")).toContain("no events recorded");
+  });
+
+  it("shows event lines with type and ts", () => {
+    const logs = [{ ts: 1_700_000_001_000, type: "started", payload: null }];
+    const { eventLines } = buildInspectOutput(baseRun, logs, 0, 20);
+    const text = eventLines.join("");
+    expect(text).toContain("type=started");
+  });
+
+  it("truncates long payloads to 200 chars with ellipsis", () => {
+    const longPayload = "x".repeat(250);
+    const logs = [{ ts: 1000, type: "step_complete", payload: longPayload }];
+    const { eventLines } = buildInspectOutput(baseRun, logs, 0, 20);
+    const text = eventLines.join("");
+    expect(text).toContain("…");
+    expect(text).not.toContain("x".repeat(201));
+  });
+
+  it("shows short payloads in full", () => {
+    const logs = [{ ts: 1000, type: "step_complete", payload: '{"count":5}' }];
+    const { eventLines } = buildInspectOutput(baseRun, logs, 0, 20);
+    expect(eventLines.join("")).toContain('{"count":5}');
+  });
+
+  it("paginates events with a hint", () => {
+    const logs = Array.from({ length: 5 }, (_, i) => ({
+      ts: 1000 + i,
+      type: "step_complete",
+      payload: null,
+    }));
+    const { eventLines, paginationHint } = buildInspectOutput(baseRun, logs, 0, 2);
+    expect(eventLines).toHaveLength(2);
+    expect(paginationHint).toContain("3 more");
+    expect(paginationHint).toContain("--offset 2");
+    expect(paginationHint).toContain("run-xyz");
+  });
+
+  it("no pagination hint when all events fit on one page", () => {
+    const logs = [{ ts: 1000, type: "started", payload: null }];
+    const { paginationHint } = buildInspectOutput(baseRun, logs, 0, 20);
+    expect(paginationHint).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Integration: getAllWorkflowRuns + buildListOutput end-to-end with real store
+// ---------------------------------------------------------------------------
+
+describe("workflow list — integration with real store", () => {
+  it("lists active runs from the store", () => {
+    upsertRun("r1", "cleanup", "started", 1000);
+    upsertRun("r2", "cleanup", "queued", 2000);
+    upsertRun("r3", "cleanup", "completed", 3000);
+
+    // Active only (getActiveWorkflowRuns)
+    const activeRuns = store.getActiveWorkflowRuns();
+    const { lines } = buildListOutput(activeRuns, 0, 20, false, null);
+    const combined = lines.join("");
+    expect(combined).toContain("r1");
+    expect(combined).toContain("r2");
+    expect(combined).not.toContain("r3");
+  });
+
+  it("lists all runs with getAllWorkflowRuns", () => {
+    upsertRun("r1", "cleanup", "started", 1000);
+    upsertRun("r2", "cleanup", "completed", 2000);
+    upsertRun("r3", "cleanup", "failed", 3000);
+
+    const allRuns = getAllWorkflowRuns(store, null);
+    const { lines } = buildListOutput(allRuns, 0, 20, true, null);
+    const combined = lines.join("");
+    expect(combined).toContain("r1");
+    expect(combined).toContain("r2");
+    expect(combined).toContain("r3");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseIntArg
+// ---------------------------------------------------------------------------
+
+describe("parseIntArg", () => {
+  it("parses a valid integer string", () => {
+    expect(parseIntArg("5", 20)).toBe(5);
+  });
+
+  it("returns fallback for non-numeric string", () => {
+    expect(parseIntArg("abc", 20)).toBe(20);
+  });
+
+  it("returns the value for '0' (not fallback)", () => {
+    expect(parseIntArg("0", 20)).toBe(0);
+  });
+
+  it("returns fallback for empty string", () => {
+    expect(parseIntArg("", 20)).toBe(20);
+  });
+
+  it("parses negative integers", () => {
+    expect(parseIntArg("-3", 20)).toBe(-3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getAllWorkflowRuns — backed by real store's SQL query
+// ---------------------------------------------------------------------------
+
+describe("getAllWorkflowRuns — uses store.getAllWorkflowRuns SQL path", () => {
+  it("returns all runs regardless of status", () => {
+    upsertRun("r1", "deploy", "completed", 1000);
+    upsertRun("r2", "deploy", "failed", 2000);
+    upsertRun("r3", "deploy", "started", 3000);
+    upsertRun("r4", "deploy", "queued", 4000);
+    upsertRun("r5", "deploy", "crashed", 5000);
+    upsertRun("r6", "deploy", "dropped", 6000);
+    upsertRun("r7", "deploy", "interrupted", 7000);
+
+    const runs = getAllWorkflowRuns(store, null);
+    expect(runs).toHaveLength(7);
+  });
+
+  it("returns runs sorted by ts descending (newest first)", () => {
+    upsertRun("r1", "deploy", "completed", 1000);
+    upsertRun("r2", "deploy", "completed", 3000);
+    upsertRun("r3", "deploy", "completed", 2000);
+
+    const runs = getAllWorkflowRuns(store, null);
+    expect(runs[0].ts).toBe(3000);
+    expect(runs[1].ts).toBe(2000);
+    expect(runs[2].ts).toBe(1000);
+  });
+
+  it("filters by workflow name", () => {
+    upsertRun("r1", "alpha", "completed", 1000);
+    upsertRun("r2", "beta", "completed", 2000);
+    upsertRun("r3", "alpha", "failed", 3000);
+
+    const runs = getAllWorkflowRuns(store, "alpha");
+    expect(runs).toHaveLength(2);
+    for (const r of runs) expect(r.workflow).toBe("alpha");
+  });
+
+  it("returns empty array when store has no runs", () => {
+    expect(getAllWorkflowRuns(store, null)).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// triggerWorkflowViaDaemon — IPC round-trip via real Unix socket
+// ---------------------------------------------------------------------------
+
+describe("triggerWorkflowViaDaemon", () => {
+  let sockDir: string;
+  let sockPath: string;
+
+  beforeEach(() => {
+    sockDir = mkdtempSync(join(tmpdir(), "nerve-ipc-test-"));
+    sockPath = join(sockDir, "nerve.sock");
+  });
+
+  afterEach(() => {
+    rmSync(sockDir, { recursive: true, force: true });
+  });
+
+  it("resolves { ok: true } when server responds ok", async () => {
+    const server = createServer((s) => {
+      s.on("data", () => {
+        s.write(`${JSON.stringify({ ok: true })}\n`);
+      });
+    });
+    await new Promise<void>((r) => server.listen(sockPath, r));
+
+    try {
+      const result = await triggerWorkflowViaDaemon(sockPath, "my-workflow", {});
+      expect(result).toEqual({ ok: true });
+    } finally {
+      await new Promise<void>((r) => server.close(() => r()));
+    }
+  });
+
+  it("resolves { ok: false, error } when server responds with error", async () => {
+    const server = createServer((s) => {
+      s.on("data", () => {
+        s.write(`${JSON.stringify({ ok: false, error: "unknown workflow" })}\n`);
+      });
+    });
+    await new Promise<void>((r) => server.listen(sockPath, r));
+
+    try {
+      const result = await triggerWorkflowViaDaemon(sockPath, "missing", {});
+      expect(result).toEqual({ ok: false, error: "unknown workflow" });
+    } finally {
+      await new Promise<void>((r) => server.close(() => r()));
+    }
+  });
+
+  it("rejects when no daemon is listening on the socket", async () => {
+    await expect(triggerWorkflowViaDaemon(sockPath, "my-workflow", {})).rejects.toThrow(
+      /Cannot connect to daemon/,
+    );
+  });
+});

packages/cli/src/cli.ts

@@ -1,12 +1,14 @@
-#!/usr/bin/env node
-
 import { defineCommand, runMain } from "citty";
 
 import { initCommand } from "./commands/init.js";
+import { logsCommand } from "./commands/logs.js";
+import { senseCommand } from "./commands/sense.js";
 import { startCommand } from "./commands/start.js";
 import { statusCommand } from "./commands/status.js";
 import { stopCommand } from "./commands/stop.js";
+import { storeCommand } from "./commands/store.js";
 import { validateCommand } from "./commands/validate.js";
+import { workflowCommand } from "./commands/workflow.js";
 
 const main = defineCommand({
   meta: {
@@ -18,7 +20,11 @@ const main = defineCommand({
     start: startCommand,
     stop: stopCommand,
     status: statusCommand,
+    logs: logsCommand,
     validate: validateCommand,
+    sense: senseCommand,
+    store: storeCommand,
+    workflow: workflowCommand,
   },
 });
 

packages/cli/src/commands/init.ts

@@ -26,10 +26,14 @@ const PACKAGE_JSON = `{
   "type": "module",
   "dependencies": {
     "@uncaged/nerve-core": "latest",
+    "@uncaged/nerve-daemon": "latest",
     "drizzle-orm": "latest"
   },
   "devDependencies": {
     "drizzle-kit": "latest"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["better-sqlite3", "esbuild"]
   }
 }
 `;
@@ -97,7 +101,7 @@ async function runCommand(cmd: string, args: string[], cwd: string): Promise<voi
   });
 }
 
-async function detectPackageManager(): Promise<{ cmd: string; args: string[] }> {
+async function detectPackageManager(): Promise<{ cmd: string; installArgs: string[] }> {
   const { execFile } = await import("node:child_process");
   const { promisify } = await import("node:util");
   const execFileAsync = promisify(execFile);
@@ -105,19 +109,103 @@ async function detectPackageManager(): Promise<{ cmd: string; args: string[] }>
   for (const pm of ["pnpm", "yarn", "npm"]) {
     try {
       await execFileAsync(pm, ["--version"]);
-      const args = pm === "pnpm" ? ["install", "--no-cache"] : ["install"];
-      return { cmd: pm, args };
+      const installArgs = pm === "pnpm" ? ["install", "--no-cache"] : ["install"];
+      return { cmd: pm, installArgs };
     } catch {
       // not available, try next
     }
   }
-  return { cmd: "npm", args: ["install"] };
+  return { cmd: "npm", installArgs: ["install"] };
 }
 
-export const initCommand = defineCommand({
+export const WORKFLOW_NAME_RE = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/;
+
+export function validateWorkflowName(name: string): string | null {
+  if (name.length === 0) return "Workflow name must not be empty.";
+  if (name.length > 64) return "Workflow name must be 64 characters or fewer.";
+  if (!WORKFLOW_NAME_RE.test(name))
+    return "Workflow name must contain only lowercase letters, digits, and hyphens, and must not start or end with a hyphen.";
+  return null;
+}
+
+export function buildWorkflowTemplate(name: string): string {
+  return `import type { WorkflowDefinition } from "@uncaged/nerve-daemon";
+
+const workflow: WorkflowDefinition = {
+  roles: {
+    main: {
+      async execute(prompt, ctx) {
+        ctx.log("${name} started");
+        // TODO: implement your role logic here
+        return { type: "done" };
+      },
+    },
+  },
+
+  moderate(thread, event) {
+    if (event.type === "thread_start") {
+      return { role: "main", prompt: {} };
+    }
+    return null; // workflow complete
+  },
+};
+
+export default workflow;
+`;
+}
+
+const initWorkflowCommand = defineCommand({
   meta: {
-    name: "init",
-    description: "Initialize the ~/.uncaged-nerve/ workspace",
+    name: "workflow",
+    description: "Scaffold a new workflow template in ~/.uncaged-nerve/workflows/<name>/",
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Workflow name (must match the key in nerve.yaml workflows section)",
+    },
+    force: {
+      type: "boolean",
+      description: "Overwrite if the workflow directory already exists",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const nerveRoot = getNerveRoot();
+    const workflowDir = join(nerveRoot, "workflows", args.name);
+
+    const nameError = validateWorkflowName(args.name);
+    if (nameError !== null) {
+      process.stderr.write(`❌ Invalid workflow name: ${nameError}\n`);
+      process.exit(1);
+    }
+
+    if (existsSync(workflowDir) && !args.force) {
+      process.stderr.write(
+        `⚠️ Workflow "${args.name}" already exists at ${workflowDir}. Use --force to overwrite.\n`,
+      );
+      process.exit(1);
+    }
+
+    mkdirSync(workflowDir, { recursive: true });
+    writeFile(join(workflowDir, "index.ts"), buildWorkflowTemplate(args.name));
+
+    process.stdout.write(`✅ Workflow scaffolded: ${workflowDir}/index.ts\n`);
+    process.stdout.write("\n💡 Next steps:\n");
+    process.stdout.write("   1. Add to nerve.yaml:\n");
+    process.stdout.write("         workflows:\n");
+    process.stdout.write(`           ${args.name}:\n`);
+    process.stdout.write("             concurrency: 1\n");
+    process.stdout.write("             overflow: drop\n");
+    process.stdout.write(`   2. Edit ${workflowDir}/index.ts to implement your roles.\n`);
+    process.stdout.write("   3. Run `nerve start` to launch the daemon.\n");
+  },
+});
+
+const initWorkspaceCommand = defineCommand({
+  meta: {
+    name: "workspace",
+    description: "Initialize the ~/.uncaged-nerve/ workspace (default)",
   },
   args: {
     force: {
@@ -127,45 +215,82 @@ export const initCommand = defineCommand({
     },
   },
   async run({ args }) {
-    const nerveRoot = getNerveRoot();
-
-    if (existsSync(nerveRoot) && !args.force) {
-      process.stderr.write("⚠️ ~/.uncaged-nerve/ already exists. Use --force to reinitialize.\n");
-      process.exit(1);
-    }
-
-    mkdirSync(join(nerveRoot, "data"), { recursive: true });
-    mkdirSync(join(nerveRoot, "data", "senses"), { recursive: true });
-    mkdirSync(join(nerveRoot, "senses", "cpu-usage", "migrations"), { recursive: true });
-
-    writeFile(join(nerveRoot, "nerve.yaml"), NERVE_YAML);
-    writeFile(join(nerveRoot, "package.json"), PACKAGE_JSON);
-    writeFile(join(nerveRoot, ".gitignore"), GITIGNORE);
-    writeFile(join(nerveRoot, "senses", "cpu-usage", "schema.ts"), CPU_SCHEMA_TS);
-    writeFile(join(nerveRoot, "senses", "cpu-usage", "index.js"), CPU_INDEX_JS);
-    writeFile(
-      join(nerveRoot, "senses", "cpu-usage", "migrations", "0001_init.sql"),
-      CPU_MIGRATION_SQL,
-    );
-
-    process.stdout.write("Installing dependencies…\n");
-    try {
-      const { cmd, args } = await detectPackageManager();
-      await runCommand(cmd, args, nerveRoot);
-    } catch {
-      process.stdout.write("⚠️ Install failed — you may need to install dependencies manually.\n");
-    }
-
-    if (!existsSync(join(nerveRoot, ".git"))) {
-      try {
-        await runCommand("git", ["init"], nerveRoot);
-      } catch {
-        process.stdout.write("⚠️ git init failed — skipping.\n");
-      }
-    }
-
-    process.stdout.write(
-      "✅ Workspace created at ~/.uncaged-nerve/\n   1 example sense: cpu-usage\n   Run `nerve start` to launch the daemon.\n",
-    );
+    await runInitWorkspace(args.force);
+  },
+});
+
+async function runInitWorkspace(force: boolean): Promise<void> {
+  const nerveRoot = getNerveRoot();
+
+  if (existsSync(nerveRoot) && !force) {
+    process.stderr.write("⚠️ ~/.uncaged-nerve/ already exists. Use --force to reinitialize.\n");
+    process.exit(1);
+  }
+
+  mkdirSync(join(nerveRoot, "data"), { recursive: true });
+  mkdirSync(join(nerveRoot, "data", "senses"), { recursive: true });
+  mkdirSync(join(nerveRoot, "senses", "cpu-usage", "migrations"), { recursive: true });
+
+  writeFile(join(nerveRoot, "nerve.yaml"), NERVE_YAML);
+  writeFile(join(nerveRoot, "package.json"), PACKAGE_JSON);
+  writeFile(join(nerveRoot, ".gitignore"), GITIGNORE);
+  writeFile(join(nerveRoot, "senses", "cpu-usage", "schema.ts"), CPU_SCHEMA_TS);
+  writeFile(join(nerveRoot, "senses", "cpu-usage", "index.js"), CPU_INDEX_JS);
+  writeFile(
+    join(nerveRoot, "senses", "cpu-usage", "migrations", "0001_init.sql"),
+    CPU_MIGRATION_SQL,
+  );
+
+  process.stdout.write("Installing dependencies…\n");
+  try {
+    const { cmd, installArgs } = await detectPackageManager();
+    await runCommand(cmd, installArgs, nerveRoot);
+
+    process.stdout.write("Rebuilding native module better-sqlite3…\n");
+    try {
+      await runCommand(cmd, ["rebuild", "better-sqlite3"], nerveRoot);
+    } catch {
+      process.stdout.write(
+        "⚠️ rebuild better-sqlite3 failed — if the daemon fails to start, reinstall from the workspace directory.\n",
+      );
+    }
+  } catch {
+    process.stdout.write("⚠️ Install failed — you may need to install dependencies manually.\n");
+  }
+
+  if (!existsSync(join(nerveRoot, ".git"))) {
+    try {
+      await runCommand("git", ["init"], nerveRoot);
+      await runCommand("git", ["add", "."], nerveRoot);
+      await runCommand("git", ["commit", "-m", "Initial nerve workspace"], nerveRoot);
+    } catch {
+      process.stdout.write("⚠️ git init failed — skipping.\n");
+    }
+  }
+
+  process.stdout.write(
+    "✅ Workspace created at ~/.uncaged-nerve/\n   1 example sense: cpu-usage\n   Run `nerve start` to launch the daemon.\n",
+  );
+}
+
+export const initCommand = defineCommand({
+  meta: {
+    name: "init",
+    description:
+      "Initialize workspace (nerve init) or scaffold templates (nerve init workflow <name>)",
+  },
+  args: {
+    force: {
+      type: "boolean",
+      description: "Reinitialize even if workspace already exists (preserves data/)",
+      default: false,
+    },
+  },
+  subCommands: {
+    workflow: initWorkflowCommand,
+    workspace: initWorkspaceCommand,
+  },
+  async run({ args }) {
+    await runInitWorkspace(args.force);
   },
 });

packages/cli/src/commands/logs.ts

@@ -0,0 +1,197 @@
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { createInterface } from "node:readline";
+
+import { defineCommand } from "citty";
+
+import { getLogPath } from "../workspace.js";
+
+export const DEFAULT_LOG_LINES = 50;
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Read all lines from a file. Returns empty array if file does not exist.
+ *
+ * TODO: For tail mode (offset=0), avoid reading the whole file into memory by
+ * seeking to the last N bytes via createReadStream({ start: max(0, size - CHUNK) }).
+ */
+export async function readAllLines(filePath: string): Promise<string[]> {
+  if (!existsSync(filePath)) return [];
+  const lines: string[] = [];
+  const rl = createInterface({
+    input: createReadStream(filePath, { encoding: "utf8" }),
+    crlfDelay: Number.POSITIVE_INFINITY,
+  });
+  for await (const line of rl) {
+    lines.push(line);
+  }
+  return lines;
+}
+
+/**
+ * Slice a log line array respecting offset + limit semantics.
+ *
+ * When offset is 0 the function returns the *last* `limit` lines (tail mode).
+ * When offset > 0 it is treated as a 1-based line number and the slice starts
+ * there (for pagination of earlier pages from the tail).
+ *
+ * Returns the selected lines plus metadata used to build the footer.
+ */
+export type LogSlice = {
+  lines: string[];
+  total: number;
+  startLine: number; // 1-based, inclusive
+  endLine: number; // 1-based, inclusive
+  nextOffset: number | null; // null when no previous page exists
+};
+
+export function sliceLogs(allLines: string[], offset: number, limit: number): LogSlice {
+  const total = allLines.length;
+
+  if (total === 0) {
+    return { lines: [], total: 0, startLine: 0, endLine: 0, nextOffset: null };
+  }
+
+  let start: number;
+  if (offset === 0) {
+    // Tail mode: last `limit` lines
+    start = Math.max(0, total - limit);
+  } else {
+    // offset is 1-based line number
+    start = Math.max(0, offset - 1);
+  }
+
+  const end = Math.min(start + limit, total);
+  const lines = allLines.slice(start, end);
+
+  const startLine = start + 1;
+  const endLine = end;
+
+  // nextOffset points to lines *before* current slice (earlier in file)
+  const nextOffset = start > 0 ? Math.max(1, startLine - limit) : null;
+
+  return { lines, total, startLine, endLine, nextOffset };
+}
+
+/**
+ * Build the footer string shown after the log lines.
+ */
+export function buildLogFooter(slice: LogSlice, nArg: number, logPath: string): string {
+  if (slice.total === 0) {
+    return "📭 Log file is empty.\n";
+  }
+
+  const rangeStr = `lines ${slice.startLine}-${slice.endLine} of ${slice.total}`;
+  let footer = `\n📄 ${rangeStr} | ${logPath}\n`;
+
+  if (slice.nextOffset !== null) {
+    footer += `⏩ Earlier lines available. Fetch previous page:\n`;
+    footer += `   nerve logs --offset ${slice.nextOffset} -n ${nArg}\n`;
+  }
+
+  return footer;
+}
+
+// ---------------------------------------------------------------------------
+// nerve logs
+// ---------------------------------------------------------------------------
+
+export const logsCommand = defineCommand({
+  meta: {
+    name: "logs",
+    description: "Show daemon log output",
+  },
+  args: {
+    n: {
+      type: "string",
+      description: `Number of lines to show (default: ${DEFAULT_LOG_LINES})`,
+      default: String(DEFAULT_LOG_LINES),
+    },
+    offset: {
+      type: "string",
+      description: "Start from line N (1-based, for pagination)",
+      default: "0",
+    },
+    follow: {
+      type: "boolean",
+      alias: "f",
+      description: "Stream new log lines in real time",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const logPath = getLogPath();
+    const nLines = Math.max(1, Number.parseInt(args.n, 10) || DEFAULT_LOG_LINES);
+    const rawOffset = Number.parseInt(args.offset, 10) || 0;
+
+    if (rawOffset < 0) {
+      process.stderr.write(`❌ --offset must be a non-negative integer, got: ${args.offset}\n`);
+      process.exit(1);
+    }
+
+    const offset = rawOffset;
+
+    if (!existsSync(logPath)) {
+      process.stderr.write(`❌ Log file not found: ${logPath}\n`);
+      process.stderr.write("   Has the daemon been started? Try: nerve start\n");
+      process.exit(1);
+    }
+
+    if (args.follow) {
+      await followLog(logPath, nLines);
+      return;
+    }
+
+    const allLines = await readAllLines(logPath);
+    const slice = sliceLogs(allLines, offset, nLines);
+
+    for (const line of slice.lines) {
+      process.stdout.write(`${line}\n`);
+    }
+
+    process.stdout.write(buildLogFooter(slice, nLines, logPath));
+  },
+});
+
+/**
+ * Stream new lines from a log file as they are appended.
+ * Shows the last `tailLines` lines first, then watches for new content.
+ */
+async function followLog(logPath: string, tailLines: number): Promise<void> {
+  const allLines = await readAllLines(logPath);
+  const initial = allLines.slice(Math.max(0, allLines.length - tailLines));
+  for (const line of initial) {
+    process.stdout.write(`${line}\n`);
+  }
+
+  let size = statSync(logPath).size;
+
+  process.stdout.write(`\n👁  Following ${logPath} — press Ctrl+C to stop\n`);
+
+  let stopped = false;
+  process.once("SIGINT", () => {
+    stopped = true;
+  });
+
+  while (!stopped) {
+    await sleep(300);
+    if (stopped) break;
+    try {
+      const newSize = statSync(logPath).size;
+      if (newSize < size) {
+        // Log rotation: file was truncated or replaced, read from the beginning
+        size = 0;
+      }
+      if (newSize <= size) continue;
+
+      const stream = createReadStream(logPath, { start: size, encoding: "utf8" });
+      const rl = createInterface({ input: stream, crlfDelay: Number.POSITIVE_INFINITY });
+      for await (const line of rl) {
+        process.stdout.write(`${line}\n`);
+      }
+      size = newSize;
+    } catch {
+      stopped = true;
+    }
+  }
+}

packages/cli/src/commands/sense.ts

@@ -0,0 +1,157 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parseNerveConfig } from "@uncaged/nerve-core";
+import { defineCommand } from "citty";
+
+import { listSensesViaDaemon, triggerSenseViaDaemon } from "../daemon-client.js";
+import type { SenseInfo } from "../daemon-client.js";
+import { getNerveRoot, getSocketPath, isRunning } from "../workspace.js";
+
+// ---------------------------------------------------------------------------
+// Formatting helpers (exported for tests)
+// ---------------------------------------------------------------------------
+
+export function formatDuration(ms: number | null): string {
+  if (ms === null) return "—";
+  const totalSeconds = Math.floor(ms / 1000);
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (minutes < 60) return `${minutes}m ${seconds}s`;
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return `${hours}h ${remainingMinutes}m`;
+}
+
+export function formatSenseList(senses: SenseInfo[]): string {
+  if (senses.length === 0) {
+    return "📭 No senses registered in nerve.yaml.\n";
+  }
+
+  const lines: string[] = [`📡 Registered senses (${senses.length}):\n`];
+  for (const s of senses) {
+    lines.push(`\n  ${s.name}\n`);
+    lines.push(`    group:    ${s.group}\n`);
+    lines.push(`    throttle: ${formatDuration(s.throttle)}\n`);
+    lines.push(`    timeout:  ${formatDuration(s.timeout)}\n`);
+    const lastSignal =
+      s.lastSignalTs !== null ? new Date(s.lastSignalTs).toISOString() : "(never)";
+    lines.push(`    last signal: ${lastSignal}\n`);
+  }
+  return lines.join("");
+}
+
+/** Build a SenseInfo list from nerve.yaml when daemon is not running. */
+export function sensesFromConfig(configPath: string): SenseInfo[] {
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, "utf8");
+  } catch {
+    return [];
+  }
+  const result = parseNerveConfig(raw);
+  if (!result.ok) return [];
+  return Object.entries(result.value.senses).map(([name, cfg]) => ({
+    name,
+    group: cfg.group,
+    throttle: cfg.throttle,
+    timeout: cfg.timeout,
+    lastSignalTs: null,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// nerve sense list
+// ---------------------------------------------------------------------------
+
+const senseListCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "List all registered senses and their status",
+  },
+  async run() {
+    if (!isRunning()) {
+      // Daemon not running — show static info from nerve.yaml
+      process.stderr.write(
+        "⚠️  Daemon is not running — showing static config only (no last signal time).\n\n",
+      );
+      const configPath = join(getNerveRoot(), "nerve.yaml");
+      const senses = sensesFromConfig(configPath);
+      process.stdout.write(formatSenseList(senses));
+      return;
+    }
+
+    const socketPath = getSocketPath();
+    let response: { ok: true; senses: SenseInfo[] } | { ok: false; error: string };
+    try {
+      response = await listSensesViaDaemon(socketPath);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(`❌ Failed to contact daemon: ${msg}\n`);
+      process.exit(1);
+    }
+
+    if (!response.ok) {
+      process.stderr.write(`❌ Daemon error: ${response.error}\n`);
+      process.exit(1);
+    }
+
+    process.stdout.write(formatSenseList(response.senses));
+  },
+});
+
+// ---------------------------------------------------------------------------
+// nerve sense trigger <name>
+// ---------------------------------------------------------------------------
+
+const senseTriggerCommand = defineCommand({
+  meta: {
+    name: "trigger",
+    description: "Manually trigger a sense compute by sending an IPC message to the running daemon",
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "The sense name to trigger",
+    },
+  },
+  async run({ args }) {
+    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 };
+    try {
+      response = await triggerSenseViaDaemon(socketPath, args.name);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(`❌ Failed to contact daemon: ${msg}\n`);
+      process.exit(1);
+    }
+
+    if (!response.ok) {
+      process.stderr.write(`❌ Daemon rejected trigger: ${response.error}\n`);
+      process.exit(1);
+    }
+
+    process.stdout.write(`✅ Triggered sense "${args.name}" via daemon.\n`);
+  },
+});
+
+// ---------------------------------------------------------------------------
+// nerve sense (parent command)
+// ---------------------------------------------------------------------------
+
+export const senseCommand = defineCommand({
+  meta: {
+    name: "sense",
+    description: "Interact with sense computes",
+  },
+  subCommands: {
+    list: senseListCommand,
+    trigger: senseTriggerCommand,
+  },
+});

packages/cli/src/commands/start.ts

@@ -1,78 +1,64 @@
-import { createWriteStream } from "node:fs";
-import { readFileSync } from "node:fs";
+import { createWriteStream, existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { parseNerveConfig } from "@uncaged/nerve-core";
-import { createKernel } from "@uncaged/nerve-daemon";
 import { defineCommand } from "citty";
 
-import { getLogPath, getNerveRoot, isRunning, readPidFile, writePidFile } from "../workspace.js";
+import { runForegroundKernelSession } from "../run-foreground-kernel.js";
+import { loadDaemonModule } from "../workspace-daemon.js";
+import {
+  getLogPath,
+  getNerveRoot,
+  isRunning,
+  readPidFile,
+  removePidFile,
+  writePidFile,
+} from "../workspace.js";
 
-function readConfig(nerveRoot: string): ReturnType<typeof parseNerveConfig> {
-  const configPath = join(nerveRoot, "nerve.yaml");
-  let raw: string;
-  try {
-    raw = readFileSync(configPath, "utf8");
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    return { ok: false, error: new Error(`❌ Cannot read ${configPath}: ${msg}`) };
+function waitForSocket(socketPath: string, timeoutMs = 5000, intervalMs = 200): Promise<boolean> {
+  return new Promise((resolve) => {
+    const deadline = Date.now() + timeoutMs;
+    const check = (): void => {
+      if (existsSync(socketPath)) {
+        resolve(true);
+      } else if (Date.now() >= deadline) {
+        resolve(false);
+      } else {
+        setTimeout(check, intervalMs);
+      }
+    };
+    check();
+  });
+}
+
+/** Path to the CLI entry script (used to locate dist/ next to bundled assets). */
+function cliEntryScript(): string {
+  const here = fileURLToPath(import.meta.url);
+  const ext = here.endsWith(".ts") ? ".ts" : ".js";
+  const candidates = [join(dirname(here), `cli${ext}`), join(dirname(here), "..", `cli${ext}`)];
+  const cliPath = candidates.find((p) => existsSync(p));
+  if (!cliPath) {
+    throw new Error(`CLI entry not found (searched: ${candidates.join(", ")})`);
   }
-  return parseNerveConfig(raw);
+  return cliPath;
+}
+
+function daemonBootstrapScript(): string {
+  const cliPath = cliEntryScript();
+  const dir = dirname(cliPath);
+  const bootstrapJs = join(dir, "daemon-bootstrap.js");
+  if (existsSync(bootstrapJs)) {
+    return bootstrapJs;
+  }
+  throw new Error(
+    `daemon-bootstrap.js not found next to CLI at ${bootstrapJs}. Build the CLI package (e.g. \`pnpm --filter @uncaged/nerve-cli build\`) before using background mode (\`nerve start -d\`).`,
+  );
 }
 
 async function runForeground(nerveRoot: string): Promise<void> {
-  const configResult = readConfig(nerveRoot);
-  if (!configResult.ok) {
-    process.stderr.write(`${configResult.error.message}\n`);
-    process.exit(1);
-  }
-
-  const config = configResult.value;
-  const kernel = createKernel(config, nerveRoot);
-
-  const senseNames = Object.keys(config.senses);
-  const groups = [...kernel.groups];
-
-  process.stdout.write(
-    `✅ Nerve starting — ${senseNames.length} sense(s), ${groups.length} group(s)\n`,
-  );
-  for (const group of groups) {
-    const groupSenses = Object.entries(config.senses)
-      .filter(([, sc]) => sc.group === group)
-      .map(([name]) => name);
-    process.stdout.write(`   group "${group}": ${groupSenses.join(", ")}\n`);
-  }
-  process.stdout.write("   Press Ctrl+C to stop.\n");
-
-  let shuttingDown = false;
-
-  async function shutdown(): Promise<void> {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    process.stdout.write("\n[nerve] Shutting down…\n");
-    await kernel.stop();
-    process.exit(0);
-  }
-
-  process.on("SIGINT", () => {
-    shutdown().catch((e: unknown) => {
-      const msg = e instanceof Error ? e.message : String(e);
-      process.stderr.write(`[nerve] Shutdown error: ${msg}\n`);
-      process.exit(1);
-    });
-  });
-
-  process.on("SIGTERM", () => {
-    shutdown().catch((e: unknown) => {
-      const msg = e instanceof Error ? e.message : String(e);
-      process.stderr.write(`[nerve] Shutdown error: ${msg}\n`);
-      process.exit(1);
-    });
-  });
-
-  await kernel.ready;
+  const { createKernel } = await loadDaemonModule(nerveRoot);
+  await runForegroundKernelSession(nerveRoot, createKernel);
 }
 
 async function runDaemon(nerveRoot: string): Promise<void> {
@@ -82,12 +68,6 @@ async function runDaemon(nerveRoot: string): Promise<void> {
     process.exit(1);
   }
 
-  const configResult = readConfig(nerveRoot);
-  if (!configResult.ok) {
-    process.stderr.write(`${configResult.error.message}\n`);
-    process.exit(1);
-  }
-
   const logPath = getLogPath();
   await mkdir(join(nerveRoot, "logs"), { recursive: true });
 
@@ -98,12 +78,13 @@ async function runDaemon(nerveRoot: string): Promise<void> {
     else resolve();
   });
 
-  const selfPath = fileURLToPath(import.meta.url);
+  const bootstrapPath = daemonBootstrapScript();
 
-  const child = spawn(process.execPath, [selfPath, "start"], {
+  const child = spawn(process.execPath, [bootstrapPath], {
     detached: true,
     stdio: ["ignore", logStream.fd, logStream.fd],
-    env: { ...process.env, NERVE_DAEMON_MODE: "1" },
+    env: { ...process.env, NERVE_ROOT: nerveRoot },
+    cwd: nerveRoot,
   });
 
   child.unref();
@@ -115,6 +96,18 @@ async function runDaemon(nerveRoot: string): Promise<void> {
   }
 
   writePidFile(pid);
+
+  const { getSocketPath } = await import("../workspace.js");
+  const ready = await waitForSocket(getSocketPath(), 5000);
+
+  if (!ready || !isRunning()) {
+    removePidFile();
+    process.stderr.write(
+      `❌ Daemon process exited shortly after start. Check logs at:\n   ${logPath}\n`,
+    );
+    process.exit(1);
+  }
+
   process.stdout.write(`✅ Nerve daemon started (pid ${pid}).\n`);
   process.stdout.write(`   Logs: ${logPath}\n`);
   process.stdout.write("   Run `nerve stop` to stop.\n");

packages/cli/src/commands/store.ts

@@ -0,0 +1,70 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { defineCommand } from "citty";
+
+import { loadDaemonModule } from "../workspace-daemon.js";
+import { getNerveRoot } from "../workspace.js";
+
+// ---------------------------------------------------------------------------
+// nerve store archive
+// ---------------------------------------------------------------------------
+
+const storeArchiveCommand = defineCommand({
+  meta: {
+    name: "archive",
+    description:
+      "Export logs older than 30 days from logs.db to data/archive/logs/YYYY-MM-DD.jsonl and delete those rows (RFC-001 §5.4)",
+  },
+  args: {
+    vacuum: {
+      type: "boolean",
+      description: "Run SQLite VACUUM after archiving",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const nerveRoot = getNerveRoot();
+    const dbPath = join(nerveRoot, "data", "logs.db");
+    if (!existsSync(dbPath)) {
+      process.stderr.write("❌ No data/logs.db found — start the daemon at least once.\n");
+      process.exit(1);
+    }
+
+    const { createLogStore } = await loadDaemonModule(nerveRoot);
+    const store = createLogStore(dbPath);
+
+    try {
+      const result = store.archiveLogs({ vacuum: args.vacuum });
+      if (result.days.length === 0) {
+        process.stdout.write(
+          "✅ Nothing to archive (no eligible UTC days beyond the 30-day window).\n",
+        );
+      } else {
+        process.stdout.write(`✅ Archived ${result.days.length} day(s):\n`);
+        for (const d of result.days) {
+          process.stdout.write(`   ${d.day}  rows=${d.rowCount}  ${d.filePath}\n`);
+        }
+      }
+      if (result.vacuumed) {
+        process.stdout.write("   VACUUM completed.\n");
+      }
+    } finally {
+      store.close();
+    }
+  },
+});
+
+// ---------------------------------------------------------------------------
+// nerve store
+// ---------------------------------------------------------------------------
+
+export const storeCommand = defineCommand({
+  meta: {
+    name: "store",
+    description: "Maintain local Nerve SQLite stores (log cold-archive, …)",
+  },
+  subCommands: {
+    archive: storeArchiveCommand,
+  },
+});

packages/cli/src/commands/workflow.ts

@@ -0,0 +1,364 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { defineCommand } from "citty";
+
+import { triggerWorkflowViaDaemon } from "../daemon-client.js";
+import type { LogStore, WorkflowRun } from "../daemon-types.js";
+import { loadDaemonModule } from "../workspace-daemon.js";
+import { getNerveRoot, getSocketPath, isRunning } from "../workspace.js";
+
+export const DEFAULT_PAGE_SIZE = 20;
+
+export function parseIntArg(raw: string, fallback: number): number {
+  const v = Number.parseInt(raw, 10);
+  return Number.isNaN(v) ? fallback : v;
+}
+
+export function getDbPath(): string {
+  return join(getNerveRoot(), "data", "logs.db");
+}
+
+export function formatTs(ts: number): string {
+  return new Date(ts).toISOString();
+}
+
+async function openStore(): Promise<LogStore> {
+  const nerveRoot = getNerveRoot();
+  const dbPath = getDbPath();
+  if (!existsSync(dbPath)) {
+    process.stderr.write("❌ No logs.db found — has the daemon run yet?\n");
+    process.exit(1);
+  }
+  const { createLogStore } = await loadDaemonModule(nerveRoot);
+  return createLogStore(dbPath);
+}
+
+export function statusIcon(status: WorkflowRun["status"]): string {
+  switch (status) {
+    case "started":
+      return "▶";
+    case "queued":
+      return "⏳";
+    case "completed":
+      return "✅";
+    case "failed":
+      return "❌";
+    case "crashed":
+      return "💥";
+    case "dropped":
+      return "🗑";
+    case "interrupted":
+      return "⚠️";
+    default: {
+      const _exhaustive: never = status;
+      return `?(${_exhaustive})`;
+    }
+  }
+}
+
+/**
+ * Retrieve all workflow runs from the store, sorted by ts descending (newest first).
+ * Delegates to the store's efficient SQL query on the workflow_runs table.
+ */
+export function getAllWorkflowRuns(store: LogStore, filterWorkflow: string | null): WorkflowRun[] {
+  return store.getAllWorkflowRuns(filterWorkflow);
+}
+
+/**
+ * Format a single workflow run as a single output line (no trailing newline in icon/fields).
+ */
+export function formatRunLine(run: WorkflowRun): string {
+  const icon = statusIcon(run.status);
+  return `  ${icon} ${run.runId}  workflow=${run.workflow}  status=${run.status}  ts=${formatTs(run.ts)}\n`;
+}
+
+/**
+ * Format a paginated list of workflow runs into output lines.
+ * Returns the lines to write and any pagination hint.
+ */
+export type ListOutput = {
+  lines: string[];
+  paginationHint: string | null;
+};
+
+export function buildListOutput(
+  runs: WorkflowRun[],
+  offset: number,
+  limit: number,
+  allFlag: boolean,
+  filterWorkflow: string | null,
+): ListOutput {
+  const total = runs.length;
+  const page = runs.slice(offset, offset + limit);
+  const shown = page.length;
+  const remaining = total - offset - shown;
+
+  if (total === 0) {
+    const msg = allFlag
+      ? "📭 No workflow runs found.\n"
+      : "📭 No active workflow runs. Use --all to include completed/failed runs.\n";
+    return { lines: [msg], paginationHint: null };
+  }
+
+  const lines: string[] = [];
+  lines.push(`📋 Workflow runs (${shown} of ${total} shown):\n`);
+  for (const run of page) {
+    lines.push(formatRunLine(run));
+  }
+
+  let paginationHint: string | null = null;
+  if (remaining > 0) {
+    const wfFlag = filterWorkflow !== null ? ` --workflow ${filterWorkflow}` : "";
+    const allFlagStr = allFlag ? " --all" : "";
+    paginationHint =
+      `\n⏩ ${remaining} more run(s) not shown. Fetch next page:\n` +
+      `   nerve workflow list --offset ${offset + limit}${allFlagStr}${wfFlag}\n`;
+  }
+
+  return { lines, paginationHint };
+}
+
+/**
+ * Format the inspect output for a single run's log entries with pagination.
+ */
+export type InspectOutput = {
+  header: string[];
+  eventLines: string[];
+  paginationHint: string | null;
+};
+
+export function buildInspectOutput(
+  run: WorkflowRun,
+  allLogs: Array<{ ts: number; type: string; payload: string | null }>,
+  offset: number,
+  limit: number,
+): InspectOutput {
+  const total = allLogs.length;
+  const page = allLogs.slice(offset, offset + limit);
+  const shown = page.length;
+  const remaining = total - offset - shown;
+
+  const header: string[] = [
+    `🔍 Workflow run: ${run.runId}\n`,
+    `   workflow: ${run.workflow}\n`,
+    `   status:   ${run.status}\n`,
+    `   ts:       ${formatTs(run.ts)}\n`,
+    `\n📜 Thread events (${shown} of ${total}):\n`,
+  ];
+
+  const eventLines: string[] = [];
+  if (total === 0) {
+    eventLines.push("   (no events recorded)\n");
+  } else {
+    for (const entry of page) {
+      const payloadStr =
+        entry.payload === null
+          ? ""
+          : entry.payload.length <= 200
+            ? ` payload=${entry.payload}`
+            : ` payload=${entry.payload.slice(0, 200)}…`;
+      eventLines.push(`  [${formatTs(entry.ts)}] type=${entry.type}${payloadStr}\n`);
+    }
+  }
+
+  let paginationHint: string | null = null;
+  if (remaining > 0) {
+    paginationHint =
+      `\n⏩ ${remaining} more event(s) not shown. Fetch next page:\n` +
+      `   nerve workflow inspect ${run.runId} --offset ${offset + limit}\n`;
+  }
+
+  return { header, eventLines, paginationHint };
+}
+
+// ---------------------------------------------------------------------------
+// nerve workflow list
+// ---------------------------------------------------------------------------
+
+const workflowListCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "List active (queued/started) workflow runs",
+  },
+  args: {
+    all: {
+      type: "boolean",
+      description: "Include completed/failed/crashed runs",
+      default: false,
+    },
+    workflow: {
+      type: "string",
+      description: "Filter by workflow name",
+      default: "",
+    },
+    limit: {
+      type: "string",
+      description: `Max runs to show (default: ${DEFAULT_PAGE_SIZE})`,
+      default: String(DEFAULT_PAGE_SIZE),
+    },
+    offset: {
+      type: "string",
+      description: "Skip first N runs (for pagination)",
+      default: "0",
+    },
+  },
+  async run({ args }) {
+    const store = await openStore();
+
+    try {
+      const limit = Math.max(1, parseIntArg(args.limit, DEFAULT_PAGE_SIZE));
+      const offset = Math.max(0, parseIntArg(args.offset, 0));
+      const filterWorkflow = args.workflow.length > 0 ? args.workflow : null;
+
+      const runs = args.all
+        ? getAllWorkflowRuns(store, filterWorkflow)
+        : store.getActiveWorkflowRuns(filterWorkflow ?? undefined);
+
+      const { lines, paginationHint } = buildListOutput(
+        runs,
+        offset,
+        limit,
+        args.all,
+        filterWorkflow,
+      );
+
+      for (const line of lines) {
+        process.stdout.write(line);
+      }
+      if (paginationHint !== null) {
+        process.stdout.write(paginationHint);
+      }
+    } finally {
+      store.close();
+    }
+  },
+});
+
+// ---------------------------------------------------------------------------
+// nerve workflow inspect <runId>
+// ---------------------------------------------------------------------------
+
+const workflowInspectCommand = defineCommand({
+  meta: {
+    name: "inspect",
+    description: "Show details and thread events for a workflow run",
+  },
+  args: {
+    runId: {
+      type: "positional",
+      description: "The run ID to inspect",
+    },
+    limit: {
+      type: "string",
+      description: `Max log entries to show (default: ${DEFAULT_PAGE_SIZE})`,
+      default: String(DEFAULT_PAGE_SIZE),
+    },
+    offset: {
+      type: "string",
+      description: "Skip first N log entries (for pagination)",
+      default: "0",
+    },
+  },
+  async run({ args }) {
+    const store = await openStore();
+
+    try {
+      const limit = Math.max(1, parseIntArg(args.limit, DEFAULT_PAGE_SIZE));
+      const offset = Math.max(0, parseIntArg(args.offset, 0));
+
+      const run = store.getWorkflowRun(args.runId);
+      if (run === null) {
+        process.stderr.write(`❌ No workflow run found with runId: ${args.runId}\n`);
+        process.exit(1);
+      }
+
+      const allLogs = store.query({ source: "workflow", refId: args.runId });
+      const { header, eventLines, paginationHint } = buildInspectOutput(
+        run,
+        allLogs,
+        offset,
+        limit,
+      );
+
+      for (const line of [...header, ...eventLines]) {
+        process.stdout.write(line);
+      }
+      if (paginationHint !== null) {
+        process.stdout.write(paginationHint);
+      }
+    } finally {
+      store.close();
+    }
+  },
+});
+
+// ---------------------------------------------------------------------------
+// nerve workflow trigger <name>
+// ---------------------------------------------------------------------------
+
+const workflowTriggerCommand = defineCommand({
+  meta: {
+    name: "trigger",
+    description: "Manually trigger a workflow by sending an IPC message to the running daemon",
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "The workflow name to trigger",
+    },
+    payload: {
+      type: "string",
+      description: "JSON payload to pass as trigger payload (default: {})",
+      default: "{}",
+    },
+  },
+  async run({ args }) {
+    let triggerPayload: unknown = {};
+    try {
+      triggerPayload = JSON.parse(args.payload) as unknown;
+    } catch {
+      process.stderr.write(`❌ --payload must be valid JSON. Got: ${args.payload}\n`);
+      process.exit(1);
+    }
+
+    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 };
+    try {
+      response = await triggerWorkflowViaDaemon(socketPath, args.name, triggerPayload);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(`❌ Failed to contact daemon: ${msg}\n`);
+      process.exit(1);
+    }
+
+    if (!response.ok) {
+      process.stderr.write(`❌ Daemon rejected trigger: ${response.error}\n`);
+      process.exit(1);
+    }
+
+    process.stdout.write(`✅ Triggered workflow "${args.name}" via daemon.\n`);
+    process.stdout.write("\n💡 Inspect active runs with: nerve workflow list\n");
+  },
+});
+
+// ---------------------------------------------------------------------------
+// nerve workflow (parent command)
+// ---------------------------------------------------------------------------
+
+export const workflowCommand = defineCommand({
+  meta: {
+    name: "workflow",
+    description: "Manage and inspect workflow runs",
+  },
+  subCommands: {
+    list: workflowListCommand,
+    inspect: workflowInspectCommand,
+    trigger: workflowTriggerCommand,
+  },
+});

packages/cli/src/daemon-bootstrap.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { runForegroundKernelSession } from "./run-foreground-kernel.js";
+import { loadDaemonModule } from "./workspace-daemon.js";
+
+const nerveRoot = process.env.NERVE_ROOT;
+if (nerveRoot === undefined || nerveRoot.length === 0) {
+  process.stderr.write("[nerve] NERVE_ROOT environment variable is required.\n");
+  process.exit(1);
+}
+
+const { createKernel } = await loadDaemonModule(nerveRoot);
+await runForegroundKernelSession(nerveRoot, createKernel);

packages/cli/src/daemon-client.ts

@@ -0,0 +1,190 @@
+/**
+ * Daemon IPC client — connects to the daemon's Unix socket and sends
+ * trigger-workflow or trigger-sense requests.
+ *
+ * Protocol: newline-delimited JSON (same as daemon-ipc.ts server side).
+ */
+
+import { connect } from "node:net";
+import type { Socket } from "node:net";
+
+const CONNECT_TIMEOUT_MS = 3_000;
+const RESPONSE_TIMEOUT_MS = 5_000;
+
+type TriggerResponse = { ok: true } | { ok: false; error: string };
+
+export type SenseInfo = {
+  name: string;
+  group: string;
+  throttle: number | null;
+  timeout: number | null;
+  lastSignalTs: number | null;
+};
+
+type ListSensesResponse = { ok: true; senses: SenseInfo[] } | { ok: false; error: string };
+
+function parseDaemonResponse(line: string): TriggerResponse {
+  try {
+    const obj = JSON.parse(line) as unknown;
+    if (obj !== null && typeof obj === "object") {
+      const r = obj as Record<string, unknown>;
+      if (r.ok === true) return { ok: true };
+      if (r.ok === false && typeof r.error === "string") return { ok: false, error: r.error };
+    }
+  } catch {
+    // fall through
+  }
+  return { ok: false, error: `Unexpected daemon response: ${line}` };
+}
+
+function sendAndReceive(socketPath: string, message: object): Promise<TriggerResponse> {
+  return new Promise((resolve, reject) => {
+    let socket: Socket | null = null;
+    let settled = false;
+
+    function settle(result: TriggerResponse | Error): void {
+      if (settled) return;
+      settled = true;
+      if (socket !== null) {
+        socket.destroy();
+        socket = null;
+      }
+      if (result instanceof Error) {
+        reject(result);
+      } else {
+        resolve(result);
+      }
+    }
+
+    const connectTimer = setTimeout(() => {
+      settle(new Error(`Timed out connecting to daemon socket: ${socketPath}`));
+    }, CONNECT_TIMEOUT_MS);
+
+    socket = connect(socketPath, () => {
+      clearTimeout(connectTimer);
+
+      const responseTimer = setTimeout(() => {
+        settle(new Error("Timed out waiting for daemon response"));
+      }, RESPONSE_TIMEOUT_MS);
+
+      let buf = "";
+      socket?.on("data", (chunk: Buffer) => {
+        buf += chunk.toString("utf8");
+        const lines = buf.split("\n");
+        buf = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (trimmed.length === 0) continue;
+          clearTimeout(responseTimer);
+          settle(parseDaemonResponse(trimmed));
+          return;
+        }
+      });
+
+      const msg = `${JSON.stringify(message)}\n`;
+      socket?.write(msg);
+    });
+
+    socket.on("error", (err) => {
+      clearTimeout(connectTimer);
+      settle(new Error(`Cannot connect to daemon: ${err.message}`));
+    });
+  });
+}
+
+/**
+ * Send a trigger-workflow message to the running daemon via its Unix socket.
+ * Resolves with the daemon's response or rejects on connection/timeout errors.
+ */
+export function triggerWorkflowViaDaemon(
+  socketPath: string,
+  workflow: string,
+  payload: unknown,
+): Promise<TriggerResponse> {
+  return sendAndReceive(socketPath, { type: "trigger-workflow", workflow, payload });
+}
+
+/**
+ * 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 });
+}
+
+/**
+ * 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 new Promise((resolve, reject) => {
+    let socket: Socket | null = null;
+    let settled = false;
+
+    function settle(result: ListSensesResponse | Error): void {
+      if (settled) return;
+      settled = true;
+      if (socket !== null) {
+        socket.destroy();
+        socket = null;
+      }
+      if (result instanceof Error) {
+        reject(result);
+      } else {
+        resolve(result);
+      }
+    }
+
+    const connectTimer = setTimeout(() => {
+      settle(new Error(`Timed out connecting to daemon socket: ${socketPath}`));
+    }, CONNECT_TIMEOUT_MS);
+
+    socket = connect(socketPath, () => {
+      clearTimeout(connectTimer);
+
+      const responseTimer = setTimeout(() => {
+        settle(new Error("Timed out waiting for daemon response"));
+      }, RESPONSE_TIMEOUT_MS);
+
+      let buf = "";
+      socket?.on("data", (chunk: Buffer) => {
+        buf += chunk.toString("utf8");
+        const lines = buf.split("\n");
+        buf = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (trimmed.length === 0) continue;
+          clearTimeout(responseTimer);
+          try {
+            const obj = JSON.parse(trimmed) as unknown;
+            if (obj !== null && typeof obj === "object") {
+              const r = obj as Record<string, unknown>;
+              if (r.ok === false && typeof r.error === "string") {
+                settle({ ok: false, error: r.error });
+                return;
+              }
+              if (r.ok === true && Array.isArray(r.senses)) {
+                settle({ ok: true, senses: r.senses as SenseInfo[] });
+                return;
+              }
+            }
+          } catch {
+            // fall through
+          }
+          settle({ ok: false, error: `Unexpected daemon response: ${trimmed}` });
+          return;
+        }
+      });
+
+      socket?.write(`${JSON.stringify({ type: "list-senses" })}\n`);
+    });
+
+    socket.on("error", (err) => {
+      clearTimeout(connectTimer);
+      settle(new Error(`Cannot connect to daemon: ${err.message}`));
+    });
+  });
+}

packages/cli/src/daemon-types.ts

@@ -0,0 +1,70 @@
+/**
+ * Structural types for workflow CLI — mirrors @uncaged/nerve-daemon log-store
+ * public API so the CLI runtime does not statically depend on the daemon package.
+ *
+ * ⚠️  Keep in sync with @uncaged/nerve-daemon exports.
+ *     Run `pnpm --filter @uncaged/nerve-cli test` to catch drift via satisfies assertions.
+ */
+
+export type WorkflowRunStatus =
+  | "queued"
+  | "started"
+  | "completed"
+  | "failed"
+  | "crashed"
+  | "dropped"
+  | "interrupted";
+
+export type WorkflowRun = {
+  runId: string;
+  workflow: string;
+  status: WorkflowRunStatus;
+  ts: number;
+};
+
+export type LogEntry = {
+  id?: number;
+  source: string;
+  type: string;
+  refId: string | null;
+  payload: string | null;
+  ts: number;
+};
+
+export type LogQuery = {
+  source?: string;
+  type?: string;
+  refId?: string;
+  since?: number;
+  until?: number;
+  limit?: number;
+};
+
+export type ArchiveLogsOptions = {
+  now?: number;
+  vacuum?: boolean;
+  maxDays?: number;
+  retentionMs?: number;
+};
+
+export type ArchiveLogsDayResult = {
+  day: string;
+  rowCount: number;
+  filePath: string;
+};
+
+export type ArchiveLogsResult = {
+  days: ArchiveLogsDayResult[];
+  vacuumed: boolean;
+};
+
+/** Subset of daemon LogStore used by the CLI workflow commands. */
+export type LogStore = {
+  query: (filter?: LogQuery) => LogEntry[];
+  getWorkflowRun: (runId: string) => WorkflowRun | null;
+  getActiveWorkflowRuns: (workflowName?: string) => WorkflowRun[];
+  getAllWorkflowRuns: (workflowName: string | null) => WorkflowRun[];
+  upsertWorkflowRun: (entry: Omit<LogEntry, "id">, run: WorkflowRun) => LogEntry;
+  archiveLogs: (options?: ArchiveLogsOptions) => ArchiveLogsResult;
+  close: () => void;
+};

packages/cli/src/index.ts

@@ -8,5 +8,8 @@ export {
   isRunning,
 } from "./workspace.js";
 
-export { createKernel } from "@uncaged/nerve-daemon";
-export type { Kernel } from "@uncaged/nerve-daemon";
+export {
+  assertWorkspaceDaemonInstalled,
+  getDaemonEntryPath,
+  loadDaemonModule,
+} from "./workspace-daemon.js";

packages/cli/src/run-foreground-kernel.ts

@@ -0,0 +1,88 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { NerveConfig } from "@uncaged/nerve-core";
+import { parseNerveConfig } from "@uncaged/nerve-core";
+
+import { getSocketPath } from "./workspace.js";
+
+export type CreateKernelFn = (
+  config: NerveConfig,
+  nerveRoot: string,
+  opts: { enableFileWatcher: boolean; ipcSocketPath: string },
+) => {
+  groups: Set<string>;
+  ready: Promise<void>;
+  stop: () => Promise<void>;
+};
+
+function readConfig(nerveRoot: string): ReturnType<typeof parseNerveConfig> {
+  const configPath = join(nerveRoot, "nerve.yaml");
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, "utf8");
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, error: new Error(`❌ Cannot read ${configPath}: ${msg}`) };
+  }
+  return parseNerveConfig(raw);
+}
+
+export async function runForegroundKernelSession(
+  nerveRoot: string,
+  createKernel: CreateKernelFn,
+): Promise<void> {
+  const configResult = readConfig(nerveRoot);
+  if (!configResult.ok) {
+    process.stderr.write(`${configResult.error.message}\n`);
+    process.exit(1);
+  }
+
+  const config = configResult.value;
+  const kernel = createKernel(config, nerveRoot, {
+    enableFileWatcher: true,
+    ipcSocketPath: getSocketPath(),
+  });
+
+  const senseNames = Object.keys(config.senses);
+  const groups = [...kernel.groups];
+
+  process.stdout.write(
+    `✅ Nerve starting — ${senseNames.length} sense(s), ${groups.length} group(s)\n`,
+  );
+  for (const group of groups) {
+    const groupSenses = Object.entries(config.senses)
+      .filter(([, sc]) => sc.group === group)
+      .map(([name]) => name);
+    process.stdout.write(`   group "${group}": ${groupSenses.join(", ")}\n`);
+  }
+  process.stdout.write("   Press Ctrl+C to stop.\n");
+
+  let shuttingDown = false;
+
+  async function shutdown(): Promise<void> {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    process.stdout.write("\n[nerve] Shutting down…\n");
+    await kernel.stop();
+    process.exit(0);
+  }
+
+  process.on("SIGINT", () => {
+    shutdown().catch((e: unknown) => {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(`[nerve] Shutdown error: ${msg}\n`);
+      process.exit(1);
+    });
+  });
+
+  process.on("SIGTERM", () => {
+    shutdown().catch((e: unknown) => {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(`[nerve] Shutdown error: ${msg}\n`);
+      process.exit(1);
+    });
+  });
+
+  await kernel.ready;
+}

packages/cli/src/workspace-daemon.ts

@@ -0,0 +1,50 @@
+import { existsSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { NerveConfig } from "@uncaged/nerve-core";
+
+import type { LogStore } from "./daemon-types.js";
+
+export function getDaemonEntryPath(nerveRoot: string): string | undefined {
+  const pkgPath = join(nerveRoot, "node_modules", "@uncaged", "nerve-daemon", "package.json");
+  if (!existsSync(pkgPath)) return undefined;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { main?: string };
+    const main = pkg.main ?? "dist/index.js";
+    return join(nerveRoot, "node_modules", "@uncaged", "nerve-daemon", main);
+  } catch {
+    return join(nerveRoot, "node_modules", "@uncaged", "nerve-daemon", "dist", "index.js");
+  }
+}
+
+export function assertWorkspaceDaemonInstalled(nerveRoot: string): string {
+  const entry = getDaemonEntryPath(nerveRoot);
+  if (!entry || !existsSync(entry)) {
+    throw new Error(
+      `@uncaged/nerve-daemon is not installed under ${nerveRoot}/node_modules/. Run \`nerve init\` (or \`nerve init --force\`) to install workspace dependencies.`,
+    );
+  }
+  return entry;
+}
+
+/** Loaded from ~/.uncaged-nerve/node_modules at runtime — keep types structural only. */
+export type DaemonModule = {
+  createKernel: (
+    config: NerveConfig,
+    nerveRoot: string,
+    options: { enableFileWatcher: boolean; ipcSocketPath: string },
+  ) => {
+    groups: Set<string>;
+    ready: Promise<void>;
+    stop: () => Promise<void>;
+  };
+  createLogStore: (dbPath: string) => LogStore;
+};
+
+export async function loadDaemonModule(nerveRoot: string): Promise<DaemonModule> {
+  const entry = assertWorkspaceDaemonInstalled(nerveRoot);
+  const url = pathToFileURL(entry).href;
+  return import(url) as Promise<DaemonModule>;
+}

packages/cli/src/workspace.ts

@@ -10,6 +10,10 @@ export function getPidPath(): string {
   return join(getNerveRoot(), "nerve.pid");
 }
 
+export function getSocketPath(): string {
+  return join(getNerveRoot(), "nerve.sock");
+}
+
 export function getLogPath(): string {
   return join(getNerveRoot(), "logs", "nerve.log");
 }

packages/cli/tsup.config.ts

@@ -1,8 +1,13 @@
 import { defineConfig } from "tsup";
 
 export default defineConfig({
-  entry: ["src/index.ts", "src/cli.ts"],
+  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/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@uncaged/nerve-core",
-  "version": "0.0.1",
-  "private": true,
+  "version": "0.1.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/daemon/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@uncaged/nerve-daemon",
-  "version": "0.0.1",
-  "private": true,
+  "version": "0.1.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run"

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

@@ -91,6 +91,7 @@ function makeLogStore(
     }),
     getTriggerPayload: vi.fn(() => ({ value: 42 })),
     getThreadEvents: vi.fn(() => [{ type: "thread_start", triggerPayload: {} }]),
+    archiveLogs: vi.fn(() => ({ days: [], vacuumed: false })),
     close: vi.fn(),
   };
   return store;

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

@@ -0,0 +1,234 @@
+/**
+ * Unit + integration tests for daemon-ipc.ts — trigger-sense request type.
+ *
+ * Tests cover:
+ *   - parseRequest correctly accepts/rejects trigger-sense messages
+ *   - createDaemonIpcServer routes trigger-sense to opts.triggerSense
+ *   - Error response when triggerSense throws (unknown sense)
+ *   - Success response on valid sense trigger
+ */
+
+import { rmSync } from "node:fs";
+import { connect } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createDaemonIpcServer } from "../daemon-ipc.js";
+import type { DaemonIpcServer } from "../daemon-ipc.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+let sockPath: string;
+let server: DaemonIpcServer | null = null;
+
+function makeMockWorkflowManager() {
+  return {
+    startWorkflow: vi.fn(),
+    stop: vi.fn(async () => {}),
+    totalActiveCount: vi.fn(() => 0),
+    drainAndRespawn: vi.fn(async () => {}),
+    updateConfig: vi.fn(),
+    getActiveWorkflowRuns: vi.fn(() => []),
+  };
+}
+
+function sendRaw(path: string, message: object): Promise<object> {
+  return new Promise((resolve, reject) => {
+    const sock = connect(path, () => {
+      let buf = "";
+      sock.on("data", (chunk: Buffer) => {
+        buf += chunk.toString("utf8");
+        const lines = buf.split("\n");
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (trimmed.length === 0) continue;
+          try {
+            resolve(JSON.parse(trimmed) as object);
+          } catch {
+            reject(new Error(`Invalid JSON response: ${trimmed}`));
+          }
+          sock.destroy();
+          return;
+        }
+        buf = lines[lines.length - 1] ?? "";
+      });
+      sock.write(`${JSON.stringify(message)}\n`);
+    });
+    sock.on("error", reject);
+  });
+}
+
+beforeEach(() => {
+  sockPath = join(tmpdir(), `nerve-ipc-test-${Date.now()}-${Math.random().toString(36).slice(2)}.sock`);
+});
+
+afterEach(async () => {
+  if (server !== null) {
+    await server.close();
+    server = null;
+  }
+  try {
+    rmSync(sockPath);
+  } catch {
+    // already removed
+  }
+});
+
+// ---------------------------------------------------------------------------
+// trigger-sense: valid request → ok: true
+// ---------------------------------------------------------------------------
+
+describe("daemon-ipc — trigger-sense", () => {
+  it("responds ok:true when triggerSense succeeds", async () => {
+    const triggerSense = vi.fn();
+    server = createDaemonIpcServer(sockPath, makeMockWorkflowManager() as never, {
+      triggerSense,
+      listSenses: vi.fn(() => []),
+    });
+
+    const resp = await sendRaw(sockPath, { type: "trigger-sense", sense: "cpu-usage" });
+
+    expect(resp).toEqual({ ok: true });
+    expect(triggerSense).toHaveBeenCalledOnce();
+    expect(triggerSense).toHaveBeenCalledWith("cpu-usage");
+  });
+
+  it("responds ok:false with error message when triggerSense throws", async () => {
+    const triggerSense = vi.fn(() => {
+      throw new Error('Unknown sense: "no-such-sense"');
+    });
+    server = createDaemonIpcServer(sockPath, makeMockWorkflowManager() as never, {
+      triggerSense,
+      listSenses: vi.fn(() => []),
+    });
+
+    const resp = await sendRaw(sockPath, { type: "trigger-sense", sense: "no-such-sense" });
+
+    expect(resp).toEqual({ ok: false, error: 'Unknown sense: "no-such-sense"' });
+    expect(triggerSense).toHaveBeenCalledWith("no-such-sense");
+  });
+
+  it("responds ok:false for trigger-sense with empty sense name", async () => {
+    const triggerSense = vi.fn();
+    server = createDaemonIpcServer(sockPath, makeMockWorkflowManager() as never, {
+      triggerSense,
+      listSenses: vi.fn(() => []),
+    });
+
+    const resp = await sendRaw(sockPath, { type: "trigger-sense", sense: "" });
+
+    expect(resp).toEqual({ ok: false, error: "Invalid request" });
+    expect(triggerSense).not.toHaveBeenCalled();
+  });
+
+  it("responds ok:false for trigger-sense missing sense field", async () => {
+    const triggerSense = vi.fn();
+    server = createDaemonIpcServer(sockPath, makeMockWorkflowManager() as never, {
+      triggerSense,
+      listSenses: vi.fn(() => []),
+    });
+
+    const resp = await sendRaw(sockPath, { type: "trigger-sense" });
+
+    expect(resp).toEqual({ ok: false, error: "Invalid request" });
+    expect(triggerSense).not.toHaveBeenCalled();
+  });
+
+  it("does NOT call triggerSense for trigger-workflow requests", async () => {
+    const triggerSense = vi.fn();
+    const wfManager = makeMockWorkflowManager();
+    server = createDaemonIpcServer(sockPath, wfManager as never, {
+      triggerSense,
+      listSenses: vi.fn(() => []),
+    });
+
+    const resp = await sendRaw(sockPath, {
+      type: "trigger-workflow",
+      workflow: "my-workflow",
+      payload: {},
+    });
+
+    expect(resp).toEqual({ ok: true });
+    expect(triggerSense).not.toHaveBeenCalled();
+    expect(wfManager.startWorkflow).toHaveBeenCalledWith("my-workflow", {});
+  });
+
+  it("responds ok:false for completely unknown request type", async () => {
+    const triggerSense = vi.fn();
+    server = createDaemonIpcServer(sockPath, makeMockWorkflowManager() as never, {
+      triggerSense,
+      listSenses: vi.fn(() => []),
+    });
+
+    const resp = await sendRaw(sockPath, { type: "unknown-type", data: "x" });
+
+    expect(resp).toEqual({ ok: false, error: "Invalid request" });
+    expect(triggerSense).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// list-senses: valid request → ok: true with senses array
+// ---------------------------------------------------------------------------
+
+describe("daemon-ipc — list-senses", () => {
+  it("responds ok:true with empty senses array when listSenses returns []", async () => {
+    const listSenses = vi.fn(() => []);
+    server = createDaemonIpcServer(sockPath, makeMockWorkflowManager() as never, {
+      triggerSense: vi.fn(),
+      listSenses,
+    });
+
+    const resp = await sendRaw(sockPath, { type: "list-senses" });
+
+    expect(resp).toEqual({ ok: true, senses: [] });
+    expect(listSenses).toHaveBeenCalledOnce();
+  });
+
+  it("responds ok:true with senses populated from listSenses", async () => {
+    const sensesData = [
+      { name: "cpu-usage", group: "system", throttle: 5000, timeout: 3000, lastSignalTs: 1000 },
+      { name: "disk-usage", group: "system", throttle: 30000, timeout: null, lastSignalTs: null },
+    ];
+    const listSenses = vi.fn(() => sensesData);
+    server = createDaemonIpcServer(sockPath, makeMockWorkflowManager() as never, {
+      triggerSense: vi.fn(),
+      listSenses,
+    });
+
+    const resp = await sendRaw(sockPath, { type: "list-senses" });
+
+    expect(resp).toEqual({ ok: true, senses: sensesData });
+    expect(listSenses).toHaveBeenCalledOnce();
+  });
+
+  it("responds ok:false when listSenses throws", async () => {
+    const listSenses = vi.fn(() => {
+      throw new Error("internal error");
+    });
+    server = createDaemonIpcServer(sockPath, makeMockWorkflowManager() as never, {
+      triggerSense: vi.fn(),
+      listSenses,
+    });
+
+    const resp = await sendRaw(sockPath, { type: "list-senses" });
+
+    expect(resp).toEqual({ ok: false, error: "internal error" });
+  });
+
+  it("does NOT call listSenses for trigger-sense requests", async () => {
+    const listSenses = vi.fn(() => []);
+    server = createDaemonIpcServer(sockPath, makeMockWorkflowManager() as never, {
+      triggerSense: vi.fn(),
+      listSenses,
+    });
+
+    await sendRaw(sockPath, { type: "trigger-sense", sense: "cpu-usage" });
+
+    expect(listSenses).not.toHaveBeenCalled();
+  });
+});

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

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

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

@@ -0,0 +1,200 @@
+/**
+ * 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.
+ */
+
+import { EventEmitter } from "node:events";
+
+import type { NerveConfig } from "@uncaged/nerve-core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ---------------------------------------------------------------------------
+// Mock child_process.fork before importing kernel
+// ---------------------------------------------------------------------------
+
+const mockChildren: MockChild[] = [];
+
+type MockChild = EventEmitter & {
+  send: ReturnType<typeof vi.fn>;
+  kill: ReturnType<typeof vi.fn>;
+  connected: boolean;
+  pid: number;
+};
+
+function makeMockChild(pid = 1): MockChild {
+  const child = new EventEmitter() as MockChild;
+  child.connected = true;
+  child.send = vi.fn((msg: unknown) => {
+    if (
+      msg !== null &&
+      typeof msg === "object" &&
+      (msg as Record<string, unknown>).type === "shutdown"
+    ) {
+      setImmediate(() => {
+        child.connected = false;
+        child.emit("exit", 0, null);
+      });
+    }
+  });
+  child.kill = vi.fn((_signal?: string) => {
+    child.connected = false;
+    child.emit("exit", null, _signal ?? "SIGKILL");
+  });
+  child.pid = pid;
+  return child;
+}
+
+vi.mock("node:child_process", () => ({
+  fork: vi.fn((_script: string, _args: string[], _opts: unknown) => {
+    const child = makeMockChild(mockChildren.length + 1);
+    mockChildren.push(child);
+    return child;
+  }),
+}));
+
+// Import after mock is set up
+const { createKernel } = await import("../kernel.js");
+
+// ---------------------------------------------------------------------------
+// Mock LogStore factory (avoids better-sqlite3 dependency)
+// ---------------------------------------------------------------------------
+
+function makeMockLogStore() {
+  return {
+    append: vi.fn(),
+    query: vi.fn(() => []),
+    getMeta: vi.fn(() => null),
+    setMeta: vi.fn(),
+    upsertWorkflowRun: vi.fn(),
+    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 })),
+    close: vi.fn(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Config helpers
+// ---------------------------------------------------------------------------
+
+function makeConfig(overrides: Partial<NerveConfig> = {}): NerveConfig {
+  return {
+    senses: {
+      "cpu-usage": { group: "system", throttle: null, timeout: null, gracePeriod: null },
+    },
+    reflexes: [],
+    workflows: null,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("kernel.triggerSense()", () => {
+  beforeEach(() => {
+    mockChildren.length = 0;
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("throws for an unknown sense name", async () => {
+    const config = makeConfig();
+    const kernel = createKernel(config, "/tmp/nerve-test", {
+      workerScript: null,
+      logStore: makeMockLogStore() as never,
+    });
+
+    expect(() => kernel.triggerSense("no-such-sense")).toThrow(/Unknown sense/);
+
+    await kernel.stop();
+  });
+
+  it("sends a compute message to the worker for the correct group", async () => {
+    const config = makeConfig({
+      senses: {
+        "cpu-usage": { group: "system", throttle: null, timeout: null, gracePeriod: null },
+        "net-io": { group: "network", throttle: null, timeout: null, gracePeriod: null },
+      },
+      reflexes: [],
+    });
+    const kernel = createKernel(config, "/tmp/nerve-test", {
+      workerScript: null,
+      logStore: makeMockLogStore() as never,
+    });
+
+    // Two groups → two workers
+    expect(mockChildren.length).toBe(2);
+
+    // Workers are keyed by group: groups iteration order matches the insertion
+    // order from Object.values(config.senses).  Find the worker for "system".
+    const systemWorkerIdx = Array.from(kernel.groups).indexOf("system");
+    const systemWorker = mockChildren[systemWorkerIdx];
+
+    kernel.triggerSense("cpu-usage");
+
+    expect(systemWorker.send).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "compute", sense: "cpu-usage" }),
+    );
+
+    await kernel.stop();
+  });
+
+  it("sends a compute message to the correct worker when multiple senses share a group", async () => {
+    const config = makeConfig({
+      senses: {
+        "cpu-usage": { group: "system", throttle: null, timeout: null, gracePeriod: null },
+        "disk-usage": { group: "system", throttle: null, timeout: null, gracePeriod: null },
+      },
+      reflexes: [],
+    });
+    const kernel = createKernel(config, "/tmp/nerve-test", {
+      workerScript: null,
+      logStore: makeMockLogStore() as never,
+    });
+
+    // Both senses share the "system" group → one worker only
+    expect(mockChildren.length).toBe(1);
+    const worker = mockChildren[0];
+
+    kernel.triggerSense("disk-usage");
+
+    expect(worker.send).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "compute", sense: "disk-usage" }),
+    );
+
+    await kernel.stop();
+  });
+
+  it("does not send to a disconnected worker (does not throw)", async () => {
+    // Use real timers so kernel.stop() waitForExit can rely on SIGKILL timeout
+    vi.useRealTimers();
+
+    const config = makeConfig();
+    const kernel = createKernel(config, "/tmp/nerve-test", {
+      workerScript: null,
+      logStore: makeMockLogStore() as never,
+    });
+
+    const worker = mockChildren[0];
+    worker.connected = false;
+
+    // Should not throw even when the worker is disconnected
+    expect(() => kernel.triggerSense("cpu-usage")).not.toThrow();
+    expect(worker.send).not.toHaveBeenCalledWith(
+      expect.objectContaining({ type: "compute" }),
+    );
+
+    await kernel.stop();
+  }, 10_000);
+});

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

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

packages/daemon/src/__tests__/log-archive.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  assertValidUtcDay,
+  compareIsoDays,
+  lastArchivableUtcDay,
+  nextUtcDay,
+  prevUtcDay,
+  utcDateStringFromMs,
+  utcDayEndExclusiveMs,
+  utcDayStartMs,
+} from "../log-archive.js";
+
+describe("log-archive UTC helpers", () => {
+  it("lastArchivableUtcDay matches RFC-style boundary (exclusive end of day ≤ boundary)", () => {
+    const boundary = Date.UTC(2026, 1, 2, 12, 0, 0); // 2026-02-02 12:00 UTC
+    expect(lastArchivableUtcDay(boundary)).toBe("2026-02-01");
+  });
+
+  it("round-trips UTC day bounds", () => {
+    expect(utcDayStartMs("2026-02-01")).toBe(Date.UTC(2026, 1, 1));
+    expect(utcDayEndExclusiveMs("2026-02-01")).toBe(Date.UTC(2026, 1, 2));
+    expect(utcDateStringFromMs(Date.UTC(2026, 1, 1, 23, 59))).toBe("2026-02-01");
+  });
+
+  it("nextUtcDay / prevUtcDay", () => {
+    expect(nextUtcDay("2026-02-01")).toBe("2026-02-02");
+    expect(prevUtcDay("2026-02-01")).toBe("2026-01-31");
+  });
+
+  it("compareIsoDays sorts lexicographically for YYYY-MM-DD", () => {
+    expect(compareIsoDays("2026-01-01", "2026-02-01")).toBeLessThan(0);
+    expect(compareIsoDays("2026-02-01", "2026-02-01")).toBe(0);
+  });
+
+  it("assertValidUtcDay rejects invalid calendars", () => {
+    expect(() => assertValidUtcDay("2026-02-31")).toThrow();
+    expect(() => assertValidUtcDay("bad")).toThrow();
+  });
+});

packages/daemon/src/__tests__/log-store-archive.test.ts

@@ -0,0 +1,139 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { LOG_ARCHIVE_META_KEY, createLogStore } from "../log-store.js";
+import type { LogStore } from "../log-store.js";
+
+const DAY_MS = 86_400_000;
+
+/** `now` such that 2026-02-01 is the last archivable UTC day under a 30-day window. */
+function nowForLastArchivableFeb1(): number {
+  const boundary = Date.UTC(2026, 1, 2, 12, 0, 0);
+  return boundary + 30 * DAY_MS;
+}
+
+describe("LogStore — cold archive (RFC-001 §5.4)", () => {
+  let tmpDir: string;
+  let store: LogStore;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "nerve-archive-"));
+    store = createLogStore(join(tmpDir, "data", "logs.db"));
+  });
+
+  afterEach(() => {
+    store.close();
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("exports one UTC day to JSONL, deletes rows, advances archived_up_to", () => {
+    const ts = Date.UTC(2026, 1, 1, 10, 0, 0);
+    store.append({ source: "system", type: "x", refId: null, payload: '{"a":1}', ts });
+    store.append({ source: "reflex", type: "y", refId: "z", payload: null, ts: ts + 1 });
+
+    const now = nowForLastArchivableFeb1();
+    const result = store.archiveLogs({ now, retentionMs: 30 * DAY_MS });
+    expect(result.days).toHaveLength(1);
+    expect(result.days[0].day).toBe("2026-02-01");
+    expect(result.days[0].rowCount).toBe(2);
+
+    const jsonlPath = join(tmpDir, "data", "archive", "logs", "2026-02-01.jsonl");
+    expect(result.days[0].filePath).toBe(jsonlPath);
+
+    const lines = readFileSync(jsonlPath, "utf8").trim().split("\n");
+    expect(lines).toHaveLength(2);
+    const o = JSON.parse(lines[0] ?? "{}") as Record<string, unknown>;
+    expect(o.source).toBe("system");
+    expect(o.refId).toBeNull();
+
+    expect(store.query()).toHaveLength(0);
+    expect(store.getMeta(LOG_ARCHIVE_META_KEY)).toBe("2026-02-01");
+  });
+
+  it("returns nothing for an empty logs table", () => {
+    const r = store.archiveLogs({ now: nowForLastArchivableFeb1(), retentionMs: 30 * DAY_MS });
+    expect(r.days).toHaveLength(0);
+    expect(store.getMeta(LOG_ARCHIVE_META_KEY)).toBeNull();
+  });
+
+  it("does nothing when all logs are inside the hot window", () => {
+    const now = Date.UTC(2026, 3, 23, 12, 0, 0);
+    const ts = now - 5 * DAY_MS;
+    store.append({ source: "system", type: "warm", refId: null, payload: null, ts });
+    const r = store.archiveLogs({ now, retentionMs: 30 * DAY_MS });
+    expect(r.days).toHaveLength(0);
+    expect(store.query()).toHaveLength(1);
+  });
+
+  it("second archive with same clock is a no-op (watermark already caught up)", () => {
+    const ts = Date.UTC(2026, 1, 1, 10, 0, 0);
+    store.append({ source: "system", type: "x", refId: null, payload: null, ts });
+    const now = nowForLastArchivableFeb1();
+    store.archiveLogs({ now, retentionMs: 30 * DAY_MS });
+    const path = join(tmpDir, "data", "archive", "logs", "2026-02-01.jsonl");
+    const first = readFileSync(path, "utf8");
+
+    const second = store.archiveLogs({ now, retentionMs: 30 * DAY_MS });
+    expect(second.days).toHaveLength(0);
+    expect(readFileSync(path, "utf8")).toBe(first);
+  });
+
+  it("overwrites JSONL when the same UTC day is archived again after watermark rewind", () => {
+    const ts = Date.UTC(2026, 1, 1, 10, 0, 0);
+    store.append({ source: "a", type: "1", refId: null, payload: null, ts });
+    const now = nowForLastArchivableFeb1();
+    store.archiveLogs({ now, retentionMs: 30 * DAY_MS });
+    store.setMeta(LOG_ARCHIVE_META_KEY, "2026-01-31");
+    store.append({ source: "b", type: "2", refId: null, payload: null, ts: ts + 100 });
+    store.archiveLogs({ now, retentionMs: 30 * DAY_MS });
+
+    const path = join(tmpDir, "data", "archive", "logs", "2026-02-01.jsonl");
+    const lines = readFileSync(path, "utf8").trim().split("\n");
+    expect(lines).toHaveLength(1);
+    expect(JSON.parse(lines[0] ?? "{}").source).toBe("b");
+  });
+
+  it("respects maxDays across invocations", () => {
+    const t1 = Date.UTC(2026, 1, 1, 10, 0, 0);
+    const t2 = Date.UTC(2026, 1, 2, 10, 0, 0);
+    store.append({ source: "system", type: "a", refId: null, payload: null, ts: t1 });
+    store.append({ source: "system", type: "b", refId: null, payload: null, ts: t2 });
+
+    const now = Date.UTC(2027, 0, 1, 12, 0, 0);
+    const r1 = store.archiveLogs({ now, retentionMs: 30 * DAY_MS, maxDays: 1 });
+    expect(r1.days).toHaveLength(1);
+    expect(r1.days[0].day).toBe("2026-02-01");
+
+    const r2 = store.archiveLogs({ now, retentionMs: 30 * DAY_MS, maxDays: 1 });
+    expect(r2.days).toHaveLength(1);
+    expect(r2.days[0].day).toBe("2026-02-02");
+    expect(store.getMeta(LOG_ARCHIVE_META_KEY)).toBe("2026-02-02");
+    expect(store.query()).toHaveLength(0);
+  });
+
+  it("starts from earliest log day when it is before watermark+1", () => {
+    store.setMeta(LOG_ARCHIVE_META_KEY, "2026-01-10");
+    const ts = Date.UTC(2026, 1, 1, 10, 0, 0);
+    store.append({ source: "x", type: "p", refId: null, payload: null, ts });
+    const result = store.archiveLogs({ now: nowForLastArchivableFeb1(), retentionMs: 30 * DAY_MS });
+    expect(result.days.map((d) => d.day)).toContain("2026-02-01");
+  });
+
+  it("throws on invalid archived_up_to watermark", () => {
+    store.setMeta(LOG_ARCHIVE_META_KEY, "not-a-date");
+    expect(() => store.archiveLogs({ now: Date.now() })).toThrow();
+  });
+
+  it("runs VACUUM when vacuum: true", () => {
+    const ts = Date.UTC(2026, 1, 1, 10, 0, 0);
+    store.append({ source: "system", type: "x", refId: null, payload: null, ts });
+    const r = store.archiveLogs({
+      now: nowForLastArchivableFeb1(),
+      retentionMs: 30 * DAY_MS,
+      vacuum: true,
+    });
+    expect(r.vacuumed).toBe(true);
+  });
+});

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

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

packages/daemon/src/daemon-ipc.ts

@@ -0,0 +1,167 @@
+/**
+ * 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)
+ */
+
+import { rmSync } from "node:fs";
+import { type Server, type Socket, createServer } from "node:net";
+
+import type { WorkflowManager } from "./workflow-manager.js";
+
+/** JSON message sent by the CLI to trigger a workflow. */
+export type TriggerWorkflowRequest = {
+  type: "trigger-workflow";
+  workflow: string;
+  payload: unknown;
+};
+
+/** 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";
+};
+
+/** Runtime info about a single sense returned by list-senses. */
+export type SenseInfo = {
+  name: string;
+  group: string;
+  throttle: number | null;
+  timeout: number | null;
+  lastSignalTs: number | null;
+};
+
+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 = JSON.parse(line) as unknown;
+    if (obj === null || typeof obj !== "object") return null;
+    const req = obj as Record<string, unknown>;
+    if (req.type === "trigger-workflow") {
+      if (typeof req.workflow !== "string" || req.workflow.length === 0) return null;
+      return { type: "trigger-workflow", workflow: req.workflow, payload: req.payload ?? {} };
+    }
+    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;
+  /** Called when a list-senses request arrives. Returns sense info for all registered senses. */
+  listSenses: () => SenseInfo[];
+};
+
+export function createDaemonIpcServer(
+  socketPath: string,
+  workflowManager: WorkflowManager,
+  opts: DaemonIpcServerOptions,
+): DaemonIpcServer {
+  // Remove stale socket file if it exists
+  try {
+    rmSync(socketPath);
+  } catch {
+    // file did not exist — that is fine
+  }
+
+  function handleLine(socket: Socket, line: string): void {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) return;
+
+    const req = parseRequest(trimmed);
+    if (req === null) {
+      const resp: DaemonResponse = { ok: false, error: "Invalid request" };
+      socket.write(`${JSON.stringify(resp)}\n`);
+      return;
+    }
+
+    try {
+      if (req.type === "trigger-workflow") {
+        workflowManager.startWorkflow(req.workflow, req.payload);
+        const resp: DaemonResponse = { ok: true };
+        socket.write(`${JSON.stringify(resp)}\n`);
+      } else if (req.type === "trigger-sense") {
+        opts.triggerSense(req.sense);
+        const resp: DaemonResponse = { ok: true };
+        socket.write(`${JSON.stringify(resp)}\n`);
+      } else if (req.type === "list-senses") {
+        const senses = opts.listSenses();
+        const resp: DaemonResponse = { ok: true, senses };
+        socket.write(`${JSON.stringify(resp)}\n`);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const resp: DaemonResponse = { ok: false, error: msg };
+      socket.write(`${JSON.stringify(resp)}\n`);
+    }
+  }
+
+  const server: Server = createServer((socket) => {
+    let buf = "";
+
+    socket.on("data", (chunk: Buffer) => {
+      buf += chunk.toString("utf8");
+      const lines = buf.split("\n");
+      buf = lines.pop() ?? "";
+
+      for (const line of lines) {
+        handleLine(socket, line);
+      }
+    });
+
+    socket.on("error", () => {
+      // client disconnected mid-message — ignore
+    });
+  });
+
+  server.listen(socketPath, () => {
+    process.stderr.write(`[daemon-ipc] listening on ${socketPath}\n`);
+  });
+
+  server.on("error", (err) => {
+    process.stderr.write(`[daemon-ipc] server error: ${err.message}\n`);
+  });
+
+  async function close(): Promise<void> {
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+    try {
+      rmSync(socketPath);
+    } catch {
+      // already removed
+    }
+  }
+
+  return { close };
+}

packages/daemon/src/index.ts

@@ -32,8 +32,17 @@ export type { Kernel, KernelOptions, KernelHealth } from "./kernel.js";
 export { createFileWatcher } from "./file-watcher.js";
 export type { FileWatcher, FileChange, FileChangeHandler } from "./file-watcher.js";
 
-export { createLogStore } from "./log-store.js";
-export type { LogStore, LogEntry, LogQuery, WorkflowRun, WorkflowRunStatus } from "./log-store.js";
+export { createLogStore, LOG_ARCHIVE_META_KEY } from "./log-store.js";
+export type {
+  LogStore,
+  LogEntry,
+  LogQuery,
+  WorkflowRun,
+  WorkflowRunStatus,
+  ArchiveLogsDayResult,
+  ArchiveLogsOptions,
+  ArchiveLogsResult,
+} from "./log-store.js";
 
 export { createWorkflowManager } from "./workflow-manager.js";
 export type { WorkflowManager } from "./workflow-manager.js";

packages/daemon/src/kernel.ts

@@ -21,6 +21,8 @@ import { fileURLToPath } from "node:url";
 import type { NerveConfig, Signal } from "@uncaged/nerve-core";
 import { parseNerveConfig } from "@uncaged/nerve-core";
 
+import { createDaemonIpcServer } from "./daemon-ipc.js";
+import type { DaemonIpcServer, SenseInfo } from "./daemon-ipc.js";
 import { createFileWatcher } from "./file-watcher.js";
 import type { FileWatcher } from "./file-watcher.js";
 import type { ComputeMessage, ShutdownMessage } from "./ipc.js";
@@ -56,6 +58,11 @@ export type Kernel = {
   getWorkerPid: (group: string) => number | null;
   /** Sends a compute message to the worker responsible for the given sense. */
   triggerCompute: (senseName: string) => void;
+  /**
+   * On-demand sense trigger — looks up the group for `senseName`, finds its worker,
+   * and sends a compute message. Throws if the sense is unknown.
+   */
+  triggerSense: (senseName: string) => void;
   /** Gracefully restart a group worker (wait for exit, then respawn). */
   restartGroup: (group: string) => Promise<void>;
   /** Reload config from a new NerveConfig, incrementally updating scheduler and workers.
@@ -78,9 +85,12 @@ function resolveWorkerScript(): string {
 }
 
 function spawnWorker(nerveRoot: string, group: string, workerScript: string): ChildProcess {
-  return fork(workerScript, ["--group", group, "--root", nerveRoot], {
+  const child = fork(workerScript, ["--group", group, "--root", nerveRoot], {
     stdio: ["ignore", "inherit", "inherit", "ipc"],
   });
+  // Prevent unhandled EPIPE when writing to a child whose IPC channel closed
+  child.on("error", () => {});
+  return child;
 }
 
 function sendCompute(worker: ChildProcess, senseName: string): void {
@@ -111,10 +121,15 @@ function groupForSense(config: NerveConfig, senseName: string): string | null {
 }
 
 export type KernelOptions = {
-  workerScript: string;
+  workerScript?: string | null;
   enableFileWatcher?: boolean;
   /** Override the LogStore instance (useful for testing). */
   logStore?: LogStore;
+  /**
+   * Unix socket path for the daemon IPC server (used by CLI to send trigger-workflow).
+   * When null, the IPC server is not started (e.g. during tests).
+   */
+  ipcSocketPath?: string | null;
 };
 
 function defaultKernelOptions(): KernelOptions {
@@ -127,7 +142,7 @@ export function createKernel(
   options: KernelOptions = defaultKernelOptions(),
 ): Kernel {
   const bus: SignalBus = createSignalBus();
-  const workerScript = options.workerScript;
+  const workerScript = options.workerScript ?? resolveWorkerScript();
   const startTime = Date.now();
   const logStore: LogStore = options.logStore ?? createLogStore(join(nerveRoot, "data", "logs.db"));
 
@@ -273,6 +288,18 @@ export function createKernel(
     sendCompute(entry.process, senseName);
   }
 
+  function triggerSense(senseName: string): void {
+    const group = groupForSense(config, senseName);
+    if (group === null) {
+      throw new Error(`Unknown sense: "${senseName}"`);
+    }
+    const entry = workers.get(group);
+    if (entry === undefined) {
+      throw new Error(`No worker running for group "${group}" (sense: "${senseName}")`);
+    }
+    sendCompute(entry.process, senseName);
+  }
+
   scheduler = createReflexScheduler(config, bus, triggerFn, {
     logStore,
     workflowTriggerFn: (workflowName, payload) => {
@@ -490,12 +517,40 @@ export function createKernel(
     });
   }
 
+  let ipcServer: DaemonIpcServer | null = null;
+  if (options.ipcSocketPath != null) {
+    ipcServer = createDaemonIpcServer(options.ipcSocketPath, workflowManager, {
+      triggerSense,
+      listSenses(): SenseInfo[] {
+        return Object.entries(config.senses).map(([name, senseConfig]) => {
+          const entries = logStore.query({
+            source: "reflex",
+            type: "run_complete",
+            refId: name,
+          });
+          const lastEntry = entries.length > 0 ? entries[entries.length - 1] : null;
+          return {
+            name,
+            group: senseConfig.group,
+            throttle: senseConfig.throttle,
+            timeout: senseConfig.timeout,
+            lastSignalTs: lastEntry !== null ? lastEntry.ts : null,
+          };
+        });
+      },
+    });
+  }
+
   async function stop(): Promise<void> {
     stopped = true;
     if (fileWatcher !== null) {
       fileWatcher.close();
       fileWatcher = null;
     }
+    if (ipcServer !== null) {
+      await ipcServer.close();
+      ipcServer = null;
+    }
     scheduler.stop();
     await workflowManager.stop();
     const exitPromises: Promise<void>[] = [];
@@ -530,6 +585,7 @@ export function createKernel(
     ready,
     getWorkerPid,
     triggerCompute: triggerFn,
+    triggerSense,
     restartGroup,
     reloadConfig,
     getHealth,

packages/daemon/src/log-archive.ts

@@ -0,0 +1,78 @@
+/** Log cold-archive helpers (RFC-001 §5.4) — UTC calendar days, JSONL export. */
+
+export const LOG_ARCHIVE_META_KEY = "archived_up_to";
+
+export const DEFAULT_LOG_RETENTION_MS = 30 * 86_400_000;
+
+export type ArchiveLogsOptions = {
+  /** Wall clock for retention boundary (default: `Date.now()`). */
+  now?: number;
+  /** Run `VACUUM` after archiving (outside the per-day transaction). */
+  vacuum?: boolean;
+  /** Max UTC days to process in one call (default: unlimited). */
+  maxDays?: number;
+  /** Override default 30-day retention (tests). */
+  retentionMs?: number;
+};
+
+export type ArchiveLogsDayResult = {
+  day: string;
+  rowCount: number;
+  filePath: string;
+};
+
+export type ArchiveLogsResult = {
+  days: ArchiveLogsDayResult[];
+  vacuumed: boolean;
+};
+
+export function utcDateStringFromMs(ms: number): string {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+function parseUtcDayParts(day: string): [number, number, number] {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(day);
+  if (m === null) {
+    throw new Error(`Invalid UTC day (expected YYYY-MM-DD): ${day}`);
+  }
+  const y = Number(m[1]);
+  const mo = Number(m[2]);
+  const d = Number(m[3]);
+  const t = Date.UTC(y, mo - 1, d);
+  if (utcDateStringFromMs(t) !== day) {
+    throw new Error(`Invalid UTC calendar day: ${day}`);
+  }
+  return [y, mo, d];
+}
+
+export function assertValidUtcDay(day: string): void {
+  parseUtcDayParts(day);
+}
+
+export function utcDayStartMs(day: string): number {
+  const [y, mo, d] = parseUtcDayParts(day);
+  return Date.UTC(y, mo - 1, d);
+}
+
+export function utcDayEndExclusiveMs(day: string): number {
+  return utcDayStartMs(day) + 86_400_000;
+}
+
+export function prevUtcDay(day: string): string {
+  return utcDateStringFromMs(utcDayStartMs(day) - 86_400_000);
+}
+
+export function nextUtcDay(day: string): string {
+  return utcDateStringFromMs(utcDayEndExclusiveMs(day));
+}
+
+/** Last UTC calendar day D such that the exclusive end of D is ≤ boundaryMs. */
+export function lastArchivableUtcDay(boundaryMs: number): string {
+  return prevUtcDay(utcDateStringFromMs(boundaryMs));
+}
+
+export function compareIsoDays(a: string, b: string): number {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}

packages/daemon/src/log-store.ts

@@ -7,11 +7,27 @@
  * Also provides a `meta` key-value table for bookkeeping (e.g. archive watermarks).
  */
 
-import { mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import Database from "better-sqlite3";
 import type BetterSqlite3 from "better-sqlite3";
 
+import {
+  DEFAULT_LOG_RETENTION_MS,
+  LOG_ARCHIVE_META_KEY,
+  assertValidUtcDay,
+  compareIsoDays,
+  lastArchivableUtcDay,
+  nextUtcDay,
+  utcDateStringFromMs,
+  utcDayEndExclusiveMs,
+  utcDayStartMs,
+} from "./log-archive.js";
+import type { ArchiveLogsDayResult, ArchiveLogsOptions, ArchiveLogsResult } from "./log-archive.js";
+
+export { LOG_ARCHIVE_META_KEY } from "./log-archive.js";
+export type { ArchiveLogsDayResult, ArchiveLogsOptions, ArchiveLogsResult } from "./log-archive.js";
+
 export type LogEntry = {
   id?: number;
   source: string;
@@ -90,6 +106,11 @@ export type LogStore = {
    * Optionally filter by workflow name.
    */
   getActiveWorkflowRuns: (workflowName?: string) => WorkflowRun[];
+  /**
+   * Get all workflow runs regardless of status, sorted by ts descending.
+   * Optionally filter by workflow name.
+   */
+  getAllWorkflowRuns: (workflowName: string | null) => WorkflowRun[];
   /**
    * Get the trigger payload for a workflow run (stored in the 'started' log entry).
    * Returns null if not found.
@@ -100,6 +121,12 @@ export type LogStore = {
    * Used for crash recovery to rebuild ThreadState.
    */
   getThreadEvents: (runId: string) => Array<{ type: string; [key: string]: unknown }>;
+  /**
+   * Export logs older than the retention window to `data/archive/logs/YYYY-MM-DD.jsonl`,
+   * then delete those rows and advance `meta.archived_up_to` in one transaction per day
+   * (RFC-001 §5.4).
+   */
+  archiveLogs: (options?: ArchiveLogsOptions) => ArchiveLogsResult;
   close: () => void;
 };
 
@@ -133,6 +160,78 @@ CREATE INDEX IF NOT EXISTS idx_workflow_runs_status ON workflow_runs(status);
 CREATE INDEX IF NOT EXISTS idx_workflow_runs_workflow ON workflow_runs(workflow);
 `;
 
+type SqlLogRow = {
+  id: number;
+  source: string;
+  type: string;
+  ref_id: string | null;
+  payload: string | null;
+  ts: number;
+};
+
+function buildJsonlBody(rows: SqlLogRow[]): string {
+  if (rows.length === 0) return "";
+  const lines = rows.map((r) =>
+    JSON.stringify({
+      id: r.id,
+      source: r.source,
+      type: r.type,
+      refId: r.ref_id,
+      payload: r.payload,
+      ts: r.ts,
+    }),
+  );
+  return `${lines.join("\n")}\n`;
+}
+
+function runOptionalVacuum(sqlite: BetterSqlite3.Database, vacuum?: boolean): boolean {
+  if (vacuum !== true) return false;
+  sqlite.exec("VACUUM");
+  return true;
+}
+
+function resolveArchiveStartDay(watermark: string | null, minDay: string): string {
+  if (watermark === null) return minDay;
+  const afterWatermark = nextUtcDay(watermark);
+  return compareIsoDays(minDay, afterWatermark) < 0 ? minDay : afterWatermark;
+}
+
+function runArchiveDayLoop(
+  dbPath: string,
+  options: ArchiveLogsOptions,
+  selectLogsForDayStmt: BetterSqlite3.Statement,
+  archiveDayTx: (day: string, start: number, endExclusive: number) => void,
+  startDay: string,
+  lastDay: string,
+): ArchiveLogsDayResult[] {
+  const archiveDir = join(dirname(dbPath), "archive", "logs");
+  mkdirSync(archiveDir, { recursive: true });
+
+  const days: ArchiveLogsDayResult[] = [];
+  let d = startDay;
+  let processed = 0;
+
+  while (compareIsoDays(d, lastDay) <= 0) {
+    if (options.maxDays !== undefined && processed >= options.maxDays) {
+      break;
+    }
+
+    const start = utcDayStartMs(d);
+    const endExclusive = utcDayEndExclusiveMs(d);
+    const rows = selectLogsForDayStmt.all({ start, endExclusive }) as SqlLogRow[];
+
+    const filePath = join(archiveDir, `${d}.jsonl`);
+    writeFileSync(filePath, buildJsonlBody(rows), "utf8");
+    archiveDayTx(d, start, endExclusive);
+
+    days.push({ day: d, rowCount: rows.length, filePath });
+    processed += 1;
+    d = nextUtcDay(d);
+  }
+
+  return days;
+}
+
 export function createLogStore(dbPath: string): LogStore {
   mkdirSync(dirname(dbPath), { recursive: true });
 
@@ -173,6 +272,22 @@ export function createLogStore(dbPath: string): LogStore {
     "SELECT run_id, workflow, status, ts FROM workflow_runs WHERE status IN ('queued', 'started') AND workflow = ? ORDER BY ts ASC",
   );
 
+  const getAllWorkflowRunsStmt = sqlite.prepare(
+    "SELECT run_id, workflow, status, ts FROM workflow_runs ORDER BY ts DESC",
+  );
+
+  const getAllWorkflowRunsByNameStmt = sqlite.prepare(
+    "SELECT run_id, workflow, status, ts FROM workflow_runs WHERE workflow = ? ORDER BY ts DESC",
+  );
+
+  const minLogTsStmt = sqlite.prepare("SELECT MIN(ts) AS m FROM logs");
+  const selectLogsForDayStmt = sqlite.prepare(
+    "SELECT id, source, type, ref_id, payload, ts FROM logs WHERE ts >= @start AND ts < @endExclusive ORDER BY id ASC",
+  );
+  const deleteLogsForDayStmt = sqlite.prepare(
+    "DELETE FROM logs WHERE ts >= @start AND ts < @endExclusive",
+  );
+
   const upsertWorkflowRunTx = sqlite.transaction(
     (entry: Omit<LogEntry, "id">, run: WorkflowRun) => {
       const info = insertStmt.run({
@@ -295,6 +410,20 @@ export function createLogStore(dbPath: string): LogStore {
     }));
   }
 
+  function getAllWorkflowRuns(workflowName: string | null): WorkflowRun[] {
+    const rows = (
+      workflowName !== null
+        ? getAllWorkflowRunsByNameStmt.all(workflowName)
+        : getAllWorkflowRunsStmt.all()
+    ) as Array<{ run_id: string; workflow: string; status: string; ts: number }>;
+    return rows.map((r) => ({
+      runId: r.run_id,
+      workflow: r.workflow,
+      status: validateWorkflowRunStatus(r.status),
+      ts: r.ts,
+    }));
+  }
+
   function getTriggerPayload(runId: string): unknown {
     const row = getTriggerPayloadStmt.get(runId) as { payload: string | null } | undefined;
     if (row === undefined || row.payload === null) return null;
@@ -331,6 +460,52 @@ export function createLogStore(dbPath: string): LogStore {
     return result;
   }
 
+  const archiveDayTx = sqlite.transaction((day: string, start: number, endExclusive: number) => {
+    deleteLogsForDayStmt.run({ start, endExclusive });
+    setMetaStmt.run({ key: LOG_ARCHIVE_META_KEY, value: day });
+  });
+
+  function readWatermark(): string | null {
+    const raw = getMeta(LOG_ARCHIVE_META_KEY);
+    if (raw === null) return null;
+    assertValidUtcDay(raw);
+    return raw;
+  }
+
+  function firstLogUtcDay(): string | null {
+    const row = minLogTsStmt.get() as { m: number | null } | undefined;
+    const m = row?.m;
+    if (m === null || m === undefined) return null;
+    return utcDateStringFromMs(m);
+  }
+
+  function archiveLogs(options: ArchiveLogsOptions = {}): ArchiveLogsResult {
+    const now = options.now ?? Date.now();
+    const retentionMs = options.retentionMs ?? DEFAULT_LOG_RETENTION_MS;
+    const lastDay = lastArchivableUtcDay(now - retentionMs);
+
+    const watermark = readWatermark();
+    const minDay = firstLogUtcDay();
+    if (minDay === null) {
+      return { days: [], vacuumed: runOptionalVacuum(sqlite, options.vacuum) };
+    }
+
+    const startDay = resolveArchiveStartDay(watermark, minDay);
+    if (compareIsoDays(startDay, lastDay) > 0) {
+      return { days: [], vacuumed: runOptionalVacuum(sqlite, options.vacuum) };
+    }
+
+    const days = runArchiveDayLoop(
+      dbPath,
+      options,
+      selectLogsForDayStmt,
+      archiveDayTx,
+      startDay,
+      lastDay,
+    );
+    return { days, vacuumed: runOptionalVacuum(sqlite, options.vacuum) };
+  }
+
   function close(): void {
     sqlite.close();
   }
@@ -344,8 +519,10 @@ export function createLogStore(dbPath: string): LogStore {
     appendWithWorkflowUpdate,
     getWorkflowRun,
     getActiveWorkflowRuns,
+    getAllWorkflowRuns,
     getTriggerPayload,
     getThreadEvents,
+    archiveLogs,
     close,
   };
 }

packages/daemon/src/workflow-manager.ts

@@ -86,9 +86,12 @@ function spawnWorkflowWorker(
   workflowName: string,
   workerScript: string,
 ): ChildProcess {
-  return fork(workerScript, ["--workflow", workflowName, "--root", nerveRoot], {
+  const child = fork(workerScript, ["--workflow", workflowName, "--root", nerveRoot], {
     stdio: ["ignore", "inherit", "inherit", "ipc"],
   });
+  // Prevent unhandled EPIPE when writing to a child whose IPC channel closed
+  child.on("error", () => {});
+  return child;
 }
 
 function sendStartThread(worker: ChildProcess, msg: StartThreadMessage): void {

pnpm-lock.yaml

@@ -23,16 +23,22 @@ importers:
       '@uncaged/nerve-core':
         specifier: workspace:*
         version: link:../core
-      '@uncaged/nerve-daemon':
-        specifier: workspace:*
-        version: link:../daemon
       citty:
         specifier: ^0.1.6
         version: 0.1.6
     devDependencies:
+      '@types/better-sqlite3':
+        specifier: ^7.6.13
+        version: 7.6.13
       '@types/node':
         specifier: ^22.0.0
         version: 22.19.17
+      '@uncaged/nerve-daemon':
+        specifier: workspace:*
+        version: link:../daemon
+      vitest:
+        specifier: ^4.1.5
+        version: 4.1.5(@types/node@22.19.17)(vite@8.0.9(@types/node@22.19.17)(esbuild@0.27.7)(yaml@2.8.3))
 
   packages/core:
     dependencies:
@@ -1579,6 +1585,14 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.1.0
 
+  '@vitest/mocker@4.1.5(vite@8.0.9(@types/node@22.19.17)(esbuild@0.27.7)(yaml@2.8.3))':
+    dependencies:
+      '@vitest/spy': 4.1.5
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 8.0.9(@types/node@22.19.17)(esbuild@0.27.7)(yaml@2.8.3)
+
   '@vitest/mocker@4.1.5(vite@8.0.9(@types/node@25.6.0)(esbuild@0.27.7)(yaml@2.8.3))':
     dependencies:
       '@vitest/spy': 4.1.5
@@ -2089,6 +2103,19 @@ snapshots:
 
   util-deprecate@1.0.2: {}
 
+  vite@8.0.9(@types/node@22.19.17)(esbuild@0.27.7)(yaml@2.8.3):
+    dependencies:
+      lightningcss: 1.32.0
+      picomatch: 4.0.4
+      postcss: 8.5.10
+      rolldown: 1.0.0-rc.16
+      tinyglobby: 0.2.16
+    optionalDependencies:
+      '@types/node': 22.19.17
+      esbuild: 0.27.7
+      fsevents: 2.3.3
+      yaml: 2.8.3
+
   vite@8.0.9(@types/node@25.6.0)(esbuild@0.27.7)(yaml@2.8.3):
     dependencies:
       lightningcss: 1.32.0
@@ -2102,6 +2129,33 @@ snapshots:
       fsevents: 2.3.3
       yaml: 2.8.3
 
+  vitest@4.1.5(@types/node@22.19.17)(vite@8.0.9(@types/node@22.19.17)(esbuild@0.27.7)(yaml@2.8.3)):
+    dependencies:
+      '@vitest/expect': 4.1.5
+      '@vitest/mocker': 4.1.5(vite@8.0.9(@types/node@22.19.17)(esbuild@0.27.7)(yaml@2.8.3))
+      '@vitest/pretty-format': 4.1.5
+      '@vitest/runner': 4.1.5
+      '@vitest/snapshot': 4.1.5
+      '@vitest/spy': 4.1.5
+      '@vitest/utils': 4.1.5
+      es-module-lexer: 2.0.0
+      expect-type: 1.3.0
+      magic-string: 0.30.21
+      obug: 2.1.1
+      pathe: 2.0.3
+      picomatch: 4.0.4
+      std-env: 4.1.0
+      tinybench: 2.9.0
+      tinyexec: 1.1.1
+      tinyglobby: 0.2.16
+      tinyrainbow: 3.1.0
+      vite: 8.0.9(@types/node@22.19.17)(esbuild@0.27.7)(yaml@2.8.3)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@types/node': 22.19.17
+    transitivePeerDependencies:
+      - msw
+
   vitest@4.1.5(@types/node@25.6.0)(vite@8.0.9(@types/node@25.6.0)(esbuild@0.27.7)(yaml@2.8.3)):
     dependencies:
       '@vitest/expect': 4.1.5