@percepta/kaizen 0.6.0 → 0.8.0

package/dist/lib/runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"runner.js","names":[],"sources":["../../src/lib/runner.ts"],"sourcesContent":["import { type ChildProcess, execSync, spawn } from \"node:child_process\";\nimport { createWriteStream, existsSync, writeFileSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport { arch, hostname, platform } from \"node:os\";\nimport { extname, join } from \"node:path\";\nimport type { Readable } from \"node:stream\";\nimport type { LinearIssueLink } from \"../../shared/linear-issue.js\";\nimport {\n  type CompleteEvent,\n  type CrashedEvent,\n  type Event,\n  type ItemEvent,\n  NdjsonReader,\n  type PromotionEvent,\n} from \"./events.js\";\nimport {\n  type ManifestFile,\n  type StateFile,\n  currentBaseline,\n  listRuns,\n} from \"./leaderboard.js\";\nimport { decidePromotion } from \"./promotion.js\";\nimport {\n  appendNdjsonLine,\n  clearLock,\n  ensureDir,\n  generateRunId,\n  hypothesesPath,\n  isPidAlive,\n  systemRunsDir,\n  readJsonIfExists,\n  readLock,\n  runDir,\n  writeJsonAtomic,\n  writeLock,\n} from \"./run-dir.js\";\nimport { type SystemDef, loadSystem, resolveEvalPath } from \"./system.js\";\n\nexport interface RunOptions {\n  workspace: string;\n  stateDir?: string;\n  systemId: string;\n  variant: string;\n  parent: string | null;\n  hypothesis: string;\n  diagnostic: boolean;\n  noAutoPromote: boolean;\n  maxItems: number | null;\n  kaizenVersion: string;\n  linearIssue: LinearIssueLink | null;\n}\n\nexport interface RunResult {\n  runId: string;\n  status: \"complete\" | \"crashed\" | \"aborted\";\n  score: number | null;\n  promoted: boolean | null;\n  exitCode: number;\n}\n\nconst FAILURE_K = 10;\nconst require = createRequire(import.meta.url);\n\nexport async function runExperiment(opts: RunOptions): Promise<RunResult> {\n  const stateDir = opts.stateDir ?? join(opts.workspace, \".kaizen\");\n\n  // 0. Reap stale runs across this system (lock present, PID dead, no terminal event).\n  reapStaleRuns(stateDir, opts.systemId);\n\n  // 1. Load system + resolve eval interpreter.\n  const system = loadSystem(opts.workspace, opts.systemId);\n  const evalAbs = resolveEvalPath(opts.workspace, system);\n  if (!existsSync(evalAbs)) {\n    throw new Error(\n      `eval script not found at ${evalAbs} (declared as run_eval: ${system.frontmatter.run_eval} in systems/${opts.systemId}.md)`,\n    );\n  }\n  const interp = detectInterpreter(evalAbs);\n\n  // 2. Generate run_id, create dir, write manifest, take lock.\n  const runId = generateRunId();\n  const dir = runDir(stateDir, opts.systemId, runId);\n  ensureDir(dir);\n  const startedAt = new Date().toISOString();\n  const manifest: ManifestFile = {\n    run_id: runId,\n    system: opts.systemId,\n    variant: opts.variant,\n    parent_id: opts.parent,\n    hypothesis: opts.hypothesis,\n    git_sha: gitSha(opts.workspace),\n    git_branch: gitBranch(opts.workspace),\n    worktree_root: gitTopLevel(opts.workspace),\n    git_common_dir: gitCommonDir(opts.workspace),\n    eval_version: system.frontmatter.eval_version,\n    dataset_version: system.frontmatter.dataset_version,\n    started_at: startedAt,\n    host: `${platform()}-${arch()} (${hostname()})`,\n    kaizen_version: opts.kaizenVersion,\n    state_dir: stateDir,\n    diagnostic: opts.diagnostic,\n    linear_issue_id: opts.linearIssue?.id ?? null,\n    linear_issue_url: opts.linearIssue?.url ?? null,\n  };\n  writeJsonAtomic(join(dir, \"manifest.json\"), manifest);\n  writeLock(dir);\n\n  const eventsPath = join(dir, \"events.jsonl\");\n  const stdoutPath = join(dir, \"stdout.log\");\n  const stderrPath = join(dir, \"stderr.log\");\n\n  // 3. Build initial state and write it.\n  const state: StateFile & {\n    system: string;\n    variant: string;\n    eval_version: number;\n    dataset_version: string;\n    started_at: string;\n    updated_at: string;\n    n_done: number;\n  } = {\n    run_id: runId,\n    system: opts.systemId,\n    variant: opts.variant,\n    status: \"running\",\n    score: null,\n    n_total: null,\n    n_done: 0,\n    promoted: null,\n    started_at: startedAt,\n    updated_at: startedAt,\n    ended_at: null,\n    eval_version: system.frontmatter.eval_version,\n    dataset_version: system.frontmatter.dataset_version,\n  };\n  writeJsonAtomic(join(dir, \"state.json\"), state);\n\n  // 4. Spawn the eval with fd 3 piped for events.\n  // For shebang scripts (cmd === evalAbs) we omit evalAbs from args, since\n  // spawn already passes cmd as argv[0]. Including it would duplicate the\n  // path as a positional and break argparse-based eval scripts.\n  const evalArgs = [\n    ...interp.preArgs,\n    ...(interp.cmd === evalAbs ? [] : [evalAbs]),\n    \"--variant\",\n    opts.variant,\n    \"--dataset\",\n    system.frontmatter.dataset_version,\n    \"--out-fd\",\n    \"3\",\n  ];\n  const effectiveMax = opts.diagnostic ? 5 : opts.maxItems;\n  if (effectiveMax !== null && effectiveMax !== undefined) {\n    evalArgs.push(\"--max-items\", String(effectiveMax));\n  }\n\n  const stdoutLog = createWriteStream(stdoutPath);\n  const stderrLog = createWriteStream(stderrPath);\n  let stderrTail = \"\";\n\n  const child: ChildProcess = spawn(interp.cmd, evalArgs, {\n    cwd: opts.workspace,\n    stdio: [\"ignore\", \"pipe\", \"pipe\", \"pipe\"],\n    env: process.env,\n  });\n\n  // Tee stdout/stderr to log files. Capture last ~4KB of stderr for crash diagnostics.\n  child.stdout!.on(\"data\", (chunk: Buffer) => stdoutLog.write(chunk));\n  child.stderr!.on(\"data\", (chunk: Buffer) => {\n    stderrLog.write(chunk);\n    stderrTail = (stderrTail + chunk.toString(\"utf-8\")).slice(-4096);\n  });\n\n  // Event stream on fd 3. spawn(['ignore','pipe','pipe','pipe']) makes child.stdio[3] a Readable.\n  const eventChan = child.stdio[3] as Readable;\n  const itemEvents: ItemEvent[] = [];\n  let sawComplete: CompleteEvent | null = null;\n  let parseErrors = 0;\n  let contractErrors = 0;\n\n  const reader = new NdjsonReader(\n    (e) => onEvent(e),\n    (line, err) => {\n      parseErrors++;\n      stderrLog.write(\n        `[runner] could not parse event: ${line.slice(0, 200)}\\n`,\n      );\n      stderrLog.write(\n        `[runner] ${err instanceof Error ? err.message : String(err)}\\n`,\n      );\n    },\n  );\n  eventChan.setEncoding?.(\"utf-8\");\n  eventChan.on(\"data\", (chunk) => reader.push(chunk as string | Buffer));\n  // The event channel may close after the child's `exit` fires (Node docs\n  // explicitly note stdio streams can outlive `exit`). We must drain it\n  // before deciding terminal state — otherwise a successful run that\n  // emitted a `complete` event still in the pipe buffer gets misclassified\n  // as \"crashed\" because `sawComplete` is observed null.\n  const eventChanEnded = new Promise<void>((resolve) => {\n    eventChan.on(\"end\", () => {\n      reader.end();\n      resolve();\n    });\n    eventChan.on(\"close\", () => {\n      reader.end();\n      resolve();\n    });\n  });\n\n  function onEvent(e: Event): void {\n    appendNdjsonLine(eventsPath, e);\n    if (e.type === \"start\") {\n      const s = e;\n      if (s.eval_version !== system.frontmatter.eval_version) {\n        contractErrors++;\n        stderrLog.write(\n          `[runner] start.eval_version ${s.eval_version} does not match system eval_version ${system.frontmatter.eval_version}\\n`,\n        );\n      }\n      if (s.dataset_version !== system.frontmatter.dataset_version) {\n        contractErrors++;\n        stderrLog.write(\n          `[runner] start.dataset_version ${s.dataset_version} does not match system dataset_version ${system.frontmatter.dataset_version}\\n`,\n        );\n      }\n      state.n_total = s.n;\n      state.updated_at = new Date().toISOString();\n      writeJsonAtomic(join(dir, \"state.json\"), state);\n    } else if (e.type === \"item\") {\n      const it = e;\n      itemEvents.push(it);\n      state.n_done = (state.n_done ?? 0) + 1;\n      state.updated_at = new Date().toISOString();\n      writeJsonAtomic(join(dir, \"state.json\"), state);\n    } else if (e.type === \"progress\") {\n      // n_done is authoritative from item events; progress is informational.\n      state.updated_at = new Date().toISOString();\n      writeJsonAtomic(join(dir, \"state.json\"), state);\n    } else if (e.type === \"complete\") {\n      sawComplete = e;\n      if (state.n_total !== null && sawComplete.n !== state.n_total) {\n        contractErrors++;\n        stderrLog.write(\n          `[runner] complete.n ${sawComplete.n} does not match start.n ${state.n_total}\\n`,\n        );\n      }\n      state.score = sawComplete.score;\n      state.updated_at = new Date().toISOString();\n      writeJsonAtomic(join(dir, \"state.json\"), state);\n    }\n    // error/promotion/etc. — no state mutation here\n  }\n\n  // 5. Wait for child to exit AND for the event channel to be fully drained.\n  // Both must complete before we decide terminal state — the child's exit\n  // doesn't guarantee its stdio buffers have been consumed by us yet.\n  const { code, signal } = await waitForExit(child);\n  await eventChanEnded;\n\n  // Flush logs.\n  stdoutLog.end();\n  stderrLog.end();\n  await Promise.all([\n    new Promise<void>((r) => stdoutLog.on(\"close\", () => r())),\n    new Promise<void>((r) => stderrLog.on(\"close\", () => r())),\n  ]);\n\n  // 6. Decide terminal state.\n  const endedAt = new Date().toISOString();\n  if (\n    code === 0 &&\n    sawComplete !== null &&\n    parseErrors === 0 &&\n    contractErrors === 0\n  ) {\n    state.status = \"complete\";\n    state.score = (sawComplete as CompleteEvent).score;\n    // The complete event is already in events.jsonl from onEvent.\n  } else {\n    const crashed: CrashedEvent = {\n      type: \"crashed\",\n      exit_code: code,\n      signal: signal ?? null,\n      stderr_tail: stderrTail.slice(-2000),\n      reason:\n        code !== 0 && code !== null\n          ? `eval exited with code ${code}`\n          : signal\n            ? `eval terminated by signal ${signal}`\n            : parseErrors > 0\n              ? `eval emitted ${parseErrors} malformed event(s)`\n              : contractErrors > 0\n                ? `eval emitted ${contractErrors} contract-violating event(s)`\n                : sawComplete !== null\n                  ? \"eval emitted complete but exited non-zero\"\n                  : \"eval exited without emitting complete event\",\n      ts: Date.now() / 1000,\n    };\n    appendNdjsonLine(eventsPath, crashed);\n    state.status = \"crashed\";\n  }\n  state.ended_at = endedAt;\n  state.updated_at = endedAt;\n\n  // 7. Write failures.jsonl (worst-K).\n  if (itemEvents.length > 0) {\n    const sorted = [...itemEvents].sort((a, b) => a.score - b.score);\n    const worst = sorted.slice(0, Math.min(FAILURE_K, sorted.length));\n    const text =\n      worst.map((it) => JSON.stringify(it)).join(\"\\n\") +\n      (worst.length > 0 ? \"\\n\" : \"\");\n    writeFileSync(join(dir, \"failures.jsonl\"), text);\n  }\n\n  // 8. Promotion (only if completed cleanly).\n  let promotionEvent: PromotionEvent | null = null;\n  if (state.status === \"complete\" && !opts.noAutoPromote) {\n    const allRuns = listRuns(stateDir, opts.systemId).filter(\n      (r) => r.run_id !== runId,\n    );\n    const baselineRun = currentBaseline(\n      allRuns,\n      system.frontmatter.eval_version,\n      system.frontmatter.dataset_version,\n    );\n    const baseline = baselineRun\n      ? {\n          run_id: baselineRun.run_id,\n          variant: baselineRun.variant,\n          score: baselineRun.score!,\n          events_path: baselineRun.events_path,\n        }\n      : null;\n    const decision = decidePromotion(\n      mapFromItems(itemEvents),\n      itemEvents,\n      baseline,\n      { subgroupKeys: subgroupKeys(system) },\n    );\n    promotionEvent = { type: \"promotion\", ts: Date.now() / 1000, ...decision };\n    appendNdjsonLine(eventsPath, promotionEvent);\n    state.promoted = decision.promoted;\n  } else if (opts.noAutoPromote) {\n    state.promoted = false;\n  }\n  writeJsonAtomic(join(dir, \"state.json\"), state);\n\n  // 9. Append hypothesis log line (every run, success or failure).\n  const hypoLine = {\n    run_id: runId,\n    system: opts.systemId,\n    variant: opts.variant,\n    parent_id: opts.parent,\n    hypothesis: opts.hypothesis,\n    status: state.status,\n    score: state.score,\n    promoted: state.promoted,\n    started_at: startedAt,\n    ended_at: endedAt,\n    eval_version: system.frontmatter.eval_version,\n    dataset_version: system.frontmatter.dataset_version,\n  };\n  appendNdjsonLine(hypothesesPath(stateDir, opts.systemId), hypoLine);\n\n  // 10. Clear lock.\n  clearLock(dir);\n\n  void parseErrors; // not surfaced yet; logged to stderr.log\n\n  return {\n    runId,\n    status: state.status as \"complete\" | \"crashed\" | \"aborted\",\n    score: state.score,\n    promoted: state.promoted ?? null,\n    exitCode: state.status === \"complete\" ? 0 : 1,\n  };\n}\n\n// --- helpers ---\n\ninterface InterpreterChoice {\n  cmd: string;\n  preArgs: string[];\n}\n\nfunction detectInterpreter(evalPath: string): InterpreterChoice {\n  const ext = extname(evalPath).toLowerCase();\n  if (ext === \".py\") return { cmd: \"python3\", preArgs: [] };\n  if (ext === \".js\" || ext === \".mjs\" || ext === \".cjs\")\n    return { cmd: \"node\", preArgs: [] };\n  if (ext === \".ts\" || ext === \".tsx\" || ext === \".mts\" || ext === \".cts\") {\n    return {\n      cmd: process.execPath,\n      preArgs: [\"--import\", require.resolve(\"tsx\")],\n    };\n  }\n  // Default: assume executable with shebang.\n  return { cmd: evalPath, preArgs: [] };\n}\n\nfunction waitForExit(\n  child: ChildProcess,\n): Promise<{ code: number | null; signal: NodeJS.Signals | null }> {\n  return new Promise((resolve) => {\n    child.on(\"exit\", (code: number | null, signal: NodeJS.Signals | null) =>\n      resolve({ code, signal }),\n    );\n  });\n}\n\nfunction gitSha(cwd: string): string | null {\n  try {\n    return (\n      execSync(\"git rev-parse HEAD\", {\n        cwd,\n        stdio: [\"ignore\", \"pipe\", \"ignore\"],\n      })\n        .toString()\n        .trim() || null\n    );\n  } catch {\n    return null;\n  }\n}\n\nfunction gitBranch(cwd: string): string | null {\n  try {\n    return (\n      execSync(\"git rev-parse --abbrev-ref HEAD\", {\n        cwd,\n        stdio: [\"ignore\", \"pipe\", \"ignore\"],\n      })\n        .toString()\n        .trim() || null\n    );\n  } catch {\n    return null;\n  }\n}\n\nfunction gitTopLevel(cwd: string): string | null {\n  try {\n    return (\n      execSync(\"git rev-parse --show-toplevel\", {\n        cwd,\n        stdio: [\"ignore\", \"pipe\", \"ignore\"],\n      })\n        .toString()\n        .trim() || null\n    );\n  } catch {\n    return null;\n  }\n}\n\nfunction gitCommonDir(cwd: string): string | null {\n  try {\n    return (\n      execSync(\"git rev-parse --git-common-dir\", {\n        cwd,\n        stdio: [\"ignore\", \"pipe\", \"ignore\"],\n      })\n        .toString()\n        .trim() || null\n    );\n  } catch {\n    return null;\n  }\n}\n\nfunction mapFromItems(items: ItemEvent[]): Map<string, number> {\n  const m = new Map<string, number>();\n  for (const it of items) m.set(it.id, it.score);\n  return m;\n}\n\nfunction subgroupKeys(system: SystemDef): string[] {\n  const sg = (\n    system.frontmatter as {\n      subgroups?: Array<{ field?: string; name?: string }>;\n    }\n  ).subgroups;\n  if (!Array.isArray(sg)) return [];\n  return sg.map((s) => s.field ?? s.name ?? \"\").filter(Boolean);\n}\n\n/**\n * Sweep stale runs whose lock points to a dead PID and which never recorded a terminal event.\n * Mark them `crashed` with reason \"supervisor died\" so the dashboard / log don't show ghosts.\n */\nexport function reapStaleRuns(stateDir: string, systemId: string): void {\n  const dir = systemRunsDir(stateDir, systemId);\n  if (!existsSync(dir)) return;\n  for (const run of listRuns(stateDir, systemId)) {\n    if (run.status !== \"running\") continue;\n    const lock = readLock(join(dir, run.run_id));\n    if (!lock) continue;\n    if (isPidAlive(lock.pid)) continue;\n    const reapedEvent: CrashedEvent = {\n      type: \"crashed\",\n      exit_code: null,\n      signal: null,\n      reason: `runner pid ${lock.pid} died without writing a terminal event; reaped`,\n      ts: Date.now() / 1000,\n    };\n    appendNdjsonLine(run.events_path, reapedEvent);\n\n    const state = readJsonIfExists<StateFile>(run.state_path);\n    if (state) {\n      state.status = \"crashed\";\n      state.ended_at = new Date().toISOString();\n      writeJsonAtomic(run.state_path, state);\n    }\n    clearLock(join(dir, run.run_id));\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"runner.js","names":[],"sources":["../../src/lib/runner.ts"],"sourcesContent":["import { type ChildProcess, execSync, spawn } from \"node:child_process\";\nimport { createWriteStream, existsSync, writeFileSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport { arch, hostname, platform } from \"node:os\";\nimport { extname, join } from \"node:path\";\nimport type { Readable } from \"node:stream\";\nimport type { LinearIssueLink } from \"../../shared/linear-issue.js\";\nimport {\n  type CompleteEvent,\n  type CrashedEvent,\n  type Event,\n  type ItemEvent,\n  NdjsonReader,\n  type PromotionEvent,\n} from \"./events.js\";\nimport {\n  type ManifestFile,\n  type StateFile,\n  currentBaseline,\n  listRuns,\n} from \"./leaderboard.js\";\nimport { resolveStateDir } from \"./paths.js\";\nimport { decidePromotion } from \"./promotion.js\";\nimport {\n  appendNdjsonLine,\n  clearLock,\n  ensureDir,\n  generateRunId,\n  hypothesesPath,\n  isPidAlive,\n  systemRunsDir,\n  readJsonIfExists,\n  readLock,\n  runDir,\n  writeJsonAtomic,\n  writeLock,\n} from \"./run-dir.js\";\nimport { type SystemDef, loadSystem, resolveEvalPath } from \"./system.js\";\n\nexport interface RunOptions {\n  workspace: string;\n  systemId: string;\n  variant: string;\n  parent: string | null;\n  hypothesis: string;\n  diagnostic: boolean;\n  noAutoPromote: boolean;\n  maxItems: number | null;\n  kaizenVersion: string;\n  linearIssue: LinearIssueLink | null;\n}\n\nexport interface RunResult {\n  runId: string;\n  status: \"complete\" | \"crashed\" | \"aborted\";\n  score: number | null;\n  promoted: boolean | null;\n  exitCode: number;\n}\n\nconst FAILURE_K = 10;\nconst require = createRequire(import.meta.url);\n\nexport async function runExperiment(opts: RunOptions): Promise<RunResult> {\n  const stateDir = resolveStateDir(opts.workspace);\n\n  // 0. Reap stale runs across this system (lock present, PID dead, no terminal event).\n  reapStaleRuns(stateDir, opts.systemId);\n\n  // 1. Load system + resolve eval interpreter.\n  const system = loadSystem(opts.workspace, opts.systemId);\n  const evalAbs = resolveEvalPath(opts.workspace, system);\n  if (!existsSync(evalAbs)) {\n    throw new Error(\n      `eval script not found at ${evalAbs} (declared as run_eval: ${system.frontmatter.run_eval} in kaizen/systems/${opts.systemId}/system.md)`,\n    );\n  }\n  const interp = detectInterpreter(evalAbs);\n\n  // 2. Generate run_id, create dir, write manifest, take lock.\n  const runId = generateRunId();\n  const dir = runDir(stateDir, opts.systemId, runId);\n  ensureDir(dir);\n  const startedAt = new Date().toISOString();\n  const manifest: ManifestFile = {\n    run_id: runId,\n    system: opts.systemId,\n    variant: opts.variant,\n    parent_id: opts.parent,\n    hypothesis: opts.hypothesis,\n    git_sha: gitSha(opts.workspace),\n    git_branch: gitBranch(opts.workspace),\n    worktree_root: gitTopLevel(opts.workspace),\n    git_common_dir: gitCommonDir(opts.workspace),\n    eval_version: system.frontmatter.eval_version,\n    dataset_version: system.frontmatter.dataset_version,\n    started_at: startedAt,\n    host: `${platform()}-${arch()} (${hostname()})`,\n    kaizen_version: opts.kaizenVersion,\n    state_dir: stateDir,\n    diagnostic: opts.diagnostic,\n    linear_issue_id: opts.linearIssue?.id ?? null,\n    linear_issue_url: opts.linearIssue?.url ?? null,\n  };\n  writeJsonAtomic(join(dir, \"manifest.json\"), manifest);\n  writeLock(dir);\n\n  const eventsPath = join(dir, \"events.jsonl\");\n  const stdoutPath = join(dir, \"stdout.log\");\n  const stderrPath = join(dir, \"stderr.log\");\n\n  // 3. Build initial state and write it.\n  const state: StateFile & {\n    system: string;\n    variant: string;\n    eval_version: number;\n    dataset_version: string;\n    started_at: string;\n    updated_at: string;\n    n_done: number;\n  } = {\n    run_id: runId,\n    system: opts.systemId,\n    variant: opts.variant,\n    status: \"running\",\n    score: null,\n    n_total: null,\n    n_done: 0,\n    promoted: null,\n    started_at: startedAt,\n    updated_at: startedAt,\n    ended_at: null,\n    eval_version: system.frontmatter.eval_version,\n    dataset_version: system.frontmatter.dataset_version,\n  };\n  writeJsonAtomic(join(dir, \"state.json\"), state);\n\n  // 4. Spawn the eval with fd 3 piped for events.\n  // For shebang scripts (cmd === evalAbs) we omit evalAbs from args, since\n  // spawn already passes cmd as argv[0]. Including it would duplicate the\n  // path as a positional and break argparse-based eval scripts.\n  const evalArgs = [\n    ...interp.preArgs,\n    ...(interp.cmd === evalAbs ? [] : [evalAbs]),\n    \"--variant\",\n    opts.variant,\n    \"--dataset\",\n    system.frontmatter.dataset_version,\n    \"--out-fd\",\n    \"3\",\n  ];\n  const effectiveMax = opts.diagnostic ? 5 : opts.maxItems;\n  if (effectiveMax !== null && effectiveMax !== undefined) {\n    evalArgs.push(\"--max-items\", String(effectiveMax));\n  }\n\n  const stdoutLog = createWriteStream(stdoutPath);\n  const stderrLog = createWriteStream(stderrPath);\n  let stderrTail = \"\";\n\n  const child: ChildProcess = spawn(interp.cmd, evalArgs, {\n    cwd: opts.workspace,\n    stdio: [\"ignore\", \"pipe\", \"pipe\", \"pipe\"],\n    env: process.env,\n  });\n\n  // Tee stdout/stderr to log files. Capture last ~4KB of stderr for crash diagnostics.\n  child.stdout!.on(\"data\", (chunk: Buffer) => stdoutLog.write(chunk));\n  child.stderr!.on(\"data\", (chunk: Buffer) => {\n    stderrLog.write(chunk);\n    stderrTail = (stderrTail + chunk.toString(\"utf-8\")).slice(-4096);\n  });\n\n  // Event stream on fd 3. spawn(['ignore','pipe','pipe','pipe']) makes child.stdio[3] a Readable.\n  const eventChan = child.stdio[3] as Readable;\n  const itemEvents: ItemEvent[] = [];\n  let sawComplete: CompleteEvent | null = null;\n  let parseErrors = 0;\n  let contractErrors = 0;\n\n  const reader = new NdjsonReader(\n    (e) => onEvent(e),\n    (line, err) => {\n      parseErrors++;\n      stderrLog.write(\n        `[runner] could not parse event: ${line.slice(0, 200)}\\n`,\n      );\n      stderrLog.write(\n        `[runner] ${err instanceof Error ? err.message : String(err)}\\n`,\n      );\n    },\n  );\n  eventChan.setEncoding?.(\"utf-8\");\n  eventChan.on(\"data\", (chunk) => reader.push(chunk as string | Buffer));\n  // The event channel may close after the child's `exit` fires (Node docs\n  // explicitly note stdio streams can outlive `exit`). We must drain it\n  // before deciding terminal state — otherwise a successful run that\n  // emitted a `complete` event still in the pipe buffer gets misclassified\n  // as \"crashed\" because `sawComplete` is observed null.\n  const eventChanEnded = new Promise<void>((resolve) => {\n    eventChan.on(\"end\", () => {\n      reader.end();\n      resolve();\n    });\n    eventChan.on(\"close\", () => {\n      reader.end();\n      resolve();\n    });\n  });\n\n  function onEvent(e: Event): void {\n    appendNdjsonLine(eventsPath, e);\n    if (e.type === \"start\") {\n      const s = e;\n      if (s.eval_version !== system.frontmatter.eval_version) {\n        contractErrors++;\n        stderrLog.write(\n          `[runner] start.eval_version ${s.eval_version} does not match system eval_version ${system.frontmatter.eval_version}\\n`,\n        );\n      }\n      if (s.dataset_version !== system.frontmatter.dataset_version) {\n        contractErrors++;\n        stderrLog.write(\n          `[runner] start.dataset_version ${s.dataset_version} does not match system dataset_version ${system.frontmatter.dataset_version}\\n`,\n        );\n      }\n      state.n_total = s.n;\n      state.updated_at = new Date().toISOString();\n      writeJsonAtomic(join(dir, \"state.json\"), state);\n    } else if (e.type === \"item\") {\n      const it = e;\n      itemEvents.push(it);\n      state.n_done = (state.n_done ?? 0) + 1;\n      state.updated_at = new Date().toISOString();\n      writeJsonAtomic(join(dir, \"state.json\"), state);\n    } else if (e.type === \"progress\") {\n      // n_done is authoritative from item events; progress is informational.\n      state.updated_at = new Date().toISOString();\n      writeJsonAtomic(join(dir, \"state.json\"), state);\n    } else if (e.type === \"complete\") {\n      sawComplete = e;\n      if (state.n_total !== null && sawComplete.n !== state.n_total) {\n        contractErrors++;\n        stderrLog.write(\n          `[runner] complete.n ${sawComplete.n} does not match start.n ${state.n_total}\\n`,\n        );\n      }\n      state.score = sawComplete.score;\n      state.updated_at = new Date().toISOString();\n      writeJsonAtomic(join(dir, \"state.json\"), state);\n    }\n    // error/promotion/etc. — no state mutation here\n  }\n\n  // 5. Wait for child to exit AND for the event channel to be fully drained.\n  // Both must complete before we decide terminal state — the child's exit\n  // doesn't guarantee its stdio buffers have been consumed by us yet.\n  const { code, signal } = await waitForExit(child);\n  await eventChanEnded;\n\n  // Flush logs.\n  stdoutLog.end();\n  stderrLog.end();\n  await Promise.all([\n    new Promise<void>((r) => stdoutLog.on(\"close\", () => r())),\n    new Promise<void>((r) => stderrLog.on(\"close\", () => r())),\n  ]);\n\n  // 6. Decide terminal state.\n  const endedAt = new Date().toISOString();\n  if (\n    code === 0 &&\n    sawComplete !== null &&\n    parseErrors === 0 &&\n    contractErrors === 0\n  ) {\n    state.status = \"complete\";\n    state.score = (sawComplete as CompleteEvent).score;\n    // The complete event is already in events.jsonl from onEvent.\n  } else {\n    const crashed: CrashedEvent = {\n      type: \"crashed\",\n      exit_code: code,\n      signal: signal ?? null,\n      stderr_tail: stderrTail.slice(-2000),\n      reason:\n        code !== 0 && code !== null\n          ? `eval exited with code ${code}`\n          : signal\n            ? `eval terminated by signal ${signal}`\n            : parseErrors > 0\n              ? `eval emitted ${parseErrors} malformed event(s)`\n              : contractErrors > 0\n                ? `eval emitted ${contractErrors} contract-violating event(s)`\n                : sawComplete !== null\n                  ? \"eval emitted complete but exited non-zero\"\n                  : \"eval exited without emitting complete event\",\n      ts: Date.now() / 1000,\n    };\n    appendNdjsonLine(eventsPath, crashed);\n    state.status = \"crashed\";\n  }\n  state.ended_at = endedAt;\n  state.updated_at = endedAt;\n\n  // 7. Write failures.jsonl (worst-K).\n  if (itemEvents.length > 0) {\n    const sorted = [...itemEvents].sort((a, b) => a.score - b.score);\n    const worst = sorted.slice(0, Math.min(FAILURE_K, sorted.length));\n    const text =\n      worst.map((it) => JSON.stringify(it)).join(\"\\n\") +\n      (worst.length > 0 ? \"\\n\" : \"\");\n    writeFileSync(join(dir, \"failures.jsonl\"), text);\n  }\n\n  // 8. Promotion (only if completed cleanly).\n  let promotionEvent: PromotionEvent | null = null;\n  if (state.status === \"complete\" && !opts.noAutoPromote) {\n    const allRuns = listRuns(stateDir, opts.systemId).filter(\n      (r) => r.run_id !== runId,\n    );\n    const baselineRun = currentBaseline(\n      allRuns,\n      system.frontmatter.eval_version,\n      system.frontmatter.dataset_version,\n    );\n    const baseline = baselineRun\n      ? {\n          run_id: baselineRun.run_id,\n          variant: baselineRun.variant,\n          score: baselineRun.score!,\n          events_path: baselineRun.events_path,\n        }\n      : null;\n    const decision = decidePromotion(\n      mapFromItems(itemEvents),\n      itemEvents,\n      baseline,\n      { subgroupKeys: subgroupKeys(system) },\n    );\n    promotionEvent = { type: \"promotion\", ts: Date.now() / 1000, ...decision };\n    appendNdjsonLine(eventsPath, promotionEvent);\n    state.promoted = decision.promoted;\n  } else if (opts.noAutoPromote) {\n    state.promoted = false;\n  }\n  writeJsonAtomic(join(dir, \"state.json\"), state);\n\n  // 9. Append hypothesis log line (every run, success or failure).\n  const hypoLine = {\n    run_id: runId,\n    system: opts.systemId,\n    variant: opts.variant,\n    parent_id: opts.parent,\n    hypothesis: opts.hypothesis,\n    status: state.status,\n    score: state.score,\n    promoted: state.promoted,\n    started_at: startedAt,\n    ended_at: endedAt,\n    eval_version: system.frontmatter.eval_version,\n    dataset_version: system.frontmatter.dataset_version,\n  };\n  appendNdjsonLine(hypothesesPath(stateDir, opts.systemId), hypoLine);\n\n  // 10. Clear lock.\n  clearLock(dir);\n\n  void parseErrors; // not surfaced yet; logged to stderr.log\n\n  return {\n    runId,\n    status: state.status as \"complete\" | \"crashed\" | \"aborted\",\n    score: state.score,\n    promoted: state.promoted ?? null,\n    exitCode: state.status === \"complete\" ? 0 : 1,\n  };\n}\n\n// --- helpers ---\n\ninterface InterpreterChoice {\n  cmd: string;\n  preArgs: string[];\n}\n\nfunction detectInterpreter(evalPath: string): InterpreterChoice {\n  const ext = extname(evalPath).toLowerCase();\n  if (ext === \".py\") return { cmd: \"python3\", preArgs: [] };\n  if (ext === \".js\" || ext === \".mjs\" || ext === \".cjs\")\n    return { cmd: \"node\", preArgs: [] };\n  if (ext === \".ts\" || ext === \".tsx\" || ext === \".mts\" || ext === \".cts\") {\n    return {\n      cmd: process.execPath,\n      preArgs: [\"--import\", require.resolve(\"tsx\")],\n    };\n  }\n  // Default: assume executable with shebang.\n  return { cmd: evalPath, preArgs: [] };\n}\n\nfunction waitForExit(\n  child: ChildProcess,\n): Promise<{ code: number | null; signal: NodeJS.Signals | null }> {\n  return new Promise((resolve) => {\n    child.on(\"exit\", (code: number | null, signal: NodeJS.Signals | null) =>\n      resolve({ code, signal }),\n    );\n  });\n}\n\nfunction gitSha(cwd: string): string | null {\n  try {\n    return (\n      execSync(\"git rev-parse HEAD\", {\n        cwd,\n        stdio: [\"ignore\", \"pipe\", \"ignore\"],\n      })\n        .toString()\n        .trim() || null\n    );\n  } catch {\n    return null;\n  }\n}\n\nfunction gitBranch(cwd: string): string | null {\n  try {\n    return (\n      execSync(\"git rev-parse --abbrev-ref HEAD\", {\n        cwd,\n        stdio: [\"ignore\", \"pipe\", \"ignore\"],\n      })\n        .toString()\n        .trim() || null\n    );\n  } catch {\n    return null;\n  }\n}\n\nfunction gitTopLevel(cwd: string): string | null {\n  try {\n    return (\n      execSync(\"git rev-parse --show-toplevel\", {\n        cwd,\n        stdio: [\"ignore\", \"pipe\", \"ignore\"],\n      })\n        .toString()\n        .trim() || null\n    );\n  } catch {\n    return null;\n  }\n}\n\nfunction gitCommonDir(cwd: string): string | null {\n  try {\n    return (\n      execSync(\"git rev-parse --git-common-dir\", {\n        cwd,\n        stdio: [\"ignore\", \"pipe\", \"ignore\"],\n      })\n        .toString()\n        .trim() || null\n    );\n  } catch {\n    return null;\n  }\n}\n\nfunction mapFromItems(items: ItemEvent[]): Map<string, number> {\n  const m = new Map<string, number>();\n  for (const it of items) m.set(it.id, it.score);\n  return m;\n}\n\nfunction subgroupKeys(system: SystemDef): string[] {\n  const sg = (\n    system.frontmatter as {\n      subgroups?: Array<{ field?: string; name?: string }>;\n    }\n  ).subgroups;\n  if (!Array.isArray(sg)) return [];\n  return sg.map((s) => s.field ?? s.name ?? \"\").filter(Boolean);\n}\n\n/**\n * Sweep stale runs whose lock points to a dead PID and which never recorded a terminal event.\n * Mark them `crashed` with reason \"supervisor died\" so the dashboard / log don't show ghosts.\n */\nexport function reapStaleRuns(stateDir: string, systemId: string): void {\n  const dir = systemRunsDir(stateDir, systemId);\n  if (!existsSync(dir)) return;\n  for (const run of listRuns(stateDir, systemId)) {\n    if (run.status !== \"running\") continue;\n    const lock = readLock(join(dir, run.run_id));\n    if (!lock) continue;\n    if (isPidAlive(lock.pid)) continue;\n    const reapedEvent: CrashedEvent = {\n      type: \"crashed\",\n      exit_code: null,\n      signal: null,\n      reason: `runner pid ${lock.pid} died without writing a terminal event; reaped`,\n      ts: Date.now() / 1000,\n    };\n    appendNdjsonLine(run.events_path, reapedEvent);\n\n    const state = readJsonIfExists<StateFile>(run.state_path);\n    if (state) {\n      state.status = \"crashed\";\n      state.ended_at = new Date().toISOString();\n      writeJsonAtomic(run.state_path, state);\n    }\n    clearLock(join(dir, run.run_id));\n  }\n}\n"],"mappings":"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"}

