fix(init): auto-verify and retry better-sqlite3 native build

After pnpm install, verify better-sqlite3 actually loads by spawning
a test process. If it fails, rebuild up to 2 times. On final failure,
print actionable fix commands instead of a vague warning.

Closes #44

packages/cli/package.json

@@ -1,23 +1,28 @@
 {
   "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",
     "test": "vitest run"
   },
   "dependencies": {
     "@uncaged/nerve-core": "workspace:*",
-    "@uncaged/nerve-daemon": "workspace:*",
     "citty": "^0.1.6"
   },
   "devDependencies": {
+    "@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,47 @@
+/**
+ * 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 {
+  LogEntry as DaemonLogEntry,
+  LogQuery as DaemonLogQuery,
+  LogStore as DaemonLogStore,
+  WorkflowRun as DaemonWorkflowRun,
+  WorkflowRunStatus as DaemonWorkflowRunStatus,
+} from "@uncaged/nerve-daemon";
+import { describe, it, expectTypeOf } from "vitest";
+
+import type {
+  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" | "close">>();
+  });
+});

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

@@ -9,33 +9,7 @@ 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";
-
-// Inline the template builder (same logic as in init.ts) for isolated testing
-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;
-`;
-}
+import { buildWorkflowTemplate } from "../commands/init.js";
 
 let tmpDir: string;
 

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

@@ -13,7 +13,6 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { createLogStore } from "@uncaged/nerve-daemon";
-import type { LogStore, WorkflowRun } from "@uncaged/nerve-daemon";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import {
@@ -25,6 +24,7 @@ import {
   statusIcon,
 } from "../commands/workflow.js";
 import { triggerWorkflowViaDaemon } from "../daemon-client.js";
+import type { LogStore, WorkflowRun } from "../daemon-types.js";
 
 // ---------------------------------------------------------------------------
 // Test helpers

packages/cli/src/cli.ts

@@ -1,8 +1,8 @@
-#!/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";
@@ -19,7 +19,9 @@ const main = defineCommand({
     start: startCommand,
     stop: stopCommand,
     status: statusCommand,
+    logs: logsCommand,
     validate: validateCommand,
+    sense: senseCommand,
     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,13 +109,13 @@ 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 WORKFLOW_NAME_RE = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/;
@@ -124,7 +128,7 @@ export function validateWorkflowName(name: string): string | null {
   return null;
 }
 
-function buildWorkflowTemplate(name: string): string {
+export function buildWorkflowTemplate(name: string): string {
   return `import type { WorkflowDefinition } from "@uncaged/nerve-daemon";
 
 const workflow: WorkflowDefinition = {
@@ -215,6 +219,23 @@ const initWorkspaceCommand = defineCommand({
   },
 });
 
+async function tryRequireSqlite(nerveRoot: string): Promise<boolean> {
+  try {
+    const modulePath = join(nerveRoot, "node_modules", "better-sqlite3");
+    // Use a child process to test if the native module loads
+    const { execFile } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const execFileAsync = promisify(execFile);
+    await execFileAsync("node", ["-e", `require(${JSON.stringify(modulePath)})`], {
+      cwd: nerveRoot,
+      timeout: 10_000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function runInitWorkspace(force: boolean): Promise<void> {
   const nerveRoot = getNerveRoot();
 
@@ -238,16 +259,43 @@ async function runInitWorkspace(force: boolean): Promise<void> {
   );
 
   process.stdout.write("Installing dependencies…\n");
+  const { cmd, installArgs } = await detectPackageManager();
   try {
-    const { cmd, args } = await detectPackageManager();
-    await runCommand(cmd, args, nerveRoot);
+    await runCommand(cmd, installArgs, nerveRoot);
   } catch {
-    process.stdout.write("⚠️ Install failed — you may need to install dependencies manually.\n");
+    process.stdout.write(
+      `⚠️ Install failed. Try manually:\n   cd ${nerveRoot} && ${cmd} ${installArgs.join(" ")}\n`,
+    );
+  }
+
+  // Verify better-sqlite3 native module — rebuild up to 2 times if broken
+  const sqlitePath = join(nerveRoot, "node_modules", "better-sqlite3");
+  if (existsSync(sqlitePath)) {
+    for (let attempt = 1; attempt <= 2; attempt++) {
+      if (await tryRequireSqlite(nerveRoot)) break;
+      process.stdout.write(
+        `${attempt === 1 ? "Building" : "Retrying build of"} native module better-sqlite3 (attempt ${attempt}/2)…\n`,
+      );
+      try {
+        await runCommand(cmd, ["rebuild", "better-sqlite3"], nerveRoot);
+      } catch {
+        // will be caught by the verify below
+      }
+    }
+    if (!(await tryRequireSqlite(nerveRoot))) {
+      process.stdout.write(
+        `⚠️ better-sqlite3 native module is not working. The daemon will fail to start.\n` +
+          `   Fix: cd ${nerveRoot} && ${cmd} rebuild better-sqlite3\n` +
+          `   Or:  npm install --build-from-source better-sqlite3\n`,
+      );
+    }
   }
 
   if (!existsSync(join(nerveRoot, ".git"))) {
     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");
     }

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,88 +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 { runForegroundKernelSession } from "../run-foreground-kernel.js";
+import { loadDaemonModule } from "../workspace-daemon.js";
 import {
   getLogPath,
   getNerveRoot,
-  getSocketPath,
   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, {
-    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;
+  const { createKernel } = await loadDaemonModule(nerveRoot);
+  await runForegroundKernelSession(nerveRoot, createKernel);
 }
 
 async function runDaemon(nerveRoot: string): Promise<void> {
@@ -92,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 });
 
@@ -108,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();
@@ -125,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/workflow.ts

@@ -1,11 +1,11 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
-import { createLogStore } from "@uncaged/nerve-daemon";
-import type { LogStore, WorkflowRun } from "@uncaged/nerve-daemon";
 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;
@@ -23,12 +23,14 @@ export function formatTs(ts: number): string {
   return new Date(ts).toISOString();
 }
 
-function openStore(): LogStore {
+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);
 }
 
@@ -202,7 +204,7 @@ const workflowListCommand = defineCommand({
     },
   },
   async run({ args }) {
-    const store = openStore();
+    const store = await openStore();
 
     try {
       const limit = Math.max(1, parseIntArg(args.limit, DEFAULT_PAGE_SIZE));
@@ -259,7 +261,7 @@ const workflowInspectCommand = defineCommand({
     },
   },
   async run({ args }) {
-    const store = openStore();
+    const store = await openStore();
 
     try {
       const limit = Math.max(1, parseIntArg(args.limit, DEFAULT_PAGE_SIZE));

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

@@ -1,6 +1,6 @@
 /**
  * Daemon IPC client — connects to the daemon's Unix socket and sends
- * a trigger-workflow request.
+ * trigger-workflow or trigger-sense requests.
  *
  * Protocol: newline-delimited JSON (same as daemon-ipc.ts server side).
  */
@@ -13,6 +13,16 @@ 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;
@@ -27,15 +37,7 @@ function parseDaemonResponse(line: string): TriggerResponse {
   return { ok: false, error: `Unexpected daemon response: ${line}` };
 }
 
-/**
- * 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> {
+function sendAndReceive(socketPath: string, message: object): Promise<TriggerResponse> {
   return new Promise((resolve, reject) => {
     let socket: Socket | null = null;
     let settled = false;
@@ -79,7 +81,7 @@ export function triggerWorkflowViaDaemon(
         }
       });
 
-      const msg = `${JSON.stringify({ type: "trigger-workflow", workflow, payload })}\n`;
+      const msg = `${JSON.stringify(message)}\n`;
       socket?.write(msg);
     });
 
@@ -89,3 +91,100 @@ export function triggerWorkflowViaDaemon(
     });
   });
 }
+
+/**
+ * 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,51 @@
+/**
+ * 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;
+};
+
+/** 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;
+  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/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__/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__/kernel-trigger-sense.test.ts

@@ -0,0 +1,199 @@
+/**
+ * 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(() => []),
+    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/daemon-ipc.ts

@@ -1,10 +1,13 @@
 /**
  * Daemon IPC server — listens on a Unix domain socket so that the CLI
- * can send commands (e.g. trigger-workflow) to the running daemon process.
+ * 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";
@@ -19,9 +22,32 @@ export type TriggerWorkflowRequest = {
   payload: unknown;
 };
 
-type DaemonRequest = TriggerWorkflowRequest;
+/** JSON message sent by the CLI to trigger a sense compute on-demand. */
+export type TriggerSenseRequest = {
+  type: "trigger-sense";
+  sense: string;
+};
 
-type DaemonResponse = { ok: true } | { ok: false; error: 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>;
@@ -36,15 +62,30 @@ function parseRequest(line: string): DaemonRequest | null {
       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 {
@@ -64,9 +105,25 @@ export function createDaemonIpcServer(
       return;
     }
 
-    workflowManager.startWorkflow(req.workflow, req.payload);
-    const resp: DaemonResponse = { ok: true };
-    socket.write(`${JSON.stringify(resp)}\n`);
+    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) => {

packages/daemon/src/kernel.ts

@@ -22,7 +22,7 @@ import type { NerveConfig, Signal } from "@uncaged/nerve-core";
 import { parseNerveConfig } from "@uncaged/nerve-core";
 
 import { createDaemonIpcServer } from "./daemon-ipc.js";
-import type { DaemonIpcServer } 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";
@@ -58,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.
@@ -80,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 {
@@ -280,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) => {
@@ -499,7 +519,26 @@ export function createKernel(
 
   let ipcServer: DaemonIpcServer | null = null;
   if (options.ipcSocketPath != null) {
-    ipcServer = createDaemonIpcServer(options.ipcSocketPath, workflowManager);
+    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> {
@@ -546,6 +585,7 @@ export function createKernel(
     ready,
     getWorkerPid,
     triggerCompute: triggerFn,
+    triggerSense,
     restartGroup,
     reloadConfig,
     getHealth,

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,9 +23,6 @@ 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
@@ -36,6 +33,9 @@ importers:
       '@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))