fix: address review feedback (星月)

1. trySendSync: wrap child.send in try/catch — IPC race between connected check and send
2. gracefulStop: same try/catch for shutdown send
3. Remove crashTimestamps reset on ready — crash window detection was being bypassed

.gitignore

@@ -3,3 +3,4 @@ dist
 .turbo
 *.tsbuildinfo
 *.tgz
+knowledge.db

packages/core/src/__tests__/config.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { parseNerveConfig } from "../parse-nerve-config.js";
+import { parseNerveConfig } from "../config.js";
 
 const VALID_CONFIG = `
 senses:

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { parseDaemonIpcRequest } from "../daemon-ipc-protocol.js";
+import { parseDaemonIpcRequest } from "../daemon.js";
 
 describe("parseDaemonIpcRequest", () => {
   it("parses trigger-workflow", () => {

packages/core/src/__tests__/knowledge-config.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { parseKnowledgeYaml } from "../knowledge-config.js";
+import { parseKnowledgeYaml } from "../config.js";
 
 describe("parseKnowledgeYaml", () => {
   it("parses include and exclude glob lists", () => {

packages/core/src/__tests__/sense-workflow-directive.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { parseWorkflowTrigger, routeSenseComputeOutput } from "../sense-workflow-directive.js";
+import { parseWorkflowTrigger, routeSenseComputeOutput } from "../sense.js";
 
 describe("parseWorkflowTrigger", () => {
   it("accepts a valid trigger object", () => {

packages/core/src/__tests__/spawn-safe.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { spawnSafe } from "../spawn-safe.js";
+import { spawnSafe } from "../util.js";
 
 describe("spawnSafe", () => {
   it("passes argv literally without shell interpretation (injection-safe)", async () => {

packages/core/src/agent-adapter-ids.ts

@@ -1,5 +0,0 @@
-/**
- * Agent adapter ids referenced by tooling / docs (RFC-003).
- * Workflows import adapter packages directly; echo may be used in tests via a small factory.
- */
-export const KNOWN_AGENT_ADAPTER_IDS = ["echo", "cursor", "hermes", "codex"] as const;

packages/core/src/agent.ts

@@ -21,3 +21,9 @@ export class ExtractError extends Error {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 }
+
+/**
+ * Agent adapter ids referenced by tooling / docs (RFC-003).
+ * Workflows import adapter packages directly; echo may be used in tests via a small factory.
+ */
+export const KNOWN_AGENT_ADAPTER_IDS = ["echo", "cursor", "hermes", "codex"] as const;

packages/core/src/config.ts

@@ -1,5 +1,7 @@
-/** Default max rows kept in each sense's `_signals` SQLite table (see `retention` on `SenseConfig`). */
-export const DEFAULT_SENSE_SIGNAL_RETENTION = 10_000;
+import { parse } from "yaml";
+
+import { type Result, err, isPlainRecord, ok, parseDurationStringToMs } from "./util.js";
+import { DEFAULT_ENGINE_MAX_ROUNDS } from "./workflow.js";
 
 export type SenseConfig = {
   group: string;
@@ -75,3 +77,398 @@ export type NerveConfig = {
   /** Global extract defaults; `null` when the section is omitted. */
   extract: ExtractConfig | null;
 };
+
+export type KnowledgeConfig = {
+  include: ReadonlyArray<string>;
+  exclude: ReadonlyArray<string>;
+};
+
+/** Default max rows kept in each sense's `_signals` SQLite table (see `retention` on `SenseConfig`). */
+export const DEFAULT_SENSE_SIGNAL_RETENTION = 10_000;
+
+function isValidGroupName(value: string): boolean {
+  return /^[a-zA-Z0-9_-]+$/.test(value);
+}
+
+function parseRetentionField(name: string, field: unknown): Result<number> {
+  if (field === undefined || field === null) {
+    return ok(DEFAULT_SENSE_SIGNAL_RETENTION);
+  }
+  if (typeof field !== "number" || !Number.isInteger(field) || field < 1) {
+    return err(new Error(`senses.${name}.retention: must be a positive integer`));
+  }
+  return ok(field);
+}
+
+function parseDurationField(field: unknown, label: string): Result<number | null> {
+  if (field === undefined || field === null) return ok(null);
+  if (typeof field !== "string") {
+    return err(
+      new Error(`${label}: invalid duration "${field}" (expected e.g. "5s", "10m", "1h")`),
+    );
+  }
+  const msResult = parseDurationStringToMs(field);
+  if (!msResult.ok) {
+    return err(new Error(`${label}: ${msResult.error.message}`));
+  }
+  return ok(msResult.value);
+}
+
+function validateSenseConfig(name: string, raw: unknown): Result<SenseConfig> {
+  if (!isPlainRecord(raw)) {
+    return err(new Error(`senses.${name}: must be an object`));
+  }
+
+  const obj = raw;
+
+  if (typeof obj.group !== "string" || obj.group.trim() === "") {
+    return err(new Error(`senses.${name}.group: required string`));
+  }
+
+  if (!isValidGroupName(obj.group)) {
+    return err(
+      new Error(
+        `senses.${name}.group: invalid name "${obj.group}" (only alphanumeric, underscore, hyphen allowed)`,
+      ),
+    );
+  }
+
+  const throttleResult = parseDurationField(obj.throttle, `senses.${name}.throttle`);
+  if (!throttleResult.ok) return throttleResult;
+
+  const timeoutResult = parseDurationField(obj.timeout, `senses.${name}.timeout`);
+  if (!timeoutResult.ok) return timeoutResult;
+
+  const graceResult = parseDurationField(obj.grace_period, `senses.${name}.grace_period`);
+  if (!graceResult.ok) return graceResult;
+
+  const retentionResult = parseRetentionField(name, obj.retention);
+  if (!retentionResult.ok) return retentionResult;
+
+  const intervalResult = parseDurationField(obj.interval, `senses.${name}.interval`);
+  if (!intervalResult.ok) return intervalResult;
+
+  let on: string[] = [];
+  if (obj.on !== undefined && obj.on !== null) {
+    if (
+      !Array.isArray(obj.on) ||
+      !obj.on.every((item: unknown): item is string => typeof item === "string")
+    ) {
+      return err(new Error(`senses.${name}.on: must be an array of strings`));
+    }
+    on = obj.on;
+  }
+
+  return ok({
+    group: obj.group,
+    throttle: throttleResult.value,
+    timeout: timeoutResult.value,
+    gracePeriod: graceResult.value,
+    retention: retentionResult.value,
+    interval: intervalResult.value,
+    on,
+  });
+}
+
+function parseEngineMaxRounds(obj: Record<string, unknown>): Result<number> {
+  if (obj.max_rounds === undefined || obj.max_rounds === null) {
+    return ok(DEFAULT_ENGINE_MAX_ROUNDS);
+  }
+  if (
+    typeof obj.max_rounds !== "number" ||
+    !Number.isInteger(obj.max_rounds) ||
+    obj.max_rounds < 1
+  ) {
+    return err(new Error("max_rounds: must be a positive integer"));
+  }
+  return ok(obj.max_rounds);
+}
+
+function validateWorkflowConfig(name: string, raw: unknown): Result<WorkflowConfig> {
+  if (!isPlainRecord(raw)) {
+    return err(new Error(`workflows.${name}: must be an object`));
+  }
+
+  const obj = raw;
+
+  if (
+    typeof obj.concurrency !== "number" ||
+    !Number.isInteger(obj.concurrency) ||
+    obj.concurrency < 1
+  ) {
+    return err(new Error(`workflows.${name}.concurrency: must be a positive integer`));
+  }
+
+  if (obj.overflow !== "drop" && obj.overflow !== "queue") {
+    return err(new Error(`workflows.${name}.overflow: must be "drop" or "queue"`));
+  }
+
+  if (obj.overflow === "drop") {
+    if (obj.max_queue !== undefined && obj.max_queue !== null) {
+      return err(new Error(`workflows.${name}: max_queue is not allowed with overflow "drop"`));
+    }
+    return ok({
+      concurrency: obj.concurrency,
+      overflow: "drop" as const,
+    });
+  }
+
+  // overflow: "queue"
+  let maxQueue = 100; // default
+  if (obj.max_queue !== undefined && obj.max_queue !== null) {
+    if (
+      typeof obj.max_queue !== "number" ||
+      !Number.isInteger(obj.max_queue) ||
+      obj.max_queue < 1
+    ) {
+      return err(new Error(`workflows.${name}.max_queue: must be a positive integer`));
+    }
+    maxQueue = obj.max_queue;
+  }
+
+  return ok({
+    concurrency: obj.concurrency,
+    overflow: "queue" as const,
+    maxQueue,
+  });
+}
+
+function parseSenses(
+  obj: Record<string, unknown>,
+): Result<{ senses: Record<string, SenseConfig> }> {
+  if (!isPlainRecord(obj.senses)) {
+    return err(new Error("senses: required object"));
+  }
+
+  const sensesRaw = obj.senses;
+  const senses: Record<string, SenseConfig> = {};
+
+  for (const [name, senseRaw] of Object.entries(sensesRaw)) {
+    const result = validateSenseConfig(name, senseRaw);
+    if (!result.ok) return result;
+    senses[name] = result.value;
+  }
+
+  return ok({ senses });
+}
+
+const DEFAULT_API_BIND_HOST = "127.0.0.1";
+
+/** Hosts that may bind the HTTP API without `api.token` (loopback-only). */
+function isLoopbackOnlyApiHost(host: string): boolean {
+  const h = host.trim();
+  return h === "127.0.0.1" || h.toLowerCase() === "localhost";
+}
+
+function parseApiTokenField(api: Record<string, unknown>): Result<string | null> {
+  if (api.token === undefined || api.token === null) {
+    return ok(null);
+  }
+  if (typeof api.token !== "string") {
+    return err(new Error("api.token: must be a string when provided"));
+  }
+  if (api.token.length === 0) {
+    return err(new Error("api.token: must not be empty when provided"));
+  }
+  return ok(api.token);
+}
+
+function parseApiHostField(api: Record<string, unknown>): Result<string> {
+  if (api.host === undefined || api.host === null) {
+    return ok(DEFAULT_API_BIND_HOST);
+  }
+  if (typeof api.host !== "string") {
+    return err(new Error("api.host: must be a string when provided"));
+  }
+  if (api.host.length === 0) {
+    return err(new Error("api.host: must not be empty when provided"));
+  }
+  return ok(api.host);
+}
+
+function parseApiConfig(obj: Record<string, unknown>): Result<NerveApiConfig> {
+  if (obj.api === undefined || obj.api === null) {
+    return ok({ port: null, token: null, host: DEFAULT_API_BIND_HOST });
+  }
+  if (!isPlainRecord(obj.api)) {
+    return err(new Error("api: must be an object if provided"));
+  }
+  const api = obj.api;
+  if (api.port === undefined || api.port === null) {
+    return ok({ port: null, token: null, host: DEFAULT_API_BIND_HOST });
+  }
+  if (
+    typeof api.port !== "number" ||
+    !Number.isInteger(api.port) ||
+    api.port < 1 ||
+    api.port > 65_535
+  ) {
+    return err(new Error("api.port: must be an integer between 1 and 65535 if provided"));
+  }
+
+  const tokenResult = parseApiTokenField(api);
+  if (!tokenResult.ok) return tokenResult;
+  const hostResult = parseApiHostField(api);
+  if (!hostResult.ok) return hostResult;
+
+  if (!isLoopbackOnlyApiHost(hostResult.value) && tokenResult.value === null) {
+    return err(
+      new Error("api.host binds to non-loopback address, api.token is required for security"),
+    );
+  }
+
+  return ok({ port: api.port, token: tokenResult.value, host: hostResult.value });
+}
+
+function parseWorkflows(obj: Record<string, unknown>): Result<Record<string, WorkflowConfig>> {
+  if (obj.workflows === undefined || obj.workflows === null) return ok({});
+
+  if (!isPlainRecord(obj.workflows)) {
+    return err(new Error("workflows: must be an object if provided"));
+  }
+
+  const workflowsRaw = obj.workflows;
+  const workflows: Record<string, WorkflowConfig> = {};
+
+  for (const [name, wfRaw] of Object.entries(workflowsRaw)) {
+    const result = validateWorkflowConfig(name, wfRaw);
+    if (!result.ok) return result;
+    workflows[name] = result.value;
+  }
+
+  return ok(workflows);
+}
+
+function parseExtract(obj: Record<string, unknown>): Result<ExtractConfig | null> {
+  if (obj.extract === undefined || obj.extract === null) {
+    return ok(null);
+  }
+
+  if (!isPlainRecord(obj.extract)) {
+    return err(new Error("extract: must be an object if provided"));
+  }
+
+  const ext = obj.extract;
+
+  if (typeof ext.provider !== "string" || ext.provider.trim() === "") {
+    return err(new Error("extract.provider: required non-empty string"));
+  }
+
+  if (typeof ext.model !== "string" || ext.model.trim() === "") {
+    return err(new Error("extract.model: required non-empty string"));
+  }
+
+  return ok({ provider: ext.provider, model: ext.model });
+}
+
+export function parseNerveConfig(raw: string): Result<NerveConfig> {
+  let parsed: unknown;
+
+  try {
+    parsed = parse(raw);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return err(new Error(`YAML parse error: ${message}`));
+  }
+
+  if (!isPlainRecord(parsed)) {
+    return err(new Error("Config must be a YAML object"));
+  }
+
+  const obj = parsed;
+
+  const sensesResult = parseSenses(obj);
+  if (!sensesResult.ok) return sensesResult;
+  const { senses } = sensesResult.value;
+
+  // Legacy top-level `reflexes` is rejected; each sense carries `interval` / `on` for the sense scheduler.
+  if (Object.hasOwn(obj, "reflexes")) {
+    return err(
+      new Error(
+        "reflexes: top-level key is no longer supported; set `interval` and `on` on each sense under `senses.<name>`",
+      ),
+    );
+  }
+
+  const workflowsResult = parseWorkflows(obj);
+  if (!workflowsResult.ok) return workflowsResult;
+
+  const maxRoundsResult = parseEngineMaxRounds(obj);
+  if (!maxRoundsResult.ok) return maxRoundsResult;
+
+  const apiResult = parseApiConfig(obj);
+  if (!apiResult.ok) return apiResult;
+
+  if (Object.hasOwn(obj, "agents")) {
+    return err(
+      new Error(
+        "agents: key is no longer supported — declare adapters on workflow roles (RFC-003)",
+      ),
+    );
+  }
+
+  const extractResult = parseExtract(obj);
+  if (!extractResult.ok) return extractResult;
+
+  return ok({
+    maxRounds: maxRoundsResult.value,
+    senses,
+    workflows: workflowsResult.value,
+    api: apiResult.value,
+    extract: extractResult.value,
+  });
+}
+
+function parseStringList(field: unknown, label: string): Result<ReadonlyArray<string>> {
+  if (field === undefined || field === null) {
+    return ok([]);
+  }
+  if (!Array.isArray(field)) {
+    return err(new Error(`${label}: must be an array of strings`));
+  }
+  const out: string[] = [];
+  for (let i = 0; i < field.length; i++) {
+    const item = field[i];
+    if (typeof item !== "string" || item.length === 0) {
+      return err(new Error(`${label}[${String(i)}]: must be a non-empty string`));
+    }
+    out.push(item);
+  }
+  return ok(out);
+}
+
+/**
+ * Parse `knowledge.yaml` at the repo root (RFC-003 Knowledge Layer).
+ * `include` / `exclude` entries are glob patterns resolved against the repo root.
+ */
+export function parseKnowledgeYaml(raw: string): Result<KnowledgeConfig> {
+  let parsed: unknown;
+  try {
+    parsed = parse(raw);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return err(new Error(`YAML parse error: ${message}`));
+  }
+
+  if (parsed === undefined || parsed === null) {
+    return ok({ include: [], exclude: [] });
+  }
+
+  if (!isPlainRecord(parsed)) {
+    return err(new Error("knowledge.yaml: root must be a mapping"));
+  }
+
+  const includeResult = parseStringList(parsed.include, "include");
+  if (!includeResult.ok) {
+    return includeResult;
+  }
+  const excludeResult = parseStringList(parsed.exclude, "exclude");
+  if (!excludeResult.ok) {
+    return excludeResult;
+  }
+
+  return ok({
+    include: includeResult.value,
+    exclude: excludeResult.value,
+  });
+}

packages/core/src/daemon-payload-guards.ts

@@ -1,33 +0,0 @@
-import type { WorkflowStatus } from "./daemon-ipc-protocol.js";
-import { isPlainRecord } from "./is-plain-record.js";
-import type { SenseInfo } from "./sense.js";
-
-/** Type guard for JSON {@link SenseInfo} payloads from daemon HTTP/IPC. */
-export function isSenseInfo(value: unknown): value is SenseInfo {
-  if (!isPlainRecord(value)) return false;
-  return (
-    typeof value.name === "string" &&
-    typeof value.group === "string" &&
-    (value.throttle === null || typeof value.throttle === "number") &&
-    (value.timeout === null || typeof value.timeout === "number") &&
-    Array.isArray(value.triggers) &&
-    value.triggers.every((t: unknown) => typeof t === "string") &&
-    (value.lastSignalTimestamp === null || typeof value.lastSignalTimestamp === "number")
-  );
-}
-
-/** Type guard for JSON {@link WorkflowStatus} payloads from daemon HTTP/IPC. */
-export function isWorkflowStatus(value: unknown): value is WorkflowStatus {
-  if (!isPlainRecord(value)) return false;
-  const cfg = value.config;
-  if (!isPlainRecord(cfg)) return false;
-  return (
-    typeof value.name === "string" &&
-    typeof value.activeThreads === "number" &&
-    Array.isArray(value.activeRunIds) &&
-    value.activeRunIds.every((id: unknown) => typeof id === "string") &&
-    typeof value.queuedThreads === "number" &&
-    typeof cfg.concurrency === "number" &&
-    typeof cfg.overflow === "string"
-  );
-}

packages/core/src/daemon-transport.ts

@@ -1,28 +0,0 @@
-import type { HealthInfo, WorkflowStatus } from "./daemon-ipc-protocol.js";
-import type { SenseInfo } from "./sense.js";
-
-export type DaemonTransportTriggerResult = { ok: true } | { ok: false; error: string };
-
-export type DaemonTransportWorkflowLaunch = {
-  prompt: string;
-  maxRounds: number;
-  dryRun: boolean;
-};
-
-/**
- * Abstraction over daemon control plane (Unix socket IPC today, HTTP in Phase 2).
- * Implementations live in CLI / tools; the daemon kernel uses shared handler logic.
- */
-export type DaemonTransport = {
-  health(): Promise<HealthInfo>;
-  listSenses(): Promise<SenseInfo[]>;
-  listWorkflows(): Promise<WorkflowStatus[]>;
-  triggerSense(name: string): Promise<DaemonTransportTriggerResult>;
-  /** When `launch` is null, implementations use engine defaults (empty prompt, default max rounds, dryRun false). */
-  triggerWorkflow(
-    name: string,
-    launch: DaemonTransportWorkflowLaunch | null,
-  ): Promise<DaemonTransportTriggerResult>;
-  /** Kill a running or queued workflow thread by `runId` (same field as IPC `kill-workflow`). */
-  killWorkflow(runId: string): Promise<DaemonTransportTriggerResult>;
-};

packages/core/src/daemon.ts

@@ -4,8 +4,8 @@
  * one response object per line from the daemon.
  */
 
-import { isPlainRecord } from "./is-plain-record.js";
 import type { SenseInfo } from "./sense.js";
+import { isPlainRecord } from "./util.js";
 
 /** Runtime status of a registered workflow (for listing / observability). */
 export type WorkflowStatus = {
@@ -100,6 +100,32 @@ export type DaemonIpcResponse =
   | DaemonIpcListWorkflowsResponse
   | DaemonIpcHealthResponse;
 
+export type DaemonTransportTriggerResult = { ok: true } | { ok: false; error: string };
+
+export type DaemonTransportWorkflowLaunch = {
+  prompt: string;
+  maxRounds: number;
+  dryRun: boolean;
+};
+
+/**
+ * Abstraction over daemon control plane (Unix socket IPC today, HTTP in Phase 2).
+ * Implementations live in CLI / tools; the daemon kernel uses shared handler logic.
+ */
+export type DaemonTransport = {
+  health(): Promise<HealthInfo>;
+  listSenses(): Promise<SenseInfo[]>;
+  listWorkflows(): Promise<WorkflowStatus[]>;
+  triggerSense(name: string): Promise<DaemonTransportTriggerResult>;
+  /** When `launch` is null, implementations use engine defaults (empty prompt, default max rounds, dryRun false). */
+  triggerWorkflow(
+    name: string,
+    launch: DaemonTransportWorkflowLaunch | null,
+  ): Promise<DaemonTransportTriggerResult>;
+  /** Kill a running or queued workflow thread by `runId` (same field as IPC `kill-workflow`). */
+  killWorkflow(runId: string): Promise<DaemonTransportTriggerResult>;
+};
+
 function parseTriggerWorkflowFields(
   req: Record<string, unknown>,
 ): DaemonIpcTriggerWorkflowRequest | null {
@@ -150,3 +176,33 @@ export function parseDaemonIpcRequest(line: string): DaemonIpcRequest | null {
     return null;
   }
 }
+
+/** Type guard for JSON {@link SenseInfo} payloads from daemon HTTP/IPC. */
+export function isSenseInfo(value: unknown): value is SenseInfo {
+  if (!isPlainRecord(value)) return false;
+  return (
+    typeof value.name === "string" &&
+    typeof value.group === "string" &&
+    (value.throttle === null || typeof value.throttle === "number") &&
+    (value.timeout === null || typeof value.timeout === "number") &&
+    Array.isArray(value.triggers) &&
+    value.triggers.every((t: unknown) => typeof t === "string") &&
+    (value.lastSignalTimestamp === null || typeof value.lastSignalTimestamp === "number")
+  );
+}
+
+/** Type guard for JSON {@link WorkflowStatus} payloads from daemon HTTP/IPC. */
+export function isWorkflowStatus(value: unknown): value is WorkflowStatus {
+  if (!isPlainRecord(value)) return false;
+  const cfg = value.config;
+  if (!isPlainRecord(cfg)) return false;
+  return (
+    typeof value.name === "string" &&
+    typeof value.activeThreads === "number" &&
+    Array.isArray(value.activeRunIds) &&
+    value.activeRunIds.every((id: unknown) => typeof id === "string") &&
+    typeof value.queuedThreads === "number" &&
+    typeof cfg.concurrency === "number" &&
+    typeof cfg.overflow === "string"
+  );
+}

packages/core/src/duration.ts

@@ -1,22 +0,0 @@
-import type { Result } from "./result.js";
-import { err, ok } from "./result.js";
-
-const DURATION_RE = /^(\d+)([smh])$/;
-
-const DURATION_MULTIPLIERS: Record<string, number> = {
-  s: 1_000,
-  m: 60_000,
-  h: 3_600_000,
-};
-
-/**
- * Parse a duration string such as `5s`, `10m`, `1h` to milliseconds.
- * Used by `parseNerveConfig` sense/workflow duration fields.
- */
-export function parseDurationStringToMs(value: string): Result<number> {
-  const match = DURATION_RE.exec(value);
-  if (!match) {
-    return err(new Error(`invalid duration "${value}" (expected e.g. "5s", "10m", "1h")`));
-  }
-  return ok(Number(match[1]) * DURATION_MULTIPLIERS[match[2]]);
-}

packages/core/src/index.ts

@@ -12,8 +12,8 @@ export type {
   ComputeResult,
 } from "./config.js";
 export type { Signal, SenseInfo } from "./sense.js";
-export type { SenseComputeFn, SenseModule } from "./sense-contract.js";
-export { labelSenseTrigger, senseTriggerLabels } from "./sense-trigger-labels.js";
+export type { SenseComputeFn, SenseModule } from "./sense.js";
+export { labelSenseTrigger, senseTriggerLabels } from "./sense.js";
 export type {
   WorkflowMessage,
   RoleResult,
@@ -29,11 +29,11 @@ export type {
   WorkflowDefinition,
 } from "./workflow.js";
 export { START, END, DEFAULT_ENGINE_MAX_ROUNDS } from "./workflow.js";
-export { parseDurationStringToMs } from "./duration.js";
-export type { Schema, ExtractFn } from "./extract-layer.js";
-export { ExtractError } from "./extract-layer.js";
-export type { Result } from "./result.js";
-export { ok, err } from "./result.js";
+export { parseDurationStringToMs } from "./util.js";
+export type { Schema, ExtractFn } from "./agent.js";
+export { ExtractError } from "./agent.js";
+export type { Result } from "./util.js";
+export { ok, err } from "./util.js";
 export {
   nerveCommandEnv,
   spawnSafe,
@@ -41,17 +41,17 @@ export {
   type SpawnError,
   type SpawnResult,
   type SpawnSafeOptions,
-} from "./spawn-safe.js";
-export { parseNerveConfig } from "./parse-nerve-config.js";
-export type { KnowledgeConfig } from "./knowledge-config.js";
-export { parseKnowledgeYaml } from "./knowledge-config.js";
-export { isPlainRecord } from "./is-plain-record.js";
-export { KNOWN_AGENT_ADAPTER_IDS } from "./agent-adapter-ids.js";
+} from "./util.js";
+export { parseNerveConfig } from "./config.js";
+export type { KnowledgeConfig } from "./config.js";
+export { parseKnowledgeYaml } from "./config.js";
+export { isPlainRecord } from "./util.js";
+export { KNOWN_AGENT_ADAPTER_IDS } from "./agent.js";
 
-export type { RoutedSenseOutput } from "./sense-workflow-directive.js";
-export { parseWorkflowTrigger, routeSenseComputeOutput } from "./sense-workflow-directive.js";
+export type { RoutedSenseOutput } from "./sense.js";
+export { parseWorkflowTrigger, routeSenseComputeOutput } from "./sense.js";
 
-export { isSenseInfo, isWorkflowStatus } from "./daemon-payload-guards.js";
+export { isSenseInfo, isWorkflowStatus } from "./daemon.js";
 export type {
   WorkflowStatus,
   HealthInfo,
@@ -69,10 +69,10 @@ export type {
   DaemonIpcListWorkflowsResponse,
   DaemonIpcHealthResponse,
   DaemonIpcResponse,
-} from "./daemon-ipc-protocol.js";
-export { parseDaemonIpcRequest } from "./daemon-ipc-protocol.js";
+} from "./daemon.js";
+export { parseDaemonIpcRequest } from "./daemon.js";
 export type {
   DaemonTransport,
   DaemonTransportTriggerResult,
   DaemonTransportWorkflowLaunch,
-} from "./daemon-transport.js";
+} from "./daemon.js";

packages/core/src/is-plain-record.ts

@@ -1,7 +0,0 @@
-/**
- * Narrows `unknown` to a plain JSON-style object (not null, not array).
- * Use after `JSON.parse` / YAML / IPC when validating structure field-by-field.
- */
-export function isPlainRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

packages/core/src/knowledge-config.ts

@@ -1,64 +0,0 @@
-import { parse } from "yaml";
-
-import { isPlainRecord } from "./is-plain-record.js";
-import type { Result } from "./result.js";
-import { err, ok } from "./result.js";
-
-export type KnowledgeConfig = {
-  include: ReadonlyArray<string>;
-  exclude: ReadonlyArray<string>;
-};
-
-function parseStringList(field: unknown, label: string): Result<ReadonlyArray<string>> {
-  if (field === undefined || field === null) {
-    return ok([]);
-  }
-  if (!Array.isArray(field)) {
-    return err(new Error(`${label}: must be an array of strings`));
-  }
-  const out: string[] = [];
-  for (let i = 0; i < field.length; i++) {
-    const item = field[i];
-    if (typeof item !== "string" || item.length === 0) {
-      return err(new Error(`${label}[${String(i)}]: must be a non-empty string`));
-    }
-    out.push(item);
-  }
-  return ok(out);
-}
-
-/**
- * Parse `knowledge.yaml` at the repo root (RFC-003 Knowledge Layer).
- * `include` / `exclude` entries are glob patterns resolved against the repo root.
- */
-export function parseKnowledgeYaml(raw: string): Result<KnowledgeConfig> {
-  let parsed: unknown;
-  try {
-    parsed = parse(raw);
-  } catch (e) {
-    const message = e instanceof Error ? e.message : String(e);
-    return err(new Error(`YAML parse error: ${message}`));
-  }
-
-  if (parsed === undefined || parsed === null) {
-    return ok({ include: [], exclude: [] });
-  }
-
-  if (!isPlainRecord(parsed)) {
-    return err(new Error("knowledge.yaml: root must be a mapping"));
-  }
-
-  const includeResult = parseStringList(parsed.include, "include");
-  if (!includeResult.ok) {
-    return includeResult;
-  }
-  const excludeResult = parseStringList(parsed.exclude, "exclude");
-  if (!excludeResult.ok) {
-    return excludeResult;
-  }
-
-  return ok({
-    include: includeResult.value,
-    exclude: excludeResult.value,
-  });
-}

packages/core/src/parse-nerve-config.ts

@@ -1,348 +0,0 @@
-import { parse } from "yaml";
-
-import {
-  DEFAULT_SENSE_SIGNAL_RETENTION,
-  type ExtractConfig,
-  type NerveApiConfig,
-  type NerveConfig,
-  type SenseConfig,
-  type WorkflowConfig,
-} from "./config.js";
-import { parseDurationStringToMs } from "./duration.js";
-import { isPlainRecord } from "./is-plain-record.js";
-import type { Result } from "./result.js";
-import { err, ok } from "./result.js";
-import { DEFAULT_ENGINE_MAX_ROUNDS } from "./workflow.js";
-
-function isValidGroupName(value: string): boolean {
-  return /^[a-zA-Z0-9_-]+$/.test(value);
-}
-
-function parseRetentionField(name: string, field: unknown): Result<number> {
-  if (field === undefined || field === null) {
-    return ok(DEFAULT_SENSE_SIGNAL_RETENTION);
-  }
-  if (typeof field !== "number" || !Number.isInteger(field) || field < 1) {
-    return err(new Error(`senses.${name}.retention: must be a positive integer`));
-  }
-  return ok(field);
-}
-
-function parseDurationField(field: unknown, label: string): Result<number | null> {
-  if (field === undefined || field === null) return ok(null);
-  if (typeof field !== "string") {
-    return err(
-      new Error(`${label}: invalid duration "${field}" (expected e.g. "5s", "10m", "1h")`),
-    );
-  }
-  const msResult = parseDurationStringToMs(field);
-  if (!msResult.ok) {
-    return err(new Error(`${label}: ${msResult.error.message}`));
-  }
-  return ok(msResult.value);
-}
-
-function validateSenseConfig(name: string, raw: unknown): Result<SenseConfig> {
-  if (!isPlainRecord(raw)) {
-    return err(new Error(`senses.${name}: must be an object`));
-  }
-
-  const obj = raw;
-
-  if (typeof obj.group !== "string" || obj.group.trim() === "") {
-    return err(new Error(`senses.${name}.group: required string`));
-  }
-
-  if (!isValidGroupName(obj.group)) {
-    return err(
-      new Error(
-        `senses.${name}.group: invalid name "${obj.group}" (only alphanumeric, underscore, hyphen allowed)`,
-      ),
-    );
-  }
-
-  const throttleResult = parseDurationField(obj.throttle, `senses.${name}.throttle`);
-  if (!throttleResult.ok) return throttleResult;
-
-  const timeoutResult = parseDurationField(obj.timeout, `senses.${name}.timeout`);
-  if (!timeoutResult.ok) return timeoutResult;
-
-  const graceResult = parseDurationField(obj.grace_period, `senses.${name}.grace_period`);
-  if (!graceResult.ok) return graceResult;
-
-  const retentionResult = parseRetentionField(name, obj.retention);
-  if (!retentionResult.ok) return retentionResult;
-
-  const intervalResult = parseDurationField(obj.interval, `senses.${name}.interval`);
-  if (!intervalResult.ok) return intervalResult;
-
-  let on: string[] = [];
-  if (obj.on !== undefined && obj.on !== null) {
-    if (
-      !Array.isArray(obj.on) ||
-      !obj.on.every((item: unknown): item is string => typeof item === "string")
-    ) {
-      return err(new Error(`senses.${name}.on: must be an array of strings`));
-    }
-    on = obj.on;
-  }
-
-  return ok({
-    group: obj.group,
-    throttle: throttleResult.value,
-    timeout: timeoutResult.value,
-    gracePeriod: graceResult.value,
-    retention: retentionResult.value,
-    interval: intervalResult.value,
-    on,
-  });
-}
-
-function parseEngineMaxRounds(obj: Record<string, unknown>): Result<number> {
-  if (obj.max_rounds === undefined || obj.max_rounds === null) {
-    return ok(DEFAULT_ENGINE_MAX_ROUNDS);
-  }
-  if (
-    typeof obj.max_rounds !== "number" ||
-    !Number.isInteger(obj.max_rounds) ||
-    obj.max_rounds < 1
-  ) {
-    return err(new Error("max_rounds: must be a positive integer"));
-  }
-  return ok(obj.max_rounds);
-}
-
-function validateWorkflowConfig(name: string, raw: unknown): Result<WorkflowConfig> {
-  if (!isPlainRecord(raw)) {
-    return err(new Error(`workflows.${name}: must be an object`));
-  }
-
-  const obj = raw;
-
-  if (
-    typeof obj.concurrency !== "number" ||
-    !Number.isInteger(obj.concurrency) ||
-    obj.concurrency < 1
-  ) {
-    return err(new Error(`workflows.${name}.concurrency: must be a positive integer`));
-  }
-
-  if (obj.overflow !== "drop" && obj.overflow !== "queue") {
-    return err(new Error(`workflows.${name}.overflow: must be "drop" or "queue"`));
-  }
-
-  if (obj.overflow === "drop") {
-    if (obj.max_queue !== undefined && obj.max_queue !== null) {
-      return err(new Error(`workflows.${name}: max_queue is not allowed with overflow "drop"`));
-    }
-    return ok({
-      concurrency: obj.concurrency,
-      overflow: "drop" as const,
-    });
-  }
-
-  // overflow: "queue"
-  let maxQueue = 100; // default
-  if (obj.max_queue !== undefined && obj.max_queue !== null) {
-    if (
-      typeof obj.max_queue !== "number" ||
-      !Number.isInteger(obj.max_queue) ||
-      obj.max_queue < 1
-    ) {
-      return err(new Error(`workflows.${name}.max_queue: must be a positive integer`));
-    }
-    maxQueue = obj.max_queue;
-  }
-
-  return ok({
-    concurrency: obj.concurrency,
-    overflow: "queue" as const,
-    maxQueue,
-  });
-}
-
-function parseSenses(
-  obj: Record<string, unknown>,
-): Result<{ senses: Record<string, SenseConfig> }> {
-  if (!isPlainRecord(obj.senses)) {
-    return err(new Error("senses: required object"));
-  }
-
-  const sensesRaw = obj.senses;
-  const senses: Record<string, SenseConfig> = {};
-
-  for (const [name, senseRaw] of Object.entries(sensesRaw)) {
-    const result = validateSenseConfig(name, senseRaw);
-    if (!result.ok) return result;
-    senses[name] = result.value;
-  }
-
-  return ok({ senses });
-}
-
-const DEFAULT_API_BIND_HOST = "127.0.0.1";
-
-/** Hosts that may bind the HTTP API without `api.token` (loopback-only). */
-function isLoopbackOnlyApiHost(host: string): boolean {
-  const h = host.trim();
-  return h === "127.0.0.1" || h.toLowerCase() === "localhost";
-}
-
-function parseApiTokenField(api: Record<string, unknown>): Result<string | null> {
-  if (api.token === undefined || api.token === null) {
-    return ok(null);
-  }
-  if (typeof api.token !== "string") {
-    return err(new Error("api.token: must be a string when provided"));
-  }
-  if (api.token.length === 0) {
-    return err(new Error("api.token: must not be empty when provided"));
-  }
-  return ok(api.token);
-}
-
-function parseApiHostField(api: Record<string, unknown>): Result<string> {
-  if (api.host === undefined || api.host === null) {
-    return ok(DEFAULT_API_BIND_HOST);
-  }
-  if (typeof api.host !== "string") {
-    return err(new Error("api.host: must be a string when provided"));
-  }
-  if (api.host.length === 0) {
-    return err(new Error("api.host: must not be empty when provided"));
-  }
-  return ok(api.host);
-}
-
-function parseApiConfig(obj: Record<string, unknown>): Result<NerveApiConfig> {
-  if (obj.api === undefined || obj.api === null) {
-    return ok({ port: null, token: null, host: DEFAULT_API_BIND_HOST });
-  }
-  if (!isPlainRecord(obj.api)) {
-    return err(new Error("api: must be an object if provided"));
-  }
-  const api = obj.api;
-  if (api.port === undefined || api.port === null) {
-    return ok({ port: null, token: null, host: DEFAULT_API_BIND_HOST });
-  }
-  if (
-    typeof api.port !== "number" ||
-    !Number.isInteger(api.port) ||
-    api.port < 1 ||
-    api.port > 65_535
-  ) {
-    return err(new Error("api.port: must be an integer between 1 and 65535 if provided"));
-  }
-
-  const tokenResult = parseApiTokenField(api);
-  if (!tokenResult.ok) return tokenResult;
-  const hostResult = parseApiHostField(api);
-  if (!hostResult.ok) return hostResult;
-
-  if (!isLoopbackOnlyApiHost(hostResult.value) && tokenResult.value === null) {
-    return err(
-      new Error("api.host binds to non-loopback address, api.token is required for security"),
-    );
-  }
-
-  return ok({ port: api.port, token: tokenResult.value, host: hostResult.value });
-}
-
-function parseWorkflows(obj: Record<string, unknown>): Result<Record<string, WorkflowConfig>> {
-  if (obj.workflows === undefined || obj.workflows === null) return ok({});
-
-  if (!isPlainRecord(obj.workflows)) {
-    return err(new Error("workflows: must be an object if provided"));
-  }
-
-  const workflowsRaw = obj.workflows;
-  const workflows: Record<string, WorkflowConfig> = {};
-
-  for (const [name, wfRaw] of Object.entries(workflowsRaw)) {
-    const result = validateWorkflowConfig(name, wfRaw);
-    if (!result.ok) return result;
-    workflows[name] = result.value;
-  }
-
-  return ok(workflows);
-}
-
-function parseExtract(obj: Record<string, unknown>): Result<ExtractConfig | null> {
-  if (obj.extract === undefined || obj.extract === null) {
-    return ok(null);
-  }
-
-  if (!isPlainRecord(obj.extract)) {
-    return err(new Error("extract: must be an object if provided"));
-  }
-
-  const ext = obj.extract;
-
-  if (typeof ext.provider !== "string" || ext.provider.trim() === "") {
-    return err(new Error("extract.provider: required non-empty string"));
-  }
-
-  if (typeof ext.model !== "string" || ext.model.trim() === "") {
-    return err(new Error("extract.model: required non-empty string"));
-  }
-
-  return ok({ provider: ext.provider, model: ext.model });
-}
-
-export function parseNerveConfig(raw: string): Result<NerveConfig> {
-  let parsed: unknown;
-
-  try {
-    parsed = parse(raw);
-  } catch (e) {
-    const message = e instanceof Error ? e.message : String(e);
-    return err(new Error(`YAML parse error: ${message}`));
-  }
-
-  if (!isPlainRecord(parsed)) {
-    return err(new Error("Config must be a YAML object"));
-  }
-
-  const obj = parsed;
-
-  const sensesResult = parseSenses(obj);
-  if (!sensesResult.ok) return sensesResult;
-  const { senses } = sensesResult.value;
-
-  // Legacy top-level `reflexes` is rejected; each sense carries `interval` / `on` for the sense scheduler.
-  if (Object.hasOwn(obj, "reflexes")) {
-    return err(
-      new Error(
-        "reflexes: top-level key is no longer supported; set `interval` and `on` on each sense under `senses.<name>`",
-      ),
-    );
-  }
-
-  const workflowsResult = parseWorkflows(obj);
-  if (!workflowsResult.ok) return workflowsResult;
-
-  const maxRoundsResult = parseEngineMaxRounds(obj);
-  if (!maxRoundsResult.ok) return maxRoundsResult;
-
-  const apiResult = parseApiConfig(obj);
-  if (!apiResult.ok) return apiResult;
-
-  if (Object.hasOwn(obj, "agents")) {
-    return err(
-      new Error(
-        "agents: key is no longer supported — declare adapters on workflow roles (RFC-003)",
-      ),
-    );
-  }
-
-  const extractResult = parseExtract(obj);
-  if (!extractResult.ok) return extractResult;
-
-  return ok({
-    maxRounds: maxRoundsResult.value,
-    senses,
-    workflows: workflowsResult.value,
-    api: apiResult.value,
-    extract: extractResult.value,
-  });
-}

packages/core/src/result.ts

@@ -1,9 +0,0 @@
-export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
-
-export function ok<T>(value: T): Result<T, never> {
-  return { ok: true, value };
-}
-
-export function err<E = Error>(error: E): Result<never, E> {
-  return { ok: false, error };
-}

packages/core/src/sense-contract.ts

@@ -1,22 +0,0 @@
-import type { SQLiteTable } from "drizzle-orm/sqlite-core";
-import type { ComputeResult } from "./config.js";
-
-/**
- * The function signature every sense `src/index.ts` must export as a named
- * `compute` export.
- *
- * Pure: no DB, no peers.
- * Return `null` to stay silent, or `{ signal, workflow }` to emit a Signal
- * (and optionally trigger a Workflow).
- * The runtime handles persistence via `db.insert(table).values(result.signal)`.
- */
-export type SenseComputeFn<T = unknown> = () => Promise<ComputeResult<T>>;
-
-/**
- * The full shape a sense module (`src/index.ts`) must export.
- * `compute` provides the data; `table` tells the runtime where to persist it.
- */
-export type SenseModule<T = unknown> = {
-  compute: SenseComputeFn<T>;
-  table: SQLiteTable;
-};

packages/core/src/sense-trigger-labels.ts

@@ -1,40 +0,0 @@
-import type { SenseConfig } from "./config.js";
-
-function formatIntervalMs(ms: number): string {
-  const totalSeconds = Math.floor(ms / 1000);
-  if (totalSeconds < 60) return `${totalSeconds}s`;
-  const minutes = Math.floor(totalSeconds / 60);
-  if (minutes < 60) return `${minutes}m`;
-  const hours = Math.floor(minutes / 60);
-  const remainingMinutes = minutes % 60;
-  return `${hours}h ${remainingMinutes}m`;
-}
-
-/** Human-readable label for a sense schedule (`interval` and/or `on`). */
-export function labelSenseTrigger(slice: Pick<SenseConfig, "interval" | "on">): string {
-  const parts: string[] = [];
-  if (slice.interval !== null) {
-    parts.push(`every ${formatIntervalMs(slice.interval)}`);
-  }
-  if (slice.on.length > 0) {
-    parts.push(`on: ${slice.on.join(", ")}`);
-  }
-  if (parts.length === 0) {
-    return "trigger (no interval or on)";
-  }
-  return parts.join(" · ");
-}
-
-/**
- * Human-readable trigger labels for a sense from its `SenseConfig.interval` / `.on`.
- * Returns an empty array when the sense is missing or has no schedule.
- */
-export function senseTriggerLabels(
-  senseName: string,
-  senses: Record<string, SenseConfig>,
-): string[] {
-  const sc = senses[senseName];
-  if (sc === undefined) return [];
-  if (sc.interval === null && sc.on.length === 0) return [];
-  return [labelSenseTrigger({ interval: sc.interval, on: sc.on })];
-}

packages/core/src/sense-workflow-directive.ts

@@ -1,56 +0,0 @@
-import type { WorkflowTrigger } from "./config.js";
-import { isPlainRecord } from "./is-plain-record.js";
-import type { Result } from "./result.js";
-import { err, ok } from "./result.js";
-
-/** Normalized non-null compute output for the kernel (unknown signal payload). */
-export type RoutedSenseOutput = {
-  signal: unknown;
-  workflow: WorkflowTrigger | null;
-};
-
-/**
- * Validates a structured workflow trigger object from Sense compute or IPC.
- */
-export function parseWorkflowTrigger(value: unknown): Result<WorkflowTrigger> {
-  if (!isPlainRecord(value)) {
-    return err(new Error("workflow trigger must be a plain object"));
-  }
-  const nameRaw = value.name;
-  if (typeof nameRaw !== "string" || nameRaw.trim().length === 0) {
-    return err(new Error('workflow trigger: "name" must be a non-empty string'));
-  }
-  const maxRounds = value.maxRounds;
-  if (typeof maxRounds !== "number" || !Number.isInteger(maxRounds) || maxRounds < 1) {
-    return err(new Error('workflow trigger: "maxRounds" must be an integer >= 1'));
-  }
-  const prompt = value.prompt;
-  if (typeof prompt !== "string") {
-    return err(new Error('workflow trigger: "prompt" must be a string'));
-  }
-  const dryRun = value.dryRun;
-  if (typeof dryRun !== "boolean") {
-    return err(new Error('workflow trigger: "dryRun" must be a boolean'));
-  }
-  return ok({ name: nameRaw.trim(), maxRounds, prompt, dryRun });
-}
-
-/**
- * Interprets a Sense compute non-null return value for the engine.
- * - Explicit `{ signal, workflow }` (workflow may be null): validates `workflow` when non-null.
- * - Any other value: treated as `{ signal: payload, workflow: null }` (shorthand).
- */
-export function routeSenseComputeOutput(payload: unknown): Result<RoutedSenseOutput> {
-  if (isPlainRecord(payload) && Object.hasOwn(payload, "signal")) {
-    const wfRaw = Object.hasOwn(payload, "workflow") ? payload.workflow : null;
-    if (wfRaw === null) {
-      return ok({ signal: payload.signal, workflow: null });
-    }
-    const parsed = parseWorkflowTrigger(wfRaw);
-    if (!parsed.ok) {
-      return ok({ signal: payload.signal, workflow: null });
-    }
-    return ok({ signal: payload.signal, workflow: parsed.value });
-  }
-  return ok({ signal: payload, workflow: null });
-}

packages/core/src/sense.ts

@@ -1,3 +1,8 @@
+import type { SQLiteTable } from "drizzle-orm/sqlite-core";
+
+import type { ComputeResult, SenseConfig, WorkflowTrigger } from "./config.js";
+import { type Result, err, isPlainRecord, ok } from "./util.js";
+
 export type Signal = {
   id: number;
   senseId: string;
@@ -15,3 +20,114 @@ export type SenseInfo = {
   triggers: string[];
   lastSignalTimestamp: number | null;
 };
+
+/**
+ * The function signature every sense `src/index.ts` must export as a named
+ * `compute` export.
+ *
+ * Pure: no DB, no peers.
+ * Return `null` to stay silent, or `{ signal, workflow }` to emit a Signal
+ * (and optionally trigger a Workflow).
+ * The runtime handles persistence via `db.insert(table).values(result.signal)`.
+ */
+export type SenseComputeFn<T = unknown> = () => Promise<ComputeResult<T>>;
+
+/**
+ * The full shape a sense module (`src/index.ts`) must export.
+ * `compute` provides the data; `table` tells the runtime where to persist it.
+ */
+export type SenseModule<T = unknown> = {
+  compute: SenseComputeFn<T>;
+  table: SQLiteTable;
+};
+
+/** Normalized non-null compute output for the kernel (unknown signal payload). */
+export type RoutedSenseOutput = {
+  signal: unknown;
+  workflow: WorkflowTrigger | null;
+};
+
+function formatIntervalMs(ms: number): string {
+  const totalSeconds = Math.floor(ms / 1000);
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+  const minutes = Math.floor(totalSeconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return `${hours}h ${remainingMinutes}m`;
+}
+
+/** Human-readable label for a sense schedule (`interval` and/or `on`). */
+export function labelSenseTrigger(slice: Pick<SenseConfig, "interval" | "on">): string {
+  const parts: string[] = [];
+  if (slice.interval !== null) {
+    parts.push(`every ${formatIntervalMs(slice.interval)}`);
+  }
+  if (slice.on.length > 0) {
+    parts.push(`on: ${slice.on.join(", ")}`);
+  }
+  if (parts.length === 0) {
+    return "trigger (no interval or on)";
+  }
+  return parts.join(" · ");
+}
+
+/**
+ * Human-readable trigger labels for a sense from its `SenseConfig.interval` / `.on`.
+ * Returns an empty array when the sense is missing or has no schedule.
+ */
+export function senseTriggerLabels(
+  senseName: string,
+  senses: Record<string, SenseConfig>,
+): string[] {
+  const sc = senses[senseName];
+  if (sc === undefined) return [];
+  if (sc.interval === null && sc.on.length === 0) return [];
+  return [labelSenseTrigger({ interval: sc.interval, on: sc.on })];
+}
+
+/**
+ * Validates a structured workflow trigger object from Sense compute or IPC.
+ */
+export function parseWorkflowTrigger(value: unknown): Result<WorkflowTrigger> {
+  if (!isPlainRecord(value)) {
+    return err(new Error("workflow trigger must be a plain object"));
+  }
+  const nameRaw = value.name;
+  if (typeof nameRaw !== "string" || nameRaw.trim().length === 0) {
+    return err(new Error('workflow trigger: "name" must be a non-empty string'));
+  }
+  const maxRounds = value.maxRounds;
+  if (typeof maxRounds !== "number" || !Number.isInteger(maxRounds) || maxRounds < 1) {
+    return err(new Error('workflow trigger: "maxRounds" must be an integer >= 1'));
+  }
+  const prompt = value.prompt;
+  if (typeof prompt !== "string") {
+    return err(new Error('workflow trigger: "prompt" must be a string'));
+  }
+  const dryRun = value.dryRun;
+  if (typeof dryRun !== "boolean") {
+    return err(new Error('workflow trigger: "dryRun" must be a boolean'));
+  }
+  return ok({ name: nameRaw.trim(), maxRounds, prompt, dryRun });
+}
+
+/**
+ * Interprets a Sense compute non-null return value for the engine.
+ * - Explicit `{ signal, workflow }` (workflow may be null): validates `workflow` when non-null.
+ * - Any other value: treated as `{ signal: payload, workflow: null }` (shorthand).
+ */
+export function routeSenseComputeOutput(payload: unknown): Result<RoutedSenseOutput> {
+  if (isPlainRecord(payload) && Object.hasOwn(payload, "signal")) {
+    const wfRaw = Object.hasOwn(payload, "workflow") ? payload.workflow : null;
+    if (wfRaw === null) {
+      return ok({ signal: payload.signal, workflow: null });
+    }
+    const parsed = parseWorkflowTrigger(wfRaw);
+    if (!parsed.ok) {
+      return ok({ signal: payload.signal, workflow: null });
+    }
+    return ok({ signal: payload.signal, workflow: parsed.value });
+  }
+  return ok({ signal: payload, workflow: null });
+}

packages/core/src/util.ts

@@ -1,7 +1,8 @@
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { type Result, err, ok } from "./result.js";
+
+export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
 
 /** Compatible with `process.env` for `child_process.spawn`. */
 export type SpawnEnv = Record<string, string | undefined>;
@@ -40,6 +41,42 @@ type SpawnSafeOptionsInput = SpawnSafeOptions | Omit<SpawnSafeOptions, "dryRun">
 
 const DEFAULT_TIMEOUT_MS = 300_000;
 
+export function ok<T>(value: T): Result<T, never> {
+  return { ok: true, value };
+}
+
+export function err<E = Error>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+/**
+ * Narrows `unknown` to a plain JSON-style object (not null, not array).
+ * Use after `JSON.parse` / YAML / IPC when validating structure field-by-field.
+ */
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const DURATION_RE = /^(\d+)([smh])$/;
+
+const DURATION_MULTIPLIERS: Record<string, number> = {
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+};
+
+/**
+ * Parse a duration string such as `5s`, `10m`, `1h` to milliseconds.
+ * Used by `parseNerveConfig` sense/workflow duration fields.
+ */
+export function parseDurationStringToMs(value: string): Result<number> {
+  const match = DURATION_RE.exec(value);
+  if (!match) {
+    return err(new Error(`invalid duration "${value}" (expected e.g. "5s", "10m", "1h")`));
+  }
+  return ok(Number(match[1]) * DURATION_MULTIPLIERS[match[2]]);
+}
+
 /**
  * PATH and PNPM_HOME for running `pnpm` and `nerve` from workflow roles.
  * Uses the pnpm store home only (no npm user bin); binaries must resolve via PATH.

packages/daemon/src/__tests__/fixtures/crash-worker.js

@@ -0,0 +1,9 @@
+// Ready then crashes on a timer; still echoes IPC so parent tests can send after respawn
+process.on("message", (msg) => {
+  if (msg && msg.type === "shutdown") {
+    process.exit(0);
+  }
+  process.send({ type: "echo", payload: msg });
+});
+process.send({ type: "ready" });
+setTimeout(() => process.exit(1), 50);

packages/daemon/src/__tests__/fixtures/echo-worker.js

@@ -0,0 +1,9 @@
+// Simple test worker: sends ready, echoes messages, handles shutdown
+process.on("message", (msg) => {
+  if (msg && msg.type === "shutdown") {
+    process.exit(0);
+  }
+  // Echo back with 'echo' type
+  process.send({ type: "echo", payload: msg });
+});
+process.send({ type: "ready" });

packages/daemon/src/__tests__/fixtures/stderr-worker.js

@@ -0,0 +1,9 @@
+// Like echo-worker but writes stderr for tail diagnostics
+console.error("stderr-marker");
+process.on("message", (msg) => {
+  if (msg && msg.type === "shutdown") {
+    process.exit(0);
+  }
+  process.send({ type: "echo", payload: msg });
+});
+process.send({ type: "ready" });

packages/daemon/src/__tests__/kernel-phase6.test.ts

@@ -70,6 +70,14 @@ const { createKernel } = await import("../kernel.js");
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** Sense worker `fork` runs on the next microtask per scheduled `start`. */
+async function flushSenseWorkerForkMicrotasks(kernel: { groups: Set<string> }): Promise<void> {
+  const n = kernel.groups.size;
+  for (let i = 0; i < n; i++) {
+    await Promise.resolve();
+  }
+}
+
 function makeConfig(overrides: Partial<NerveConfig> = {}): NerveConfig {
   return {
     senses: {
@@ -142,6 +150,8 @@ describe("kernel — getHealth", () => {
       },
     });
     const kernel = createKernel(config, nerveRoot);
+    await flushSenseWorkerForkMicrotasks(kernel);
+    await vi.runAllTimersAsync();
 
     const health = kernel.getHealth();
     expect(health.activeSenses).toBe(3);
@@ -171,6 +181,8 @@ describe("kernel — restartGroup", () => {
   it("sends shutdown to old worker and spawns new one", async () => {
     const config = makeConfig();
     const kernel = createKernel(config, nerveRoot);
+    await flushSenseWorkerForkMicrotasks(kernel);
+    await vi.runAllTimersAsync();
 
     expect(mockChildren.length).toBe(1);
     const oldChild = mockChildren[0];
@@ -178,6 +190,7 @@ describe("kernel — restartGroup", () => {
     const restartPromise = kernel.restartGroup("system");
     // The shutdown message triggers exit in the mock
     await restartPromise;
+    await vi.runAllTimersAsync();
 
     // A new child should have been spawned
     expect(mockChildren.length).toBe(2);
@@ -191,6 +204,8 @@ describe("kernel — restartGroup", () => {
   it("restartGroup on unknown group does nothing", async () => {
     const config = makeConfig();
     const kernel = createKernel(config, nerveRoot);
+    await flushSenseWorkerForkMicrotasks(kernel);
+    await vi.runAllTimersAsync();
 
     expect(mockChildren.length).toBe(1);
     await kernel.restartGroup("nonexistent");
@@ -218,6 +233,8 @@ describe("kernel — reloadConfig", () => {
   it("adds new group worker when new sense group appears", async () => {
     const config = makeConfig();
     const kernel = createKernel(config, nerveRoot);
+    await flushSenseWorkerForkMicrotasks(kernel);
+    await vi.runAllTimersAsync();
 
     expect(mockChildren.length).toBe(1); // only system group
     expect(kernel.groups.has("network")).toBe(false);
@@ -249,6 +266,9 @@ describe("kernel — reloadConfig", () => {
       api: { port: null, token: null, host: "127.0.0.1" },
     });
 
+    await Promise.resolve();
+    await vi.runAllTimersAsync();
+
     expect(kernel.groups.has("network")).toBe(true);
     expect(mockChildren.length).toBe(2); // system + network
 
@@ -283,6 +303,8 @@ describe("kernel — reloadConfig", () => {
       api: { port: null, token: null, host: "127.0.0.1" },
     };
     const kernel = createKernel(config, nerveRoot);
+    await flushSenseWorkerForkMicrotasks(kernel);
+    await vi.runAllTimersAsync();
 
     expect(mockChildren.length).toBe(2);
     expect(kernel.groups.has("network")).toBe(true);
@@ -308,6 +330,7 @@ describe("kernel — reloadConfig", () => {
     });
 
     expect(kernel.groups.has("network")).toBe(false);
+    await vi.runAllTimersAsync();
     // Network child should have received shutdown
     expect(networkChild.send).toHaveBeenCalledWith(expect.objectContaining({ type: "shutdown" }));
 
@@ -317,6 +340,8 @@ describe("kernel — reloadConfig", () => {
   it("health reflects updated sense count after reloadConfig", async () => {
     const config = makeConfig();
     const kernel = createKernel(config, nerveRoot);
+    await flushSenseWorkerForkMicrotasks(kernel);
+    await vi.runAllTimersAsync();
 
     expect(kernel.getHealth().activeSenses).toBe(1);
 

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

@@ -29,6 +29,9 @@ type MockChild = EventEmitter & {
 function makeMockChild(pid = 1): MockChild {
   const child = new EventEmitter() as MockChild;
   child.connected = true;
+  setImmediate(() => {
+    child.emit("message", { type: "ready" });
+  });
   child.send = vi.fn((msg: unknown) => {
     if (
       msg !== null &&
@@ -136,6 +139,7 @@ describe("kernel.triggerSense()", () => {
       logStore: makeMockLogStore() as never,
     });
 
+    await vi.runAllTimersAsync();
     expect(() => kernel.triggerSense("no-such-sense")).toThrow(/Unknown sense/);
 
     await kernel.stop();
@@ -169,6 +173,7 @@ describe("kernel.triggerSense()", () => {
       logStore: makeMockLogStore() as never,
     });
 
+    await vi.runAllTimersAsync();
     // Two groups → two workers
     expect(mockChildren.length).toBe(2);
 
@@ -214,6 +219,7 @@ describe("kernel.triggerSense()", () => {
       logStore: makeMockLogStore() as never,
     });
 
+    await vi.runAllTimersAsync();
     // Both senses share the "system" group → one worker only
     expect(mockChildren.length).toBe(1);
     const worker = mockChildren[0];
@@ -237,6 +243,7 @@ describe("kernel.triggerSense()", () => {
       logStore: makeMockLogStore() as never,
     });
 
+    await new Promise<void>((resolve) => setImmediate(resolve));
     const worker = mockChildren[0];
     worker.connected = false;
 

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

@@ -102,6 +102,13 @@ function makeLogStore() {
   };
 }
 
+async function flushSenseWorkerForkMicrotasks(kernel: { groups: Set<string> }): Promise<void> {
+  const n = kernel.groups.size;
+  for (let i = 0; i < n; i++) {
+    await Promise.resolve();
+  }
+}
+
 function makeConfig(overrides: Partial<NerveConfig> = {}): NerveConfig {
   return {
     senses: {
@@ -164,6 +171,8 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
+      await flushSenseWorkerForkMicrotasks(kernel);
+      await vi.runAllTimersAsync();
 
       // Simulate a sense worker sending a signal with workflow launch payload
       // The kernel's handleWorkerMessage processes "signal" type messages
@@ -222,6 +231,8 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
+      await flushSenseWorkerForkMicrotasks(kernel);
+      await vi.runAllTimersAsync();
 
       // Simulate sense worker returning a signal plus workflow launch
       const workerPool = mockChildren[0];
@@ -275,6 +286,8 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
+      await flushSenseWorkerForkMicrotasks(kernel);
+      await vi.runAllTimersAsync();
 
       const workerPool = mockChildren[0];
       if (workerPool) {
@@ -337,6 +350,8 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
+      await flushSenseWorkerForkMicrotasks(kernel);
+      await vi.runAllTimersAsync();
 
       // Emit a regular signal (shorthand payload) — should NOT trigger any workflow
       const workerPool = mockChildren[0];
@@ -387,6 +402,8 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
+      await flushSenseWorkerForkMicrotasks(kernel);
+      await vi.runAllTimersAsync();
 
       // Simulate sense compute returning a signal plus workflow launch
       const workerPool = mockChildren[0];
@@ -440,6 +457,8 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
+      await flushSenseWorkerForkMicrotasks(kernel);
+      await vi.runAllTimersAsync();
 
       // Reload with a workflow added
       const newConfig: NerveConfig = {
@@ -517,6 +536,8 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
+      await flushSenseWorkerForkMicrotasks(kernel);
+      await vi.runAllTimersAsync();
 
       // Reload with the workflow removed
       const newConfig: NerveConfig = {
@@ -600,6 +621,8 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
+      await flushSenseWorkerForkMicrotasks(kernel);
+      await vi.runAllTimersAsync();
 
       // Trigger a workflow via sense compute return value
       const workerPool = mockChildren[0];
@@ -664,6 +687,8 @@ describe("kernel + workflowManager integration", () => {
         workerScript: "fake-worker.js",
         logStore,
       });
+      await flushSenseWorkerForkMicrotasks(kernel);
+      await vi.runAllTimersAsync();
 
       const health = kernel.getHealth();
       expect(health).toHaveProperty("activeWorkflows");

packages/daemon/src/__tests__/kernel.test.ts

@@ -16,10 +16,12 @@ type MockChild = EventEmitter & {
   send: ReturnType<typeof vi.fn>;
   kill: ReturnType<typeof vi.fn>;
   pid: number;
+  connected: boolean;
 };
 
 function makeMockChild(pid = 1): MockChild {
   const child = new EventEmitter() as MockChild;
+  child.connected = true;
   setImmediate(() => {
     child.emit("message", { type: "ready" });
   });
@@ -27,7 +29,10 @@ function makeMockChild(pid = 1): MockChild {
     if (msg === null || typeof msg !== "object") return;
     const m = msg as Record<string, unknown>;
     if (m.type === "shutdown") {
-      setImmediate(() => child.emit("exit", 0, null));
+      setImmediate(() => {
+        child.connected = false;
+        child.emit("exit", 0, null);
+      });
       return;
     }
     if (m.type === "compute" && typeof m.sense === "string") {
@@ -37,6 +42,7 @@ function makeMockChild(pid = 1): MockChild {
     }
   });
   child.kill = vi.fn((_signal?: string) => {
+    child.connected = false;
     child.emit("exit", null, _signal ?? "SIGKILL");
   });
   child.pid = pid;
@@ -59,6 +65,14 @@ const { createLogStore } = await import("@uncaged/nerve-store");
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** `WorkerRuntime.start` schedules `fork` on the next microtask — flush one tick per initial group. */
+async function flushSenseWorkerForkMicrotasks(kernel: { groups: Set<string> }): Promise<void> {
+  const n = kernel.groups.size;
+  for (let i = 0; i < n; i++) {
+    await Promise.resolve();
+  }
+}
+
 function makeConfig(overrides: Partial<NerveConfig> = {}): NerveConfig {
   return {
     senses: {
@@ -173,6 +187,7 @@ describe("kernel — message routing", () => {
       },
     });
     const kernel = createKernel(config, nerveRoot);
+    await flushSenseWorkerForkMicrotasks(kernel);
 
     const child = mockChildren[0];
     child.emit("message", { type: "error", sense: "cpu-usage", error: "compute failed" });
@@ -201,6 +216,7 @@ describe("kernel — message routing", () => {
       },
     });
     const kernel = createKernel(config, nerveRoot);
+    await flushSenseWorkerForkMicrotasks(kernel);
 
     const child = mockChildren[0];
     const callsBefore = stderrSpy.mock.calls.length;
@@ -228,6 +244,7 @@ describe("kernel — message routing", () => {
       },
     });
     const kernel = createKernel(config, nerveRoot);
+    await flushSenseWorkerForkMicrotasks(kernel);
 
     const child = mockChildren[0];
     expect(() => child.emit("message", { type: "unknown-type" })).not.toThrow();
@@ -290,6 +307,7 @@ describe("kernel — groupForSense mapping", () => {
       api: { port: null, token: null, host: "127.0.0.1" },
     };
     const kernel = createKernel(config, nerveRoot);
+    await flushSenseWorkerForkMicrotasks(kernel);
 
     // system and network = 2 unique groups
     expect(mockChildren.length).toBe(2);
@@ -311,8 +329,10 @@ describe("kernel — groupForSense mapping", () => {
       },
     });
     const kernel = createKernel(config, nerveRoot);
-
+    await flushSenseWorkerForkMicrotasks(kernel);
     const child = mockChildren[0];
+    child.emit("message", { type: "ready" });
+
     vi.advanceTimersByTime(500);
 
     expect(child.send).toHaveBeenCalledWith(

packages/daemon/src/__tests__/worker-pool.test.ts

@@ -50,6 +50,7 @@ async function startWorkerWithReady(
   group: string,
 ): Promise<void> {
   const pr = pool.startWorker(group);
+  await Promise.resolve();
   const child = mockChildren[mockChildren.length - 1];
   child.emit("message", { type: "ready" });
   await pr;
@@ -137,6 +138,7 @@ describe("createSenseWorkerPool", () => {
     expect(pool.activeGroupCount()).toBe(1);
     pool.evictGroup("x");
     expect(pool.hasWorkerForGroup("x")).toBe(false);
+    await Promise.resolve();
     expect(mockChildren[0].send).toHaveBeenCalledWith(
       expect.objectContaining({ type: "shutdown" }),
     );
@@ -159,6 +161,7 @@ describe("createSenseWorkerPool", () => {
 
     const p = pool.restartGroup("g");
     expect(onBeforeGroupRestart).toHaveBeenCalledWith("g");
+    await Promise.resolve();
     expect(mockChildren[0].send).toHaveBeenCalledWith(
       expect.objectContaining({ type: "shutdown" }),
     );
@@ -171,7 +174,7 @@ describe("createSenseWorkerPool", () => {
   });
 
   it("onWorkerCrashed runs and schedules respawn after non-zero exit", async () => {
-    vi.useFakeTimers({ shouldAdvanceTime: true });
+    vi.useFakeTimers();
     const onWorkerCrashed = vi.fn();
     const pool = createSenseWorkerPool({
       nerveRoot: "/tmp/n",

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

@@ -0,0 +1,180 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createWorkerRuntime } from "../worker-runtime.js";
+
+const fixturesDir = join(dirname(fileURLToPath(import.meta.url)), "fixtures");
+const echoWorkerPath = join(fixturesDir, "echo-worker.js");
+const crashWorkerPath = join(fixturesDir, "crash-worker.js");
+const stderrWorkerPath = join(fixturesDir, "stderr-worker.js");
+
+function baseConfig(script: string) {
+  return {
+    script,
+    argsForKey: () => [],
+    forwardStderr: true,
+    onMessage: vi.fn(),
+    onReady: vi.fn(),
+    onExit: vi.fn(),
+    respawn: {
+      enabled: true,
+      maxCrashes: 6,
+      windowMs: 60_000,
+      delayMs: 80,
+      allowRespawn: null,
+    },
+    shutdownTimeoutMs: 5000,
+  };
+}
+
+describe("createWorkerRuntime", () => {
+  const runtimes: Array<{ shutdown: () => Promise<void> }> = [];
+
+  afterEach(async () => {
+    await Promise.all(runtimes.splice(0).map((r) => r.shutdown()));
+  });
+
+  function track<R extends { shutdown: () => Promise<void> }>(r: R): R {
+    runtimes.push(r);
+    return r;
+  }
+
+  it("start + send message + receive echo", async () => {
+    const incoming: unknown[] = [];
+    const rt = track(
+      createWorkerRuntime({
+        ...baseConfig(echoWorkerPath),
+        onMessage: (_key, msg) => {
+          incoming.push(msg);
+        },
+      }),
+    );
+
+    await rt.start("a");
+    expect(rt.has("a")).toBe(true);
+    await rt.send("a", { type: "ping", n: 1 });
+
+    await vi.waitFor(() => {
+      expect(incoming.some((m) => isEchoOf(m, { type: "ping", n: 1 }))).toBe(true);
+    });
+    await rt.shutdown();
+  });
+
+  it("cold start on send (no explicit start)", async () => {
+    const incoming: unknown[] = [];
+    const rt = track(
+      createWorkerRuntime({
+        ...baseConfig(echoWorkerPath),
+        onMessage: (_key, msg) => {
+          incoming.push(msg);
+        },
+      }),
+    );
+
+    expect(rt.has("x")).toBe(false);
+    await rt.send("x", { type: "hi" });
+    await vi.waitFor(() => {
+      expect(rt.has("x")).toBe(true);
+      expect(incoming.some((m) => isEchoOf(m, { type: "hi" }))).toBe(true);
+    });
+    await rt.shutdown();
+  });
+
+  it("evict stops worker; has() is false", async () => {
+    const rt = track(createWorkerRuntime(baseConfig(echoWorkerPath)));
+    await rt.start("k");
+    expect(rt.has("k")).toBe(true);
+    await rt.evict("k");
+    expect(rt.has("k")).toBe(false);
+    await rt.shutdown();
+  });
+
+  it("drain stops and respawns (new pid)", async () => {
+    const rt = track(createWorkerRuntime(baseConfig(echoWorkerPath)));
+    await rt.start("k");
+    const before = rt.pid("k");
+    expect(before).not.toBeNull();
+    await rt.drain("k");
+    const after = rt.pid("k");
+    expect(after).not.toBeNull();
+    expect(after).not.toBe(before);
+    await rt.shutdown();
+  });
+
+  it("crash triggers auto-respawn", async () => {
+    const incoming: unknown[] = [];
+    const onExit = vi.fn();
+    const rt = track(
+      createWorkerRuntime({
+        ...baseConfig(crashWorkerPath),
+        onExit,
+        onMessage: (_key, msg) => {
+          incoming.push(msg);
+        },
+      }),
+    );
+
+    await rt.start("c");
+
+    await vi.waitFor(() => expect(onExit.mock.calls.length).toBeGreaterThanOrEqual(1), {
+      timeout: 3000,
+    });
+    await vi.waitFor(() => expect(rt.has("c")).toBe(true), { timeout: 3000 });
+
+    await rt.send("c", { type: "after-crash" });
+    await vi.waitFor(() => {
+      expect(incoming.some((m) => isEchoOf(m, { type: "after-crash" }))).toBe(true);
+    });
+    await rt.shutdown();
+  });
+
+  it("crash limit reached → no more automatic respawns", async () => {
+    const rt = track(
+      createWorkerRuntime({
+        ...baseConfig(crashWorkerPath),
+        respawn: {
+          enabled: true,
+          maxCrashes: 2,
+          windowMs: 60_000,
+          delayMs: 50,
+          allowRespawn: null,
+        },
+      }),
+    );
+
+    await rt.start("z");
+
+    await vi.waitFor(() => expect(rt.has("z")).toBe(false), { timeout: 8000 });
+
+    await rt.shutdown();
+  });
+
+  it("shutdown stops all workers", async () => {
+    const rt = track(createWorkerRuntime(baseConfig(echoWorkerPath)));
+    await rt.start("a");
+    await rt.start("b");
+    expect(rt.keys().sort()).toEqual(["a", "b"].sort());
+    await rt.shutdown();
+    expect(rt.keys()).toEqual([]);
+    expect(rt.has("a")).toBe(false);
+    expect(rt.has("b")).toBe(false);
+  });
+
+  it("stderrTail captures stderr output", async () => {
+    const rt = track(createWorkerRuntime(baseConfig(stderrWorkerPath)));
+    await rt.start("s");
+    await vi.waitFor(() => {
+      expect(rt.stderrTail("s")).toContain("stderr-marker");
+    });
+    await rt.shutdown();
+  });
+});
+
+function isEchoOf(msg: unknown, payload: unknown): boolean {
+  return (
+    typeof msg === "object" &&
+    msg !== null &&
+    (msg as Record<string, unknown>).type === "echo" &&
+    JSON.stringify((msg as Record<string, unknown>).payload) === JSON.stringify(payload)
+  );
+}

packages/daemon/src/worker-pool.ts

@@ -1,19 +1,13 @@
 /**
- * Sense worker pool — forked child processes per sense group (IPC lifecycle).
+ * Sense worker pool — thin wrapper around WorkerRuntime (RFC-006): one fork per sense group.
  */
 
-import { fork } from "node:child_process";
-import type { ChildProcess } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import type { ComputeMessage, ShutdownMessage } from "./ipc.js";
-import { parseWorkerMessage } from "./ipc.js";
-import {
-  formatCapturedStderrTail,
-  formatChildExitSummary,
-  teeCapturedStderr,
-} from "./worker-fork-support.js";
+import type { ComputeMessage } from "./ipc.js";
+import { formatCapturedStderrTail, formatChildExitSummary } from "./worker-fork-support.js";
+import { createWorkerRuntime } from "./worker-runtime.js";
 
 export function resolveWorkerScript(): string {
   const __filename = fileURLToPath(import.meta.url);
@@ -21,17 +15,12 @@ export function resolveWorkerScript(): string {
   return join(__dir, "sense-worker.js");
 }
 
-type WorkerEntry = {
-  group: string;
-  process: ChildProcess;
-};
-
 export type SenseWorkerPoolOptions = {
   nerveRoot: string;
   workerScript: string;
   /** Invoked for every IPC message from a worker (including ready / signal / error). */
   onWorkerMessage: (raw: unknown) => void;
-  /** Sense names in a group — used when clearing scheduler state on crash or restart. */
+  /** Sense names in a group — reserved for scheduler-aligned cleanup (kernel passes current config). */
   sensesForGroup: (group: string) => string[];
   /**
    * Called when a worker exits with non-zero code before scheduling a respawn
@@ -58,144 +47,106 @@ export type SenseWorkerPool = {
   activeGroupCount: () => number;
 };
 
-function spawnWorker(
-  nerveRoot: string,
-  group: string,
-  workerScript: string,
-  stderrTail: { value: string },
-): ChildProcess {
-  const child = fork(workerScript, ["--group", group, "--root", nerveRoot], {
-    stdio: ["ignore", "inherit", "pipe", "ipc"],
-  });
-  teeCapturedStderr(child, stderrTail);
-  child.on("error", (err) => {
-    if ((err as NodeJS.ErrnoException).code !== "EPIPE") {
-      console.error("[worker] error:", err.message);
-    }
-  });
-  return child;
-}
-
-function sendComputeToProcess(worker: ChildProcess, senseName: string): void {
-  if (worker.connected === false) return;
-  const msg: ComputeMessage = { type: "compute", sense: senseName };
-  try {
-    worker.send(msg);
-  } catch {
-    // IPC channel closed between connected check and send
-  }
-}
-
-function sendShutdownToProcess(worker: ChildProcess): void {
-  if (worker.connected === false) return;
-  const msg: ShutdownMessage = { type: "shutdown" };
-  try {
-    worker.send(msg);
-  } catch {
-    // IPC channel closed between connected check and send
-  }
-}
-
-function waitForExit(child: ChildProcess, timeoutMs: number): Promise<void> {
-  return new Promise((resolve) => {
-    const timer = setTimeout(() => {
-      child.kill("SIGKILL");
-      resolve();
-    }, timeoutMs);
-    child.once("exit", () => {
-      clearTimeout(timer);
-      resolve();
-    });
-  });
-}
+/** Matches legacy pool: long crash window, 1s respawn delay, practical unlimited respawns. */
+const SENSE_WORKER_RESPAWN = {
+  enabled: true,
+  maxCrashes: 100_000,
+  windowMs: 86_400_000,
+  delayMs: 1000,
+} as const;
 
 export function createSenseWorkerPool(options: SenseWorkerPoolOptions): SenseWorkerPool {
-  const workers = new Map<string, WorkerEntry>();
-
-  function startWorker(group: string): Promise<void> {
-    const stderrTail = { value: "" };
-    const child = spawnWorker(options.nerveRoot, group, options.workerScript, stderrTail);
-
-    let workerReadyResolve: (() => void) | undefined;
-    const workerReady = new Promise<void>((resolve) => {
-      workerReadyResolve = resolve;
-    });
-
-    child.on("message", (raw: unknown) => {
-      const result = parseWorkerMessage(raw);
-      if (result.ok && result.value.type === "ready") {
-        workerReadyResolve?.();
-      }
+  const runtime = createWorkerRuntime<string>({
+    script: options.workerScript,
+    argsForKey: (group) => ["--group", group, "--root", options.nerveRoot],
+    forwardStderr: true,
+    onMessage: (_key, raw) => {
       options.onWorkerMessage(raw);
-    });
-
-    child.on("exit", (code, signal) => {
-      const summary = formatChildExitSummary(code, signal ?? null);
+    },
+    onReady: (_key, msg) => {
+      options.onWorkerMessage(msg);
+    },
+    onExit: (group, code, signal) => {
+      const sig =
+        signal === null || signal === undefined || signal === ""
+          ? null
+          : (signal as NodeJS.Signals);
+      const summary = formatChildExitSummary(code, sig);
       process.stderr.write(
-        `[kernel] worker for group "${group}" exited (${summary})${formatCapturedStderrTail(stderrTail.value)}\n`,
+        `[kernel] worker for group "${group}" exited (${summary})${formatCapturedStderrTail(runtime.stderrTail(group))}\n`,
       );
-      workerReadyResolve?.();
       if (!options.isStopped() && code !== 0) {
         process.stderr.write(`[kernel] respawning worker for group "${group}" in 1s\n`);
         options.onWorkerCrashed(group);
-        setTimeout(() => {
-          if (!options.isStopped()) {
-            startWorker(group);
-          }
-        }, 1000);
       }
-    });
+    },
+    respawn: {
+      ...SENSE_WORKER_RESPAWN,
+      allowRespawn: (_group) => !options.isStopped(),
+    },
+    shutdownTimeoutMs: 5000,
+  });
 
-    workers.set(group, { group, process: child });
-    return workerReady;
+  /** Groups we have ever started — mirrors legacy Map presence for `restartGroup` no-op when unknown. */
+  const trackedGroups = new Set<string>();
+  /** Marks groups mid-evict so `hasWorkerForGroup` drops immediately (legacy synchronous eviction). */
+  const evicting = new Set<string>();
+
+  async function startWorker(group: string): Promise<void> {
+    trackedGroups.add(group);
+    await runtime.start(group);
   }
 
   async function restartGroup(group: string): Promise<void> {
-    const entry = workers.get(group);
-    if (entry === undefined) return;
-
-    options.onBeforeGroupRestart(group);
-
-    sendShutdownToProcess(entry.process);
-    await waitForExit(entry.process, 5000);
-
-    if (!options.isStopped()) {
-      await startWorker(group);
+    if (!trackedGroups.has(group)) {
+      return;
     }
+    options.onBeforeGroupRestart(group);
+    await runtime.drain(group);
   }
 
   function evictGroup(group: string): void {
-    const entry = workers.get(group);
-    if (entry === undefined) return;
-    sendShutdownToProcess(entry.process);
-    workers.delete(group);
+    trackedGroups.delete(group);
+    evicting.add(group);
+    void runtime.evict(group).finally(() => {
+      evicting.delete(group);
+    });
   }
 
   async function shutdownAll(): Promise<void> {
-    const exitPromises: Promise<void>[] = [];
-    for (const entry of workers.values()) {
-      sendShutdownToProcess(entry.process);
-      exitPromises.push(waitForExit(entry.process, 5000));
-    }
-    await Promise.all(exitPromises);
+    await runtime.shutdown();
+    trackedGroups.clear();
+    evicting.clear();
   }
 
   function sendCompute(group: string, senseName: string): void {
-    const entry = workers.get(group);
-    if (entry === undefined) return;
-    sendComputeToProcess(entry.process, senseName);
+    if (!trackedGroups.has(group) || evicting.has(group)) {
+      return;
+    }
+    // Legacy pool: `child.send` no-op when IPC is closed (still allow cold start: child === null).
+    if (runtime.hasDisconnectedChild(group)) {
+      return;
+    }
+    const msg: ComputeMessage = { type: "compute", sense: senseName };
+    if (!runtime.trySendSync(group, msg)) {
+      void runtime.send(group, msg).catch(() => {
+        // IPC channel may close between scheduling and send — same as legacy try/catch on child.send
+      });
+    }
   }
 
   function getWorkerPid(group: string): number | null {
-    return workers.get(group)?.process.pid ?? null;
+    return runtime.pid(group);
   }
 
+  /** True once `startWorker` has been called for the group and it is not mid-evict (matches legacy Map key). */
   function hasWorkerForGroup(group: string): boolean {
-    return workers.has(group);
+    return trackedGroups.has(group) && !evicting.has(group);
   }
 
+  /** Count of sense groups with a worker slot (includes not-yet-ready), excluding evicted keys. */
   function activeGroupCount(): number {
-    return workers.size;
+    return trackedGroups.size;
   }
 
   return {

packages/daemon/src/worker-runtime.ts

@@ -0,0 +1,404 @@
+/**
+ * Generic message-routed worker process manager (RFC-006).
+ * One forked Node child per key; cold start, crash respawn, drain/evict, shutdown.
+ */
+
+import { type ChildProcess, type Serializable, fork } from "node:child_process";
+import { isPlainRecord } from "@uncaged/nerve-core";
+
+const STDERR_TAIL_MAX_CHARS = 2048;
+
+export type WorkerRuntimeConfig<K extends string> = {
+  script: string;
+  argsForKey: (key: K) => string[];
+  /** When false, stderr is not captured into `stderrTail` (e.g. tests without a pipe). */
+  forwardStderr: boolean;
+  onMessage: (key: K, msg: unknown) => void;
+  onReady: (key: K, msg: unknown) => void;
+  onExit: (key: K, code: number | null, signal: string | null) => void;
+  respawn: {
+    enabled: boolean;
+    maxCrashes: number;
+    windowMs: number;
+    delayMs: number;
+    /** When non-null, return false to skip automatic respawn after an unexpected exit. */
+    allowRespawn: ((key: K) => boolean) | null;
+  };
+  shutdownTimeoutMs: number;
+};
+
+export type WorkerRuntime<K extends string> = {
+  send: (key: K, msg: unknown) => Promise<void>;
+  /** When the worker is already ready and IPC-connected, sends synchronously (returns true). Otherwise false — caller may fall back to `send`. */
+  trySendSync: (key: K, msg: unknown) => boolean;
+  start: (key: K) => Promise<void>;
+  evict: (key: K) => Promise<void>;
+  drain: (key: K) => Promise<void>;
+  shutdown: () => Promise<void>;
+  has: (key: K) => boolean;
+  /** True when a child exists but IPC is disconnected (legacy pool skipped sends in this case). */
+  hasDisconnectedChild: (key: K) => boolean;
+  pid: (key: K) => number | null;
+  keys: () => K[];
+  stderrTail: (key: K) => string;
+};
+
+type WorkerMachineState = "stopped" | "starting" | "ready" | "draining";
+
+type ReadyWaiter = {
+  resolve: () => void;
+  reject: (err: Error) => void;
+};
+
+/** Internal: one forked process slot (ManagedWorker). */
+type WorkerSlot<K extends string> = {
+  key: K;
+  state: WorkerMachineState;
+  child: ChildProcess | null;
+  pid: number | null;
+  stderrTail: string;
+  crashTimestamps: number[];
+  expectExit: boolean;
+  readyWaiters: ReadyWaiter[];
+  opChain: Promise<void>;
+};
+
+function isReadyIpcMessage(raw: unknown): boolean {
+  return isPlainRecord(raw) && raw.type === "ready";
+}
+
+function signalToString(signal: NodeJS.Signals | null): string | null {
+  if (signal === null) {
+    return null;
+  }
+  return String(signal);
+}
+
+function attachStderrTail<K extends string>(child: ChildProcess, slot: WorkerSlot<K>): void {
+  const stream = child.stderr;
+  if (stream == null) {
+    return;
+  }
+  stream.setEncoding("utf8");
+  stream.on("data", (chunk: string | Buffer) => {
+    const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    slot.stderrTail = (slot.stderrTail + text).slice(-STDERR_TAIL_MAX_CHARS);
+  });
+}
+
+function enqueueOp<K extends string>(slot: WorkerSlot<K>, fn: () => Promise<void>): Promise<void> {
+  const run = slot.opChain.then(fn, fn);
+  slot.opChain = run.then(
+    () => {},
+    () => {},
+  );
+  return run;
+}
+
+function resolveReadyWaiters<K extends string>(slot: WorkerSlot<K>): void {
+  const waiters = slot.readyWaiters;
+  slot.readyWaiters = [];
+  for (const w of waiters) {
+    w.resolve();
+  }
+}
+
+function rejectReadyWaiters<K extends string>(slot: WorkerSlot<K>, err: Error): void {
+  const waiters = slot.readyWaiters;
+  slot.readyWaiters = [];
+  for (const w of waiters) {
+    w.reject(err);
+  }
+}
+
+function waitForReady<K extends string>(
+  slot: WorkerSlot<K>,
+  shutdownTimeoutMs: number,
+): Promise<void> {
+  if (slot.state === "ready" && slot.child !== null && slot.child.connected) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        reject(new Error(`Worker "${String(slot.key)}" ready timeout`));
+      }
+    }, shutdownTimeoutMs);
+    slot.readyWaiters.push({
+      resolve: () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        resolve();
+      },
+      reject: (err: Error) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        reject(err);
+      },
+    });
+  });
+}
+
+async function waitForChildExit(child: ChildProcess, timeoutMs: number): Promise<void> {
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    child.once("exit", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+export function createWorkerRuntime<K extends string>(
+  config: WorkerRuntimeConfig<K>,
+): WorkerRuntime<K> {
+  const workers = new Map<K, WorkerSlot<K>>();
+
+  function getOrCreateSlot(key: K): WorkerSlot<K> {
+    let slot = workers.get(key);
+    if (slot === undefined) {
+      slot = {
+        key,
+        state: "stopped",
+        child: null,
+        pid: null,
+        stderrTail: "",
+        crashTimestamps: [],
+        expectExit: false,
+        readyWaiters: [],
+        opChain: Promise.resolve(),
+      };
+      workers.set(key, slot);
+    }
+    return slot;
+  }
+
+  function handleWorkerMessage(slot: WorkerSlot<K>, msg: unknown): void {
+    if (isReadyIpcMessage(msg)) {
+      if (slot.state === "starting") {
+        slot.state = "ready";
+        config.onReady(slot.key, msg);
+        resolveReadyWaiters(slot);
+      }
+      return;
+    }
+    config.onMessage(slot.key, msg);
+  }
+
+  function onChildExit(
+    slot: WorkerSlot<K>,
+    code: number | null,
+    signal: NodeJS.Signals | null,
+  ): void {
+    config.onExit(slot.key, code, signalToString(signal));
+
+    if (slot.child !== null) {
+      slot.child.removeAllListeners("message");
+      slot.child.removeAllListeners("exit");
+    }
+
+    const wasExpect = slot.expectExit;
+    slot.expectExit = false;
+
+    slot.child = null;
+    slot.pid = null;
+
+    if (wasExpect) {
+      slot.state = "stopped";
+      return;
+    }
+
+    rejectReadyWaiters(slot, new Error(`Worker "${String(slot.key)}" exited unexpectedly`));
+    slot.state = "stopped";
+
+    void enqueueOp(slot, async () => {
+      await handleUnexpectedCrashRecovery(slot);
+    });
+  }
+
+  function registerChild(slot: WorkerSlot<K>, child: ChildProcess): void {
+    slot.child = child;
+    slot.pid = child.pid ?? null;
+    if (config.forwardStderr) {
+      attachStderrTail(child, slot);
+    }
+    child.on("message", (msg: unknown) => {
+      handleWorkerMessage(slot, msg);
+    });
+    child.on("exit", (code, sig) => {
+      onChildExit(slot, code, sig ?? null);
+    });
+  }
+
+  async function forkAndWaitReady(slot: WorkerSlot<K>): Promise<void> {
+    if (slot.state === "ready" && slot.child !== null && slot.child.connected) {
+      return;
+    }
+
+    slot.state = "starting";
+
+    let child: ChildProcess;
+    try {
+      child = fork(config.script, config.argsForKey(slot.key), {
+        stdio: ["ignore", "inherit", "pipe", "ipc"],
+        env: process.env,
+      });
+    } catch (e) {
+      slot.state = "stopped";
+      const err = e instanceof Error ? e : new Error(String(e));
+      rejectReadyWaiters(slot, err);
+      throw err;
+    }
+
+    registerChild(slot, child);
+    await waitForReady(slot, config.shutdownTimeoutMs);
+  }
+
+  async function gracefulStop(slot: WorkerSlot<K>): Promise<void> {
+    if (slot.child === null) {
+      return;
+    }
+    slot.expectExit = true;
+    slot.state = "draining";
+    const child = slot.child;
+    try {
+      child.send({ type: "shutdown" });
+    } catch {
+      // IPC channel may have closed between null-check and send
+    }
+    await waitForChildExit(child, config.shutdownTimeoutMs);
+  }
+
+  async function handleUnexpectedCrashRecovery(slot: WorkerSlot<K>): Promise<void> {
+    if (!config.respawn.enabled) {
+      return;
+    }
+    if (config.respawn.allowRespawn !== null && !config.respawn.allowRespawn(slot.key)) {
+      return;
+    }
+
+    const now = Date.now();
+    slot.crashTimestamps.push(now);
+    slot.crashTimestamps = slot.crashTimestamps.filter((t) => now - t <= config.respawn.windowMs);
+
+    if (slot.crashTimestamps.length >= config.respawn.maxCrashes) {
+      console.error(
+        `[WorkerRuntime] worker "${String(slot.key)}" exceeded crash limit (${String(config.respawn.maxCrashes)} in ${String(config.respawn.windowMs)}ms); not respawning`,
+      );
+      return;
+    }
+
+    await new Promise<void>((resolve) => setTimeout(resolve, config.respawn.delayMs));
+    await forkAndWaitReady(slot);
+  }
+
+  async function shutdownWorker(slot: WorkerSlot<K>): Promise<void> {
+    await gracefulStop(slot);
+    workers.delete(slot.key);
+  }
+
+  function isActive(slot: WorkerSlot<K>): boolean {
+    return slot.state === "ready" && slot.child !== null && slot.child.connected;
+  }
+
+  return {
+    send: async (key: K, msg: unknown) => {
+      const slot = getOrCreateSlot(key);
+      await enqueueOp(slot, async () => {
+        await forkAndWaitReady(slot);
+        const child = slot.child;
+        if (child === null || !child.connected) {
+          throw new Error(`Worker "${String(key)}" is not connected`);
+        }
+        child.send(msg as Serializable);
+      });
+    },
+
+    trySendSync: (key: K, msg: unknown): boolean => {
+      const slot = workers.get(key);
+      if (slot === undefined || !isActive(slot)) {
+        return false;
+      }
+      const child = slot.child;
+      if (child === null || !child.connected) {
+        return false;
+      }
+      try {
+        child.send(msg as Serializable);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+
+    start: async (key: K) => {
+      const slot = getOrCreateSlot(key);
+      await enqueueOp(slot, async () => {
+        await forkAndWaitReady(slot);
+      });
+    },
+
+    evict: async (key: K) => {
+      const slot = getOrCreateSlot(key);
+      await enqueueOp(slot, async () => {
+        await gracefulStop(slot);
+        workers.delete(key);
+      });
+    },
+
+    drain: async (key: K) => {
+      const slot = getOrCreateSlot(key);
+      await enqueueOp(slot, async () => {
+        if (slot.child === null) {
+          await forkAndWaitReady(slot);
+          return;
+        }
+        await gracefulStop(slot);
+        await forkAndWaitReady(slot);
+      });
+    },
+
+    shutdown: async () => {
+      const snapshot = [...workers.values()];
+      await Promise.all(snapshot.map((slot) => enqueueOp(slot, () => shutdownWorker(slot))));
+    },
+
+    has: (key: K) => {
+      const slot = workers.get(key);
+      return slot !== undefined && isActive(slot);
+    },
+
+    hasDisconnectedChild: (key: K): boolean => {
+      const slot = workers.get(key);
+      if (slot === undefined || slot.child === null) {
+        return false;
+      }
+      return !slot.child.connected;
+    },
+
+    pid: (key: K) => {
+      const slot = workers.get(key);
+      if (slot === undefined || !isActive(slot) || slot.pid === null) {
+        return null;
+      }
+      return slot.pid;
+    },
+
+    keys: () => [...workers.values()].filter((slot) => isActive(slot)).map((slot) => slot.key),
+
+    stderrTail: (key: K) => {
+      const slot = workers.get(key);
+      return slot === undefined ? "" : slot.stderrTail;
+    },
+  };
+}

packages/workflow-utils/src/__tests__/create-llm-adapter.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { START, type ThreadContext } from "@uncaged/nerve-core";
+
+import { createLlmAdapter } from "../create-llm-adapter.js";
+
+function makeCtx(threadId: string, userContent: string): ThreadContext {
+  return {
+    threadId,
+    start: {
+      role: START,
+      content: userContent,
+      meta: { maxRounds: 10, threadId },
+      timestamp: 1,
+    },
+    steps: [],
+  };
+}
+
+describe("createLlmAdapter", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("posts system + user (start.content) and returns assistant text", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: async () =>
+        JSON.stringify({
+          choices: [{ message: { content: "model reply" } }],
+        }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const provider = { baseUrl: "https://api.example/v1", apiKey: "k", model: "m" };
+    const adapter = createLlmAdapter(provider);
+    const out = await adapter(makeCtx("t1", "trigger text"), "system instructions");
+
+    expect(out).toBe("model reply");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    const body = JSON.parse(init.body as string) as {
+      model: string;
+      messages: Array<{ role: string; content: string }>;
+    };
+    expect(body.model).toBe("m");
+    expect(body.messages).toEqual([
+      { role: "system", content: "system instructions" },
+      { role: "user", content: "trigger text" },
+    ]);
+  });
+});

packages/workflow-utils/src/create-llm-adapter.ts

@@ -0,0 +1,22 @@
+import type { AgentFn, ThreadContext } from "@uncaged/nerve-core";
+
+import { formatLlmError } from "./shared/format-error.js";
+import { chatCompletionText } from "./shared/llm-chat.js";
+import type { LlmProvider } from "./shared/llm-extract.js";
+
+/** Single-turn chat adapter: system comes from `createRole` prompt; user is the thread start frame. */
+export function createLlmAdapter(provider: LlmProvider): AgentFn {
+  return async (ctx: ThreadContext, systemPrompt: string) => {
+    const result = await chatCompletionText({
+      provider,
+      messages: [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: ctx.start.content },
+      ],
+    });
+    if (!result.ok) {
+      throw new Error(`llm: ${formatLlmError(result.error)}`);
+    }
+    return result.value;
+  };
+}

packages/workflow-utils/src/index.ts

@@ -1,9 +1,6 @@
 // Primary API — role factory templates
+export { createLlmAdapter } from "./create-llm-adapter.js";
 export { createRole, type LlmExtractorConfig } from "./create-role.js";
-export { createCursorRole } from "./role-cursor.js";
-export { createHermesRole } from "./role-hermes.js";
-export { createLlmRole } from "./role-llm.js";
-export { createReActRole } from "./role-react.js";
 export { llmExtract, llmExtractWithRetry } from "./shared/llm-extract.js";
 export { mergeExtractConfig, type ExtractConfigLayer } from "./shared/merge-extract-config.js";
 export {
@@ -37,19 +34,5 @@ export {
 } from "@uncaged/nerve-core";
 export type { LlmError, LlmProvider } from "./shared/llm-extract.js";
 export { isDryRun } from "./role-types.js";
-export type {
-  CliPromptFn,
-  CursorRoleDefaults,
-  CursorRoleRequired,
-  HermesRoleDefaults,
-  HermesRoleRequired,
-  LlmMessage,
-  LlmPromptFn,
-  LlmRoleDefaults,
-  LlmRoleRequired,
-  MetaExtractConfig,
-  ReActRoleDefaults,
-  ReActRoleRequired,
-  ReActTool,
-} from "./role-types.js";
+export type { LlmMessage, MetaExtractConfig } from "./role-types.js";
 export type { LlmChatError } from "./shared/llm-chat.js";