package/dist/lib/system.js

@@ -1,9 +1,11 @@
-import { join, resolve } from "node:path";
+import { kaizenSystemPath } from "../shared/workspace-paths.js";
+import "./paths.js";
 import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { parse } from "yaml";
 //#region src/lib/system.ts
 function systemPath(workspaceRoot, id) {
-	return join(workspaceRoot, "systems", `${id}.md`);
+	return kaizenSystemPath(workspaceRoot, id);
 }
 function loadSystem(workspaceRoot, id) {
 	const path = systemPath(workspaceRoot, id);

package/dist/lib/system.js.map

@@ -1 +1 @@
-{"version":3,"file":"system.js","names":["parseYaml"],"sources":["../../src/lib/system.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { parse as parseYaml } from \"yaml\";\n\nexport type EvalStyle = \"ground-truth\" | \"llm-as-judge\" | \"hybrid\";\nexport type ExecutionMode = \"in_process\" | \"server\";\n\nexport interface SubgroupDef {\n  name: string;\n  field: string;\n}\n\nexport interface SystemFrontmatter {\n  name: string;\n  description?: string;\n  run_eval: string;\n  eval_version: number;\n  dataset_version: string;\n  eval_style?: EvalStyle;\n  primary_metric: string;\n  target?: number;\n  execution_mode?: ExecutionMode;\n  kaizen_version?: string;\n  subgroups?: SubgroupDef[];\n  trace_renderer?: string;\n  [key: string]: unknown;\n}\n\nexport interface SystemDef {\n  id: string;\n  path: string;\n  frontmatter: SystemFrontmatter;\n  body: string;\n}\n\nexport function systemPath(workspaceRoot: string, id: string): string {\n  return join(workspaceRoot, \"systems\", `${id}.md`);\n}\n\nexport function loadSystem(workspaceRoot: string, id: string): SystemDef {\n  const path = systemPath(workspaceRoot, id);\n  if (!existsSync(path)) {\n    throw new Error(\n      `system \"${id}\" not found at ${path}. run \\`kaizen create system ${id}\\` to scaffold one.`,\n    );\n  }\n  const text = readFileSync(path, \"utf-8\");\n  const { frontmatter, body } = splitFrontmatter(text);\n  if (!frontmatter) {\n    throw new Error(`system ${id}: no YAML frontmatter found in ${path}`);\n  }\n  const fm = parseYaml(frontmatter) as Partial<SystemFrontmatter> | null;\n  if (!fm || typeof fm !== \"object\") {\n    throw new Error(`system ${id}: frontmatter is not a YAML mapping`);\n  }\n  const required = [\n    \"name\",\n    \"run_eval\",\n    \"eval_version\",\n    \"dataset_version\",\n    \"primary_metric\",\n  ] as const;\n  for (const k of required) {\n    if (fm[k] === undefined || fm[k] === null || fm[k] === \"\") {\n      throw new Error(\n        `system ${id}: frontmatter missing required field \"${k}\"`,\n      );\n    }\n  }\n  return {\n    id,\n    path,\n    frontmatter: fm as SystemFrontmatter,\n    body,\n  };\n}\n\nexport function resolveEvalPath(\n  workspaceRoot: string,\n  system: SystemDef,\n): string {\n  return resolve(workspaceRoot, system.frontmatter.run_eval);\n}\n\nfunction splitFrontmatter(text: string): {\n  frontmatter: string | null;\n  body: string;\n} {\n  // Frontmatter starts on line 1 with ---, ends with --- on its own line.\n  if (!text.startsWith(\"---\")) return { frontmatter: null, body: text };\n  const lines = text.split(\"\\n\");\n  // First line is \"---\". Find the next \"---\".\n  let close = -1;\n  for (let i = 1; i < lines.length; i++) {\n    if (lines[i].trim() === \"---\") {\n      close = i;\n      break;\n    }\n  }\n  if (close === -1) return { frontmatter: null, body: text };\n  return {\n    frontmatter: lines.slice(1, close).join(\"\\n\"),\n    body: lines.slice(close + 1).join(\"\\n\"),\n  };\n}\n"],"mappings":";;;;AAmCA,SAAgB,WAAW,eAAuB,IAAoB;AACpE,QAAO,KAAK,eAAe,WAAW,GAAG,GAAG,KAAK;;AAGnD,SAAgB,WAAW,eAAuB,IAAuB;CACvE,MAAM,OAAO,WAAW,eAAe,GAAG;AAC1C,KAAI,CAAC,WAAW,KAAK,CACnB,OAAM,IAAI,MACR,WAAW,GAAG,iBAAiB,KAAK,+BAA+B,GAAG,qBACvE;CAGH,MAAM,EAAE,aAAa,SAAS,iBADjB,aAAa,MAAM,QACmB,CAAC;AACpD,KAAI,CAAC,YACH,OAAM,IAAI,MAAM,UAAU,GAAG,iCAAiC,OAAO;CAEvE,MAAM,KAAKA,MAAU,YAAY;AACjC,KAAI,CAAC,MAAM,OAAO,OAAO,SACvB,OAAM,IAAI,MAAM,UAAU,GAAG,qCAAqC;AASpE,MAAK,MAAM,KAAK;EANd;EACA;EACA;EACA;EACA;EAEsB,CACtB,KAAI,GAAG,OAAO,KAAA,KAAa,GAAG,OAAO,QAAQ,GAAG,OAAO,GACrD,OAAM,IAAI,MACR,UAAU,GAAG,wCAAwC,EAAE,GACxD;AAGL,QAAO;EACL;EACA;EACA,aAAa;EACb;EACD;;AAGH,SAAgB,gBACd,eACA,QACQ;AACR,QAAO,QAAQ,eAAe,OAAO,YAAY,SAAS;;AAG5D,SAAS,iBAAiB,MAGxB;AAEA,KAAI,CAAC,KAAK,WAAW,MAAM,CAAE,QAAO;EAAE,aAAa;EAAM,MAAM;EAAM;CACrE,MAAM,QAAQ,KAAK,MAAM,KAAK;CAE9B,IAAI,QAAQ;AACZ,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,IAChC,KAAI,MAAM,GAAG,MAAM,KAAK,OAAO;AAC7B,UAAQ;AACR;;AAGJ,KAAI,UAAU,GAAI,QAAO;EAAE,aAAa;EAAM,MAAM;EAAM;AAC1D,QAAO;EACL,aAAa,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,KAAK;EAC7C,MAAM,MAAM,MAAM,QAAQ,EAAE,CAAC,KAAK,KAAK;EACxC"}
+{"version":3,"file":"system.js","names":["parseYaml"],"sources":["../../src/lib/system.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { parse as parseYaml } from \"yaml\";\nimport { kaizenSystemPath } from \"./paths.js\";\n\nexport type EvalStyle = \"ground-truth\" | \"llm-as-judge\" | \"hybrid\";\n\nexport interface SubgroupDef {\n  name: string;\n  field: string;\n}\n\nexport interface SystemFrontmatter {\n  name: string;\n  description?: string;\n  run_eval: string;\n  eval_version: number;\n  dataset_version: string;\n  eval_style?: EvalStyle;\n  primary_metric: string;\n  target?: number;\n  kaizen_version?: string;\n  subgroups?: SubgroupDef[];\n  [key: string]: unknown;\n}\n\nexport interface SystemDef {\n  id: string;\n  path: string;\n  frontmatter: SystemFrontmatter;\n  body: string;\n}\n\nfunction systemPath(workspaceRoot: string, id: string): string {\n  return kaizenSystemPath(workspaceRoot, id);\n}\n\nexport function loadSystem(workspaceRoot: string, id: string): SystemDef {\n  const path = systemPath(workspaceRoot, id);\n  if (!existsSync(path)) {\n    throw new Error(\n      `system \"${id}\" not found at ${path}. run \\`kaizen create system ${id}\\` to scaffold one.`,\n    );\n  }\n  const text = readFileSync(path, \"utf-8\");\n  const { frontmatter, body } = splitFrontmatter(text);\n  if (!frontmatter) {\n    throw new Error(`system ${id}: no YAML frontmatter found in ${path}`);\n  }\n  const fm = parseYaml(frontmatter) as Partial<SystemFrontmatter> | null;\n  if (!fm || typeof fm !== \"object\") {\n    throw new Error(`system ${id}: frontmatter is not a YAML mapping`);\n  }\n  const required = [\n    \"name\",\n    \"run_eval\",\n    \"eval_version\",\n    \"dataset_version\",\n    \"primary_metric\",\n  ] as const;\n  for (const k of required) {\n    if (fm[k] === undefined || fm[k] === null || fm[k] === \"\") {\n      throw new Error(\n        `system ${id}: frontmatter missing required field \"${k}\"`,\n      );\n    }\n  }\n  return {\n    id,\n    path,\n    frontmatter: fm as SystemFrontmatter,\n    body,\n  };\n}\n\nexport function resolveEvalPath(\n  workspaceRoot: string,\n  system: SystemDef,\n): string {\n  return resolve(workspaceRoot, system.frontmatter.run_eval);\n}\n\nfunction splitFrontmatter(text: string): {\n  frontmatter: string | null;\n  body: string;\n} {\n  // Frontmatter starts on line 1 with ---, ends with --- on its own line.\n  if (!text.startsWith(\"---\")) return { frontmatter: null, body: text };\n  const lines = text.split(\"\\n\");\n  // First line is \"---\". Find the next \"---\".\n  let close = -1;\n  for (let i = 1; i < lines.length; i++) {\n    if (lines[i].trim() === \"---\") {\n      close = i;\n      break;\n    }\n  }\n  if (close === -1) return { frontmatter: null, body: text };\n  return {\n    frontmatter: lines.slice(1, close).join(\"\\n\"),\n    body: lines.slice(close + 1).join(\"\\n\"),\n  };\n}\n"],"mappings":";;;;;;AAiCA,SAAS,WAAW,eAAuB,IAAoB;AAC7D,QAAO,iBAAiB,eAAe,GAAG;;AAG5C,SAAgB,WAAW,eAAuB,IAAuB;CACvE,MAAM,OAAO,WAAW,eAAe,GAAG;AAC1C,KAAI,CAAC,WAAW,KAAK,CACnB,OAAM,IAAI,MACR,WAAW,GAAG,iBAAiB,KAAK,+BAA+B,GAAG,qBACvE;CAGH,MAAM,EAAE,aAAa,SAAS,iBADjB,aAAa,MAAM,QACmB,CAAC;AACpD,KAAI,CAAC,YACH,OAAM,IAAI,MAAM,UAAU,GAAG,iCAAiC,OAAO;CAEvE,MAAM,KAAKA,MAAU,YAAY;AACjC,KAAI,CAAC,MAAM,OAAO,OAAO,SACvB,OAAM,IAAI,MAAM,UAAU,GAAG,qCAAqC;AASpE,MAAK,MAAM,KAAK;EANd;EACA;EACA;EACA;EACA;EAEsB,CACtB,KAAI,GAAG,OAAO,KAAA,KAAa,GAAG,OAAO,QAAQ,GAAG,OAAO,GACrD,OAAM,IAAI,MACR,UAAU,GAAG,wCAAwC,EAAE,GACxD;AAGL,QAAO;EACL;EACA;EACA,aAAa;EACb;EACD;;AAGH,SAAgB,gBACd,eACA,QACQ;AACR,QAAO,QAAQ,eAAe,OAAO,YAAY,SAAS;;AAG5D,SAAS,iBAAiB,MAGxB;AAEA,KAAI,CAAC,KAAK,WAAW,MAAM,CAAE,QAAO;EAAE,aAAa;EAAM,MAAM;EAAM;CACrE,MAAM,QAAQ,KAAK,MAAM,KAAK;CAE9B,IAAI,QAAQ;AACZ,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,IAChC,KAAI,MAAM,GAAG,MAAM,KAAK,OAAO;AAC7B,UAAQ;AACR;;AAGJ,KAAI,UAAU,GAAI,QAAO;EAAE,aAAa;EAAM,MAAM;EAAM;AAC1D,QAAO;EACL,aAAa,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,KAAK;EAC7C,MAAM,MAAM,MAAM,QAAQ,EAAE,CAAC,KAAK,KAAK;EACxC"}

package/dist/package.js

@@ -1,7 +1,7 @@
 //#region package.json
 var package_default = {
 	name: "@percepta/kaizen",
-	version: "0.6.0",
+	version: "0.8.0",
 	description: "Automated AI researcher that improves AI systems",
 	keywords: [
 		"ai",
@@ -13,6 +13,7 @@ var package_default = {
 	license: "MIT",
 	bin: { "kaizen": "./bin/kaizen.js" },
 	files: [
+		"agent",
 		"bin",
 		"dashboard/.next/standalone",
 		"dist",
@@ -43,8 +44,9 @@ var package_default = {
 		"typecheck:dashboard": "tsc -p dashboard --noEmit",
 		"test": "vitest run",
 		"dev": "tsx src/index.ts",
-		"dev:studio": "KAIZEN_WORKSPACE=examples/legacy-workspace next dev dashboard --webpack --port 6789",
-		"dev:next": "KAIZEN_WORKSPACE=examples/legacy-workspace next dev dashboard --webpack --port 6789",
+		"dev:studio": "KAIZEN_DEMO_MODE=1 KAIZEN_WORKSPACE=$PWD/examples/demo-workspace next dev dashboard --webpack --port 6789",
+		"dev:next": "KAIZEN_DEMO_MODE=1 KAIZEN_WORKSPACE=$PWD/examples/demo-workspace next dev dashboard --webpack --port 6789",
+		"seed:demo-data": "node scripts/seed-demo-traces.mjs --workspace $PWD/examples/demo-workspace",
 		"kaizen": "tsx src/index.ts"
 	},
 	dependencies: {
@@ -69,6 +71,7 @@ var package_default = {
 		"vitest": "^4.0.17",
 		"zod": "4.1.4"
 	},
+	peerDependencies: { "@types/react": "^19.0.0" },
 	engines: { "node": ">=20" }
 };
 //#endregion

package/dist/shared/view-types.d.ts

@@ -0,0 +1,67 @@
+//#region shared/view-types.d.ts
+/** Data shape passed to custom trace renderers. */
+interface TraceData {
+  id?: string;
+  name?: string;
+  tags?: string[];
+  timestamp?: string;
+  metadata?: unknown;
+  input?: unknown;
+  output?: unknown;
+  [key: string]: unknown;
+}
+/** Props contract for custom trace renderer components. */
+interface TraceRendererProps {
+  trace: TraceData;
+  context: TraceRendererContext;
+  actions: TraceRendererActions;
+}
+interface DatasetItemRendererProps {
+  datasetItem: DatasetItemData;
+  trace?: TraceData | null;
+  context: TraceRendererContext;
+  actions: DatasetItemRendererActions;
+}
+interface DatasetItemData {
+  id: string;
+  input?: unknown;
+  expectedOutput?: unknown;
+  metadata?: Record<string, unknown> | null;
+  [key: string]: unknown;
+}
+interface TraceRendererContext {
+  systemId: string;
+  surface: "trace" | "dataset-item" | "run-trace";
+  datasetName?: string | null;
+  runId?: string | null;
+}
+interface TraceRendererActions {
+  createScore(input: {
+    traceId?: string;
+    name: string;
+    value: number | string | boolean;
+    comment?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<unknown>;
+}
+interface DatasetItemRendererActions extends TraceRendererActions {
+  updateDatasetItem(input: {
+    datasetName?: string;
+    itemId?: string;
+    expectedOutput?: unknown;
+    metadata?: Record<string, unknown> | null;
+    input?: unknown;
+    sourceTraceId?: string | null;
+    status?: string | null;
+  }): Promise<unknown>;
+  createDatasetRunItem(input: {
+    datasetItemId?: string;
+    traceId?: string;
+    runName: string;
+    runDescription?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<unknown>;
+}
+//#endregion
+export { DatasetItemData, DatasetItemRendererActions, DatasetItemRendererProps, TraceData, TraceRendererActions, TraceRendererContext, TraceRendererProps };
+//# sourceMappingURL=view-types.d.ts.map

package/dist/shared/view-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-types.d.ts","names":["TraceData","id","name","tags","timestamp","metadata","input","output","key","TraceRendererProps","TraceRendererContext","TraceRendererActions","trace","context","actions","DatasetItemRendererProps","DatasetItemData","DatasetItemRendererActions","datasetItem","Record","expectedOutput","systemId","surface","datasetName","runId","Promise","createScore","traceId","value","comment","updateDatasetItem","itemId","sourceTraceId","status","createDatasetRunItem","datasetItemId","runName","runDescription"],"sources":["../../shared/view-types.d.ts"],"mappings":";;UACiBA,SAAAA;EACfC,EAAAA;EACAC,IAAAA;EACAC,IAAAA;EACAC,SAAAA;EACAC,QAAAA;EACAC,KAAAA;EACAC,MAAAA;EAAAA,CACCC,GAAAA;AAAAA;;UAIcC,kBAAAA;EACfG,KAAAA,EAAOZ,SAAAA;EACPa,OAAAA,EAASH,oBAAAA;EACTI,OAAAA,EAASH,oBAAAA;AAAAA;AAAAA,UAGMI,wBAAAA;EACfG,WAAAA,EAAaF,eAAAA;EACbJ,KAAAA,GAAQZ,SAAAA;EACRa,OAAAA,EAASH,oBAAAA;EACTI,OAAAA,EAASG,0BAAAA;AAAAA;AAAAA,UAGMD,eAAAA;EACff,EAAAA;EACAK,KAAAA;EACAc,cAAAA;EACAf,QAAAA,GAAWc,MAAAA;EAAAA,CACVX,GAAAA;AAAAA;AAAAA,UAGcE,oBAAAA;EACfW,QAAAA;EACAC,OAAAA;EACAC,WAAAA;EACAC,KAAAA;AAAAA;AAAAA,UAGeb,oBAAAA;EACfe,WAAAA,CAAYpB,KAAAA;IACVqB,OAAAA;IACAzB,IAAAA;IACA0B,KAAAA;IACAC,OAAAA;IACAxB,QAAAA,GAAWc,MAAAA;EAAAA,IACTM,OAAAA;AAAAA;AAAAA,UAGWR,0BAAAA,SAAmCN,oBAAAA;EAClDmB,iBAAAA,CAAkBxB,KAAAA;IAChBiB,WAAAA;IACAQ,MAAAA;IACAX,cAAAA;IACAf,QAAAA,GAAWc,MAAAA;IACXb,KAAAA;IACA0B,aAAAA;IACAC,MAAAA;EAAAA,IACER,OAAAA;EACJS,oBAAAA,CAAqB5B,KAAAA;IACnB6B,aAAAA;IACAR,OAAAA;IACAS,OAAAA;IACAC,cAAAA;IACAhC,QAAAA,GAAWc,MAAAA;EAAAA,IACTM,OAAAA;AAAAA"}

package/dist/shared/workspace-paths.js

@@ -0,0 +1,84 @@
+import { realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+//#region shared/workspace-paths.js
+const KAIZEN_DIR = "kaizen";
+const KAIZEN_CONFIG = "config.ts";
+const KAIZEN_STATE_DIR = ".kaizen";
+const KAIZEN_SYSTEMS_DIR = "systems";
+function kaizenDir(workspaceRoot) {
+	return join(workspaceRoot, KAIZEN_DIR);
+}
+function kaizenConfigPath(workspaceRoot) {
+	return join(kaizenDir(workspaceRoot), KAIZEN_CONFIG);
+}
+function kaizenSystemsDir(workspaceRoot) {
+	return join(kaizenDir(workspaceRoot), KAIZEN_SYSTEMS_DIR);
+}
+function kaizenSystemDir(workspaceRoot, systemId) {
+	return join(kaizenSystemsDir(workspaceRoot), systemId);
+}
+function kaizenSystemPath(workspaceRoot, systemId) {
+	return join(kaizenSystemDir(workspaceRoot, systemId), "system.md");
+}
+function defaultKaizenStateDir(workspaceRoot) {
+	return join(primaryWorktreeRoot(workspaceRoot), KAIZEN_DIR, KAIZEN_STATE_DIR);
+}
+function resolveKaizenStateDir(workspaceRoot) {
+	const raw = process.env.KAIZEN_STATE_DIR;
+	return raw ? resolve(workspaceRoot, raw) : defaultKaizenStateDir(workspaceRoot);
+}
+function primaryWorktreeRoot(workspaceRoot) {
+	const normalizedWorkspace = canonicalPath(workspaceRoot);
+	const gitRoot = gitTopLevel(normalizedWorkspace);
+	if (!gitRoot || canonicalPath(gitRoot) !== normalizedWorkspace) return normalizedWorkspace;
+	try {
+		const first = execFileSync("git", [
+			"-C",
+			normalizedWorkspace,
+			"worktree",
+			"list",
+			"--porcelain"
+		], {
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).split("\n").find((line) => line.startsWith("worktree "));
+		return first ? canonicalPath(first.slice(9)) : normalizedWorkspace;
+	} catch {
+		return normalizedWorkspace;
+	}
+}
+function gitTopLevel(workspaceRoot) {
+	try {
+		return execFileSync("git", [
+			"-C",
+			workspaceRoot,
+			"rev-parse",
+			"--show-toplevel"
+		], {
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return null;
+	}
+}
+function canonicalPath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return resolve(path);
+	}
+}
+//#endregion
+export { defaultKaizenStateDir, kaizenConfigPath, kaizenDir, kaizenSystemDir, kaizenSystemPath, kaizenSystemsDir, primaryWorktreeRoot, resolveKaizenStateDir };
+
+//# sourceMappingURL=workspace-paths.js.map

package/dist/shared/workspace-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-paths.js","names":[],"sources":["../../shared/workspace-paths.js"],"sourcesContent":["import { execFileSync } from \"node:child_process\";\nimport { realpathSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\n\nexport const KAIZEN_DIR = \"kaizen\";\nexport const KAIZEN_CONFIG = \"config.ts\";\nexport const KAIZEN_STATE_DIR = \".kaizen\";\nexport const KAIZEN_SYSTEMS_DIR = \"systems\";\n\nexport function kaizenDir(workspaceRoot) {\n  return join(workspaceRoot, KAIZEN_DIR);\n}\n\nexport function kaizenConfigPath(workspaceRoot) {\n  return join(kaizenDir(workspaceRoot), KAIZEN_CONFIG);\n}\n\nexport function kaizenSystemsDir(workspaceRoot) {\n  return join(kaizenDir(workspaceRoot), KAIZEN_SYSTEMS_DIR);\n}\n\nexport function kaizenSystemDir(workspaceRoot, systemId) {\n  return join(kaizenSystemsDir(workspaceRoot), systemId);\n}\n\nexport function kaizenSystemPath(workspaceRoot, systemId) {\n  return join(kaizenSystemDir(workspaceRoot, systemId), \"system.md\");\n}\n\nexport function defaultKaizenStateDir(workspaceRoot) {\n  return join(primaryWorktreeRoot(workspaceRoot), KAIZEN_DIR, KAIZEN_STATE_DIR);\n}\n\nexport function resolveKaizenStateDir(workspaceRoot) {\n  const raw = process.env.KAIZEN_STATE_DIR;\n  return raw\n    ? resolve(workspaceRoot, raw)\n    : defaultKaizenStateDir(workspaceRoot);\n}\n\nexport function primaryWorktreeRoot(workspaceRoot) {\n  const normalizedWorkspace = canonicalPath(workspaceRoot);\n  const gitRoot = gitTopLevel(normalizedWorkspace);\n  if (!gitRoot || canonicalPath(gitRoot) !== normalizedWorkspace) {\n    return normalizedWorkspace;\n  }\n\n  try {\n    const out = execFileSync(\n      \"git\",\n      [\"-C\", normalizedWorkspace, \"worktree\", \"list\", \"--porcelain\"],\n      { encoding: \"utf-8\", stdio: [\"ignore\", \"pipe\", \"ignore\"] },\n    );\n    const first = out.split(\"\\n\").find((line) => line.startsWith(\"worktree \"));\n    return first\n      ? canonicalPath(first.slice(\"worktree \".length))\n      : normalizedWorkspace;\n  } catch {\n    return normalizedWorkspace;\n  }\n}\n\nfunction gitTopLevel(workspaceRoot) {\n  try {\n    return execFileSync(\n      \"git\",\n      [\"-C\", workspaceRoot, \"rev-parse\", \"--show-toplevel\"],\n      {\n        encoding: \"utf-8\",\n        stdio: [\"ignore\", \"pipe\", \"ignore\"],\n      },\n    ).trim();\n  } catch {\n    return null;\n  }\n}\n\nfunction canonicalPath(path) {\n  try {\n    return realpathSync(path);\n  } catch {\n    return resolve(path);\n  }\n}\n"],"mappings":";;;;AAIA,MAAa,aAAa;AAC1B,MAAa,gBAAgB;AAC7B,MAAa,mBAAmB;AAChC,MAAa,qBAAqB;AAElC,SAAgB,UAAU,eAAe;AACvC,QAAO,KAAK,eAAe,WAAW;;AAGxC,SAAgB,iBAAiB,eAAe;AAC9C,QAAO,KAAK,UAAU,cAAc,EAAE,cAAc;;AAGtD,SAAgB,iBAAiB,eAAe;AAC9C,QAAO,KAAK,UAAU,cAAc,EAAE,mBAAmB;;AAG3D,SAAgB,gBAAgB,eAAe,UAAU;AACvD,QAAO,KAAK,iBAAiB,cAAc,EAAE,SAAS;;AAGxD,SAAgB,iBAAiB,eAAe,UAAU;AACxD,QAAO,KAAK,gBAAgB,eAAe,SAAS,EAAE,YAAY;;AAGpE,SAAgB,sBAAsB,eAAe;AACnD,QAAO,KAAK,oBAAoB,cAAc,EAAE,YAAY,iBAAiB;;AAG/E,SAAgB,sBAAsB,eAAe;CACnD,MAAM,MAAM,QAAQ,IAAI;AACxB,QAAO,MACH,QAAQ,eAAe,IAAI,GAC3B,sBAAsB,cAAc;;AAG1C,SAAgB,oBAAoB,eAAe;CACjD,MAAM,sBAAsB,cAAc,cAAc;CACxD,MAAM,UAAU,YAAY,oBAAoB;AAChD,KAAI,CAAC,WAAW,cAAc,QAAQ,KAAK,oBACzC,QAAO;AAGT,KAAI;EAMF,MAAM,QALM,aACV,OACA;GAAC;GAAM;GAAqB;GAAY;GAAQ;GAAc,EAC9D;GAAE,UAAU;GAAS,OAAO;IAAC;IAAU;IAAQ;IAAS;GAAE,CAE3C,CAAC,MAAM,KAAK,CAAC,MAAM,SAAS,KAAK,WAAW,YAAY,CAAC;AAC1E,SAAO,QACH,cAAc,MAAM,MAAM,EAAmB,CAAC,GAC9C;SACE;AACN,SAAO;;;AAIX,SAAS,YAAY,eAAe;AAClC,KAAI;AACF,SAAO,aACL,OACA;GAAC;GAAM;GAAe;GAAa;GAAkB,EACrD;GACE,UAAU;GACV,OAAO;IAAC;IAAU;IAAQ;IAAS;GACpC,CACF,CAAC,MAAM;SACF;AACN,SAAO;;;AAIX,SAAS,cAAc,MAAM;AAC3B,KAAI;AACF,SAAO,aAAa,KAAK;SACnB;AACN,SAAO,QAAQ,KAAK"}

package/dist/types.d.ts

@@ -1,38 +1,11 @@
+import { DatasetItemData, DatasetItemRendererActions, DatasetItemRendererProps, TraceData, TraceRendererActions, TraceRendererContext, TraceRendererProps } from "./shared/view-types.js";
+
 //#region src/types.d.ts
 interface KaizenConfig {
   customer: {
-    slug: string;
     name: string;
   };
-  langfuse?: {
-    host?: string;
-    publicKeyEnv?: string;
-    secretKeyEnv?: string;
-  };
-  studio?: {
-    port?: number;
-  };
-}
-/** Data shape passed to custom trace renderers. */
-interface TraceData {
-  id?: string;
-  name?: string;
-  tags?: string[];
-  timestamp?: string;
-  metadata?: unknown;
-  input?: unknown;
-  output?: unknown;
-}
-/** Props contract for custom trace renderer components. */
-interface TraceRendererProps {
-  trace: TraceData;
-  datasetItem?: {
-    id: string;
-    input?: unknown;
-    expectedOutput?: unknown;
-    metadata?: Record<string, unknown> | null;
-  } | null;
 }
 //#endregion
-export { KaizenConfig, TraceData, TraceRendererProps };
+export { type DatasetItemData, type DatasetItemRendererActions, type DatasetItemRendererProps, KaizenConfig, type TraceData, type TraceRendererActions, type TraceRendererContext, type TraceRendererProps };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";UAAiB,YAAA;EACf,QAAA;IACE,IAAA;IACA,IAAA;EAAA;EAEF,QAAA;IACE,IAAA;IACA,YAAA;IACA,YAAA;EAAA;EAEF,MAAA;IACE,IAAA;EAAA;AAAA;;UAKa,SAAA;EACf,EAAA;EACA,IAAA;EACA,IAAA;EACA,SAAA;EACA,QAAA;EACA,KAAA;EACA,MAAA;AAAA;;UAIe,kBAAA;EACf,KAAA,EAAO,SAAA;EACP,WAAA;IACE,EAAA;IACA,KAAA;IACA,cAAA;IACA,QAAA,GAAW,MAAA;EAAA;AAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;UAAiB,YAAA;EACf,QAAA;IACE,IAAA;EAAA;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percepta/kaizen",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Automated AI researcher that improves AI systems",
   "keywords": [
     "ai",
@@ -14,6 +14,7 @@
     "kaizen": "./bin/kaizen.js"
   },
   "files": [
+    "agent",
     "bin",
     "dashboard/.next/standalone",
     "dist",
@@ -58,6 +59,9 @@
     "zod": "4.1.4",
     "@percepta/build": "1.1.0"
   },
+  "peerDependencies": {
+    "@types/react": "^19.0.0"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -71,8 +75,9 @@
     "typecheck:dashboard": "tsc -p dashboard --noEmit",
     "test": "vitest run",
     "dev": "tsx src/index.ts",
-    "dev:studio": "KAIZEN_WORKSPACE=examples/legacy-workspace next dev dashboard --webpack --port 6789",
-    "dev:next": "KAIZEN_WORKSPACE=examples/legacy-workspace next dev dashboard --webpack --port 6789",
+    "dev:studio": "KAIZEN_DEMO_MODE=1 KAIZEN_WORKSPACE=$PWD/examples/demo-workspace next dev dashboard --webpack --port 6789",
+    "dev:next": "KAIZEN_DEMO_MODE=1 KAIZEN_WORKSPACE=$PWD/examples/demo-workspace next dev dashboard --webpack --port 6789",
+    "seed:demo-data": "node scripts/seed-demo-traces.mjs --workspace $PWD/examples/demo-workspace",
     "kaizen": "tsx src/index.ts"
   }
 }

package/shared/view-types.d.ts

@@ -0,0 +1,69 @@
+/** Data shape passed to custom trace renderers. */
+export interface TraceData {
+  id?: string;
+  name?: string;
+  tags?: string[];
+  timestamp?: string;
+  metadata?: unknown;
+  input?: unknown;
+  output?: unknown;
+  [key: string]: unknown;
+}
+
+/** Props contract for custom trace renderer components. */
+export interface TraceRendererProps {
+  trace: TraceData;
+  context: TraceRendererContext;
+  actions: TraceRendererActions;
+}
+
+export interface DatasetItemRendererProps {
+  datasetItem: DatasetItemData;
+  trace?: TraceData | null;
+  context: TraceRendererContext;
+  actions: DatasetItemRendererActions;
+}
+
+export interface DatasetItemData {
+  id: string;
+  input?: unknown;
+  expectedOutput?: unknown;
+  metadata?: Record<string, unknown> | null;
+  [key: string]: unknown;
+}
+
+export interface TraceRendererContext {
+  systemId: string;
+  surface: "trace" | "dataset-item" | "run-trace";
+  datasetName?: string | null;
+  runId?: string | null;
+}
+
+export interface TraceRendererActions {
+  createScore(input: {
+    traceId?: string;
+    name: string;
+    value: number | string | boolean;
+    comment?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<unknown>;
+}
+
+export interface DatasetItemRendererActions extends TraceRendererActions {
+  updateDatasetItem(input: {
+    datasetName?: string;
+    itemId?: string;
+    expectedOutput?: unknown;
+    metadata?: Record<string, unknown> | null;
+    input?: unknown;
+    sourceTraceId?: string | null;
+    status?: string | null;
+  }): Promise<unknown>;
+  createDatasetRunItem(input: {
+    datasetItemId?: string;
+    traceId?: string;
+    runName: string;
+    runDescription?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<unknown>;
+}

package/shared/view-types.js

@@ -0,0 +1 @@
+export {};

package/shared/workspace-paths.d.ts

@@ -0,0 +1,19 @@
+export declare const KAIZEN_DIR = "kaizen";
+export declare const KAIZEN_CONFIG = "config.ts";
+export declare const KAIZEN_STATE_DIR = ".kaizen";
+export declare const KAIZEN_SYSTEMS_DIR = "systems";
+
+export declare function kaizenDir(workspaceRoot: string): string;
+export declare function kaizenConfigPath(workspaceRoot: string): string;
+export declare function kaizenSystemsDir(workspaceRoot: string): string;
+export declare function kaizenSystemDir(
+  workspaceRoot: string,
+  systemId: string,
+): string;
+export declare function kaizenSystemPath(
+  workspaceRoot: string,
+  systemId: string,
+): string;
+export declare function defaultKaizenStateDir(workspaceRoot: string): string;
+export declare function resolveKaizenStateDir(workspaceRoot: string): string;
+export declare function primaryWorktreeRoot(workspaceRoot: string): string;

package/shared/workspace-paths.js

@@ -0,0 +1,84 @@
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export const KAIZEN_DIR = "kaizen";
+export const KAIZEN_CONFIG = "config.ts";
+export const KAIZEN_STATE_DIR = ".kaizen";
+export const KAIZEN_SYSTEMS_DIR = "systems";
+
+export function kaizenDir(workspaceRoot) {
+  return join(workspaceRoot, KAIZEN_DIR);
+}
+
+export function kaizenConfigPath(workspaceRoot) {
+  return join(kaizenDir(workspaceRoot), KAIZEN_CONFIG);
+}
+
+export function kaizenSystemsDir(workspaceRoot) {
+  return join(kaizenDir(workspaceRoot), KAIZEN_SYSTEMS_DIR);
+}
+
+export function kaizenSystemDir(workspaceRoot, systemId) {
+  return join(kaizenSystemsDir(workspaceRoot), systemId);
+}
+
+export function kaizenSystemPath(workspaceRoot, systemId) {
+  return join(kaizenSystemDir(workspaceRoot, systemId), "system.md");
+}
+
+export function defaultKaizenStateDir(workspaceRoot) {
+  return join(primaryWorktreeRoot(workspaceRoot), KAIZEN_DIR, KAIZEN_STATE_DIR);
+}
+
+export function resolveKaizenStateDir(workspaceRoot) {
+  const raw = process.env.KAIZEN_STATE_DIR;
+  return raw
+    ? resolve(workspaceRoot, raw)
+    : defaultKaizenStateDir(workspaceRoot);
+}
+
+export function primaryWorktreeRoot(workspaceRoot) {
+  const normalizedWorkspace = canonicalPath(workspaceRoot);
+  const gitRoot = gitTopLevel(normalizedWorkspace);
+  if (!gitRoot || canonicalPath(gitRoot) !== normalizedWorkspace) {
+    return normalizedWorkspace;
+  }
+
+  try {
+    const out = execFileSync(
+      "git",
+      ["-C", normalizedWorkspace, "worktree", "list", "--porcelain"],
+      { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] },
+    );
+    const first = out.split("\n").find((line) => line.startsWith("worktree "));
+    return first
+      ? canonicalPath(first.slice("worktree ".length))
+      : normalizedWorkspace;
+  } catch {
+    return normalizedWorkspace;
+  }
+}
+
+function gitTopLevel(workspaceRoot) {
+  try {
+    return execFileSync(
+      "git",
+      ["-C", workspaceRoot, "rev-parse", "--show-toplevel"],
+      {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+      },
+    ).trim();
+  } catch {
+    return null;
+  }
+}
+
+function canonicalPath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}