baa-conductor

commit

4e53054

parent

56fe5ff

author

im_wower

date

2026-03-22 21:16:04 +0800 CST

feat(codexd): add daemon scaffold

 1@@ -0,0 +1,17 @@
 2+{
 3+  "name": "@baa-conductor/codexd",
 4+  "private": true,
 5+  "type": "module",
 6+  "main": "dist/index.js",
 7+  "exports": {
 8+    ".": "./dist/index.js"
 9+  },
10+  "scripts": {
11+    "build": "pnpm exec tsc -p tsconfig.json && BAA_DIST_DIR=apps/codexd/dist BAA_DIST_ENTRY=apps/codexd/src/index.js BAA_FIX_RELATIVE_EXTENSIONS=true pnpm -C ../.. run build:runtime-postprocess",
12+    "typecheck": "pnpm exec tsc --noEmit -p tsconfig.json",
13+    "start": "pnpm run build && node dist/index.js start",
14+    "status": "pnpm run build && node dist/index.js status --json",
15+    "test": "pnpm run build && node --test src/index.test.js",
16+    "smoke": "pnpm run build && node dist/index.js smoke"
17+  }
18+}

  1@@ -0,0 +1,210 @@
  2+import {
  3+  formatCodexdConfigText,
  4+  getCodexdUsageText,
  5+  parseCodexdCliRequest
  6+} from "./config.js";
  7+import {
  8+  CodexdDaemon,
  9+  runCodexdSmoke,
 10+  type CodexdDaemonOptions
 11+} from "./daemon.js";
 12+import type {
 13+  CodexdEnvironment,
 14+  CodexdSmokeResult,
 15+  CodexdStatusSnapshot
 16+} from "./contracts.js";
 17+import { CodexdStateStore } from "./state-store.js";
 18+
 19+export interface CodexdTextWriter {
 20+  write(chunk: string): unknown;
 21+}
 22+
 23+export interface CodexdProcessLike {
 24+  argv: string[];
 25+  cwd?(): string;
 26+  env: CodexdEnvironment;
 27+  execPath?: string;
 28+  exitCode?: number;
 29+  off?(event: string, listener: () => void): unknown;
 30+  on?(event: string, listener: () => void): unknown;
 31+  pid?: number;
 32+}
 33+
 34+export interface RunCodexdCliOptions extends CodexdDaemonOptions {
 35+  argv?: readonly string[];
 36+  env?: CodexdEnvironment;
 37+  processLike?: CodexdProcessLike;
 38+  stderr?: CodexdTextWriter;
 39+  stdout?: CodexdTextWriter;
 40+}
 41+
 42+type CodexdOutputWriter = CodexdTextWriter | typeof console;
 43+
 44+export async function runCodexdCli(options: RunCodexdCliOptions = {}): Promise<number> {
 45+  const processLike = options.processLike ?? getProcessLike();
 46+  const stdout = options.stdout ?? console;
 47+  const stderr = options.stderr ?? console;
 48+  const argv = options.argv ?? processLike?.argv ?? [];
 49+  const env = options.env ?? processLike?.env ?? {};
 50+  const request = parseCodexdCliRequest(argv, env);
 51+
 52+  if (request.action === "help") {
 53+    writeLine(stdout, getCodexdUsageText());
 54+    return 0;
 55+  }
 56+
 57+  if (request.action === "config") {
 58+    if (request.printJson) {
 59+      writeLine(stdout, JSON.stringify(request.config, null, 2));
 60+    } else {
 61+      writeLine(stdout, formatCodexdConfigText(request.config));
 62+    }
 63+
 64+    return 0;
 65+  }
 66+
 67+  if (request.action === "status") {
 68+    const store = new CodexdStateStore(request.config, {
 69+      processId: () => processLike?.pid ?? null
 70+    });
 71+    const snapshot = await store.initialize();
 72+
 73+    if (request.printJson) {
 74+      writeLine(stdout, JSON.stringify(snapshot, null, 2));
 75+    } else {
 76+      writeLine(stdout, formatCodexdStatusText(snapshot));
 77+    }
 78+
 79+    return 0;
 80+  }
 81+
 82+  if (request.action === "smoke") {
 83+    const result = await runCodexdSmoke(request.config, options);
 84+
 85+    if (request.printJson) {
 86+      writeLine(stdout, JSON.stringify(result, null, 2));
 87+    } else {
 88+      writeLine(stdout, formatCodexdSmokeText(result));
 89+    }
 90+
 91+    return result.checks.every((check) => check.status === "ok") ? 0 : 1;
 92+  }
 93+
 94+  if (request.action !== "start") {
 95+    throw new Error(`Unsupported codexd request action "${request.action}".`);
 96+  }
 97+
 98+  const daemon = new CodexdDaemon(request.config, {
 99+    ...options,
100+    env
101+  });
102+  const snapshot = await daemon.start();
103+
104+  if (!request.runOnce) {
105+    if (request.printJson) {
106+      writeLine(stdout, JSON.stringify(snapshot, null, 2));
107+    } else {
108+      writeLine(stdout, formatCodexdStatusText(snapshot));
109+    }
110+
111+    const signal = await waitForShutdownSignal(processLike);
112+    const stopped = await daemon.stop();
113+
114+    if (!request.printJson) {
115+      writeLine(stdout, `codexd stopped${signal ? ` after ${signal}` : ""}`);
116+      writeLine(stdout, formatCodexdStatusText(stopped));
117+    }
118+
119+    return 0;
120+  }
121+
122+  await sleep(request.lifetimeMs);
123+  const stopped = await daemon.stop();
124+
125+  if (request.printJson) {
126+    writeLine(stdout, JSON.stringify(stopped, null, 2));
127+  } else {
128+    writeLine(stdout, formatCodexdStatusText(stopped));
129+  }
130+
131+  return 0;
132+}
133+
134+function formatCodexdSmokeText(result: CodexdSmokeResult): string {
135+  return [
136+    `smoke daemon=${result.snapshot.identity.daemonId}`,
137+    ...result.checks.map((check) => `- ${check.status} ${check.name}: ${check.detail}`),
138+    formatCodexdStatusText(result.snapshot)
139+  ].join("\n");
140+}
141+
142+function formatCodexdStatusText(snapshot: CodexdStatusSnapshot): string {
143+  return [
144+    `identity=${snapshot.identity.daemonId}`,
145+    `node=${snapshot.identity.nodeId}`,
146+    `daemon=${snapshot.daemon.started ? "running" : "stopped"}`,
147+    `child=${snapshot.daemon.child.status}`,
148+    `strategy=${snapshot.config.server.childStrategy}`,
149+    `mode=${snapshot.config.server.mode}`,
150+    `endpoint=${snapshot.config.server.endpoint}`,
151+    `sessions=${snapshot.sessionRegistry.sessions.length}`,
152+    `recent_events=${snapshot.recentEvents.events.length}`,
153+    `logs_dir=${snapshot.config.paths.logsDir}`,
154+    `state_dir=${snapshot.config.paths.stateDir}`
155+  ].join(" ");
156+}
157+
158+function getProcessLike(): CodexdProcessLike | undefined {
159+  return (globalThis as { process?: CodexdProcessLike }).process;
160+}
161+
162+function sleep(ms: number): Promise<void> {
163+  return new Promise((resolve) => {
164+    setTimeout(resolve, ms);
165+  });
166+}
167+
168+async function waitForShutdownSignal(processLike: CodexdProcessLike | undefined): Promise<string | null> {
169+  const subscribe = processLike?.on;
170+
171+  if (!subscribe || !processLike) {
172+    return null;
173+  }
174+
175+  return new Promise((resolve) => {
176+    const signals = ["SIGINT", "SIGTERM"] as const;
177+    const listeners: Partial<Record<(typeof signals)[number], () => void>> = {};
178+    const cleanup = () => {
179+      if (!processLike.off) {
180+        return;
181+      }
182+
183+      for (const signal of signals) {
184+        const listener = listeners[signal];
185+
186+        if (listener) {
187+          processLike.off(signal, listener);
188+        }
189+      }
190+    };
191+
192+    for (const signal of signals) {
193+      const listener = () => {
194+        cleanup();
195+        resolve(signal);
196+      };
197+
198+      listeners[signal] = listener;
199+      subscribe.call(processLike, signal, listener);
200+    }
201+  });
202+}
203+
204+function writeLine(writer: CodexdOutputWriter, line: string): void {
205+  if ("write" in writer) {
206+    writer.write(`${line}\n`);
207+    return;
208+  }
209+
210+  writer.log(line);
211+}

  1@@ -0,0 +1,465 @@
  2+import { resolve } from "node:path";
  3+
  4+import type {
  5+  CodexdCliAction,
  6+  CodexdEnvironment,
  7+  CodexdResolvedConfig,
  8+  CodexdRuntimePaths,
  9+  CodexdServerConfig
 10+} from "./contracts.js";
 11+
 12+export interface CodexdConfigInput {
 13+  eventCacheSize?: number;
 14+  logsDir?: string;
 15+  mode?: string;
 16+  nodeId?: string;
 17+  repoRoot?: string;
 18+  serverArgs?: string[];
 19+  serverCommand?: string;
 20+  serverCwd?: string;
 21+  serverEndpoint?: string;
 22+  serverStrategy?: string;
 23+  smokeLifetimeMs?: number;
 24+  stateDir?: string;
 25+  version?: string | null;
 26+}
 27+
 28+export type CodexdCliRequest =
 29+  | {
 30+      action: "help";
 31+    }
 32+  | {
 33+      action: Exclude<CodexdCliAction, "help" | "start">;
 34+      config: CodexdResolvedConfig;
 35+      printJson: boolean;
 36+    }
 37+  | {
 38+      action: "start";
 39+      config: CodexdResolvedConfig;
 40+      printJson: boolean;
 41+      runOnce: boolean;
 42+      lifetimeMs: number;
 43+    };
 44+
 45+const DEFAULT_EVENT_CACHE_SIZE = 50;
 46+const DEFAULT_NODE_ID = "mini-main";
 47+const DEFAULT_SERVER_ARGS = ["app-server"];
 48+const DEFAULT_SERVER_COMMAND = "codex";
 49+const DEFAULT_SERVER_ENDPOINT = "stdio://codex-app-server";
 50+const DEFAULT_SERVER_MODE = "app-server";
 51+const DEFAULT_SERVER_STRATEGY = "spawn";
 52+const DEFAULT_SMOKE_LIFETIME_MS = 100;
 53+
 54+export function resolveCodexdConfig(input: CodexdConfigInput = {}): CodexdResolvedConfig {
 55+  const repoRoot = resolve(input.repoRoot ?? getDefaultRepoRoot());
 56+  const logsRootDir = resolve(getOptionalString(input.logsDir) ?? resolve(repoRoot, "logs"));
 57+  const stateRootDir = resolve(getOptionalString(input.stateDir) ?? resolve(repoRoot, "state"));
 58+  const paths = resolveCodexdRuntimePaths(repoRoot, logsRootDir, stateRootDir);
 59+  const server = resolveServerConfig(input, repoRoot);
 60+
 61+  return {
 62+    nodeId: getOptionalString(input.nodeId) ?? DEFAULT_NODE_ID,
 63+    version: getOptionalString(input.version),
 64+    eventCacheSize: normalizePositiveInteger(input.eventCacheSize, DEFAULT_EVENT_CACHE_SIZE, "event cache"),
 65+    smokeLifetimeMs: normalizePositiveInteger(
 66+      input.smokeLifetimeMs,
 67+      DEFAULT_SMOKE_LIFETIME_MS,
 68+      "smoke lifetime"
 69+    ),
 70+    paths,
 71+    server
 72+  };
 73+}
 74+
 75+export function parseCodexdCliRequest(
 76+  argv: readonly string[],
 77+  env: CodexdEnvironment = {}
 78+): CodexdCliRequest {
 79+  const tokens = argv.slice(2);
 80+  let action: CodexdCliAction = "start";
 81+  let actionSet = false;
 82+  let printJson = false;
 83+  let runOnce = false;
 84+  let eventCacheSize = parseOptionalInteger(env.BAA_CODEXD_EVENT_CACHE_SIZE);
 85+  let logsDir = env.BAA_CODEXD_LOGS_DIR ?? env.BAA_LOGS_DIR;
 86+  let mode = env.BAA_CODEXD_MODE;
 87+  let nodeId = env.BAA_NODE_ID;
 88+  let repoRoot = env.BAA_CODEXD_REPO_ROOT;
 89+  let serverArgs: string[] | undefined = parseArgumentList(env.BAA_CODEXD_SERVER_ARGS);
 90+  let serverArgsSet = serverArgs !== undefined;
 91+  let serverCommand = env.BAA_CODEXD_SERVER_COMMAND;
 92+  let serverCwd = env.BAA_CODEXD_SERVER_CWD;
 93+  let serverEndpoint = env.BAA_CODEXD_SERVER_ENDPOINT;
 94+  let serverStrategy = env.BAA_CODEXD_SERVER_STRATEGY;
 95+  let smokeLifetimeMs = parseOptionalInteger(env.BAA_CODEXD_SMOKE_LIFETIME_MS);
 96+  let stateDir = env.BAA_CODEXD_STATE_DIR ?? env.BAA_STATE_DIR;
 97+  let version = env.BAA_CODEXD_VERSION ?? null;
 98+
 99+  for (let index = 0; index < tokens.length; index += 1) {
100+    const token = tokens[index];
101+
102+    if (token == null) {
103+      continue;
104+    }
105+
106+    if (token === "--help" || token === "-h" || token === "help") {
107+      return { action: "help" };
108+    }
109+
110+    if (token === "--json") {
111+      printJson = true;
112+      continue;
113+    }
114+
115+    if (token === "--run-once") {
116+      runOnce = true;
117+      continue;
118+    }
119+
120+    if (token === "--repo-root") {
121+      repoRoot = readCliValue(tokens, index, "--repo-root");
122+      index += 1;
123+      continue;
124+    }
125+
126+    if (token === "--node-id") {
127+      nodeId = readCliValue(tokens, index, "--node-id");
128+      index += 1;
129+      continue;
130+    }
131+
132+    if (token === "--mode") {
133+      mode = readCliValue(tokens, index, "--mode");
134+      index += 1;
135+      continue;
136+    }
137+
138+    if (token === "--logs-dir") {
139+      logsDir = readCliValue(tokens, index, "--logs-dir");
140+      index += 1;
141+      continue;
142+    }
143+
144+    if (token === "--state-dir") {
145+      stateDir = readCliValue(tokens, index, "--state-dir");
146+      index += 1;
147+      continue;
148+    }
149+
150+    if (token === "--server-endpoint") {
151+      serverEndpoint = readCliValue(tokens, index, "--server-endpoint");
152+      index += 1;
153+      continue;
154+    }
155+
156+    if (token === "--server-strategy") {
157+      serverStrategy = readCliValue(tokens, index, "--server-strategy");
158+      index += 1;
159+      continue;
160+    }
161+
162+    if (token === "--server-command") {
163+      serverCommand = readCliValue(tokens, index, "--server-command");
164+      index += 1;
165+      continue;
166+    }
167+
168+    if (token === "--server-arg") {
169+      const serverArg = readCliValue(tokens, index, "--server-arg");
170+
171+      if (!serverArgsSet || serverArgs == null) {
172+        serverArgs = [];
173+        serverArgsSet = true;
174+      }
175+
176+      serverArgs.push(serverArg);
177+      index += 1;
178+      continue;
179+    }
180+
181+    if (token === "--server-cwd") {
182+      serverCwd = readCliValue(tokens, index, "--server-cwd");
183+      index += 1;
184+      continue;
185+    }
186+
187+    if (token === "--event-cache-size") {
188+      eventCacheSize = parseStrictInteger(readCliValue(tokens, index, "--event-cache-size"), "--event-cache-size");
189+      index += 1;
190+      continue;
191+    }
192+
193+    if (token === "--smoke-lifetime-ms") {
194+      smokeLifetimeMs = parseStrictInteger(
195+        readCliValue(tokens, index, "--smoke-lifetime-ms"),
196+        "--smoke-lifetime-ms"
197+      );
198+      index += 1;
199+      continue;
200+    }
201+
202+    if (token === "--version") {
203+      version = readCliValue(tokens, index, "--version");
204+      index += 1;
205+      continue;
206+    }
207+
208+    if (token.startsWith("--")) {
209+      throw new Error(`Unknown codexd flag "${token}".`);
210+    }
211+
212+    if (actionSet) {
213+      throw new Error(`Unexpected extra codexd argument "${token}".`);
214+    }
215+
216+    if (!isCodexdCliAction(token)) {
217+      throw new Error(`Unknown codexd action "${token}".`);
218+    }
219+
220+    action = token;
221+    actionSet = true;
222+  }
223+
224+  const config = resolveCodexdConfig({
225+    eventCacheSize,
226+    logsDir,
227+    mode,
228+    nodeId,
229+    repoRoot,
230+    serverArgs,
231+    serverCommand,
232+    serverCwd,
233+    serverEndpoint,
234+    serverStrategy,
235+    smokeLifetimeMs,
236+    stateDir,
237+    version
238+  });
239+
240+  if (action === "start") {
241+    return {
242+      action,
243+      config,
244+      printJson,
245+      runOnce,
246+      lifetimeMs: config.smokeLifetimeMs
247+    };
248+  }
249+
250+  return {
251+    action,
252+    config,
253+    printJson
254+  };
255+}
256+
257+export function formatCodexdConfigText(config: CodexdResolvedConfig): string {
258+  return [
259+    `node_id: ${config.nodeId}`,
260+    `version: ${config.version ?? "not-set"}`,
261+    `mode: ${config.server.mode}`,
262+    `endpoint: ${config.server.endpoint}`,
263+    `child_strategy: ${config.server.childStrategy}`,
264+    `child_command: ${config.server.childCommand}`,
265+    `child_args: ${config.server.childArgs.join(" ") || "(none)"}`,
266+    `child_cwd: ${config.server.childCwd}`,
267+    `logs_dir: ${config.paths.logsDir}`,
268+    `state_dir: ${config.paths.stateDir}`,
269+    `event_cache_size: ${config.eventCacheSize}`,
270+    `smoke_lifetime_ms: ${config.smokeLifetimeMs}`
271+  ].join("\n");
272+}
273+
274+export function getCodexdUsageText(): string {
275+  return [
276+    "Usage:",
277+    "  node apps/codexd/dist/index.js [start] [options]",
278+    "  node apps/codexd/dist/index.js status [--json]",
279+    "  node apps/codexd/dist/index.js config [--json]",
280+    "  node apps/codexd/dist/index.js smoke [--json]",
281+    "  node apps/codexd/dist/index.js help",
282+    "",
283+    "Options:",
284+    "  --repo-root <path>",
285+    "  --node-id <id>",
286+    "  --mode <app-server|exec>",
287+    "  --logs-dir <path>",
288+    "  --state-dir <path>",
289+    "  --server-endpoint <url-or-stdio>",
290+    "  --server-strategy <spawn|external>",
291+    "  --server-command <command>",
292+    "  --server-arg <arg>",
293+    "  --server-cwd <path>",
294+    "  --event-cache-size <integer>",
295+    "  --smoke-lifetime-ms <integer>",
296+    "  --version <string>",
297+    "  --run-once",
298+    "  --json",
299+    "  --help",
300+    "",
301+    "Environment:",
302+    "  BAA_NODE_ID",
303+    "  BAA_LOGS_DIR",
304+    "  BAA_STATE_DIR",
305+    "  BAA_CODEXD_REPO_ROOT",
306+    "  BAA_CODEXD_MODE",
307+    "  BAA_CODEXD_LOGS_DIR",
308+    "  BAA_CODEXD_STATE_DIR",
309+    "  BAA_CODEXD_SERVER_ENDPOINT",
310+    "  BAA_CODEXD_SERVER_STRATEGY",
311+    "  BAA_CODEXD_SERVER_COMMAND",
312+    "  BAA_CODEXD_SERVER_ARGS",
313+    "  BAA_CODEXD_SERVER_CWD",
314+    "  BAA_CODEXD_EVENT_CACHE_SIZE",
315+    "  BAA_CODEXD_SMOKE_LIFETIME_MS",
316+    "  BAA_CODEXD_VERSION",
317+    "",
318+    "Notes:",
319+    "  start manages one configured Codex child process or an external endpoint placeholder.",
320+    "  smoke always uses an embedded stub child so the scaffold can be verified without Codex CLI."
321+  ].join("\n");
322+}
323+
324+function getDefaultRepoRoot(): string {
325+  if (typeof process !== "undefined" && typeof process.cwd === "function") {
326+    return process.cwd();
327+  }
328+
329+  return ".";
330+}
331+
332+function resolveServerConfig(input: CodexdConfigInput, repoRoot: string): CodexdServerConfig {
333+  const mode = normalizeServerMode(input.mode);
334+  const childStrategy = normalizeChildStrategy(input.serverStrategy);
335+  const childArgs = input.serverArgs == null ? [...DEFAULT_SERVER_ARGS] : [...input.serverArgs];
336+
337+  return {
338+    mode,
339+    endpoint: getOptionalString(input.serverEndpoint) ?? DEFAULT_SERVER_ENDPOINT,
340+    childStrategy,
341+    childCommand: getOptionalString(input.serverCommand) ?? DEFAULT_SERVER_COMMAND,
342+    childArgs,
343+    childCwd: resolve(getOptionalString(input.serverCwd) ?? repoRoot)
344+  };
345+}
346+
347+function resolveCodexdRuntimePaths(
348+  repoRoot: string,
349+  logsRootDir: string,
350+  stateRootDir: string
351+): CodexdRuntimePaths {
352+  const logsDir = resolve(logsRootDir, "codexd");
353+  const stateDir = resolve(stateRootDir, "codexd");
354+
355+  return {
356+    repoRoot,
357+    logsRootDir,
358+    stateRootDir,
359+    logsDir,
360+    stateDir,
361+    structuredEventLogPath: resolve(logsDir, "events.jsonl"),
362+    stdoutLogPath: resolve(logsDir, "stdout.log"),
363+    stderrLogPath: resolve(logsDir, "stderr.log"),
364+    identityPath: resolve(stateDir, "identity.json"),
365+    daemonStatePath: resolve(stateDir, "daemon-state.json"),
366+    sessionRegistryPath: resolve(stateDir, "session-registry.json"),
367+    recentEventsPath: resolve(stateDir, "recent-events.json")
368+  };
369+}
370+
371+function isCodexdCliAction(value: string): value is Exclude<CodexdCliAction, "help"> {
372+  return value === "config" || value === "smoke" || value === "start" || value === "status";
373+}
374+
375+function normalizeChildStrategy(value: string | undefined): CodexdServerConfig["childStrategy"] {
376+  switch (value ?? DEFAULT_SERVER_STRATEGY) {
377+    case "external":
378+      return "external";
379+    case "spawn":
380+      return "spawn";
381+    default:
382+      throw new Error(`Unsupported codexd child strategy "${value}".`);
383+  }
384+}
385+
386+function normalizeServerMode(value: string | undefined): CodexdServerConfig["mode"] {
387+  switch (value ?? DEFAULT_SERVER_MODE) {
388+    case "app-server":
389+      return "app-server";
390+    case "exec":
391+      return "exec";
392+    default:
393+      throw new Error(`Unsupported codexd mode "${value}".`);
394+  }
395+}
396+
397+function parseArgumentList(value: string | undefined): string[] | undefined {
398+  if (value == null) {
399+    return undefined;
400+  }
401+
402+  const trimmed = value.trim();
403+
404+  if (trimmed === "") {
405+    return [];
406+  }
407+
408+  if (trimmed.startsWith("[")) {
409+    const parsed = JSON.parse(trimmed) as unknown;
410+
411+    if (!Array.isArray(parsed) || parsed.some((entry) => typeof entry !== "string")) {
412+      throw new Error("BAA_CODEXD_SERVER_ARGS must be a JSON string array when JSON syntax is used.");
413+    }
414+
415+    return [...parsed];
416+  }
417+
418+  return trimmed.split(/\s+/u);
419+}
420+
421+function parseOptionalInteger(value: string | undefined): number | undefined {
422+  if (value == null || value.trim() === "") {
423+    return undefined;
424+  }
425+
426+  return parseStrictInteger(value, "integer value");
427+}
428+
429+function parseStrictInteger(value: string, label: string): number {
430+  const parsed = Number(value);
431+
432+  if (!Number.isInteger(parsed)) {
433+    throw new Error(`Invalid ${label} "${value}".`);
434+  }
435+
436+  return parsed;
437+}
438+
439+function normalizePositiveInteger(value: number | undefined, fallback: number, label: string): number {
440+  const candidate = value ?? fallback;
441+
442+  if (!Number.isInteger(candidate) || candidate < 0) {
443+    throw new Error(`Invalid ${label} value "${String(value)}".`);
444+  }
445+
446+  return candidate;
447+}
448+
449+function getOptionalString(value: string | null | undefined): string | null {
450+  if (value == null) {
451+    return null;
452+  }
453+
454+  const trimmed = value.trim();
455+  return trimmed === "" ? null : trimmed;
456+}
457+
458+function readCliValue(tokens: readonly string[], index: number, flag: string): string {
459+  const value = tokens[index + 1];
460+
461+  if (value == null || value.startsWith("--")) {
462+    throw new Error(`Missing value for ${flag}.`);
463+  }
464+
465+  return value;
466+}

  1@@ -0,0 +1,126 @@
  2+export type CodexdCliAction = "config" | "help" | "smoke" | "start" | "status";
  3+export type CodexdChildStrategy = "external" | "spawn";
  4+export type CodexdManagedChildStatus = "external" | "failed" | "idle" | "running" | "starting" | "stopped";
  5+export type CodexdEventLevel = "error" | "info" | "warn";
  6+export type CodexdServerMode = "app-server" | "exec";
  7+export type CodexdSessionPurpose = "duplex" | "smoke" | "worker";
  8+export type CodexdSessionStatus = "active" | "closed";
  9+
 10+export type CodexdEnvironment = Record<string, string | undefined>;
 11+
 12+export interface CodexdRuntimePaths {
 13+  repoRoot: string;
 14+  logsRootDir: string;
 15+  stateRootDir: string;
 16+  logsDir: string;
 17+  stateDir: string;
 18+  structuredEventLogPath: string;
 19+  stdoutLogPath: string;
 20+  stderrLogPath: string;
 21+  identityPath: string;
 22+  daemonStatePath: string;
 23+  sessionRegistryPath: string;
 24+  recentEventsPath: string;
 25+}
 26+
 27+export interface CodexdServerConfig {
 28+  mode: CodexdServerMode;
 29+  endpoint: string;
 30+  childStrategy: CodexdChildStrategy;
 31+  childCommand: string;
 32+  childArgs: string[];
 33+  childCwd: string;
 34+}
 35+
 36+export interface CodexdResolvedConfig {
 37+  nodeId: string;
 38+  version: string | null;
 39+  eventCacheSize: number;
 40+  smokeLifetimeMs: number;
 41+  paths: CodexdRuntimePaths;
 42+  server: CodexdServerConfig;
 43+}
 44+
 45+export interface CodexdDaemonIdentity {
 46+  daemonId: string;
 47+  nodeId: string;
 48+  repoRoot: string;
 49+  createdAt: string;
 50+  version: string | null;
 51+}
 52+
 53+export interface CodexdManagedChildState {
 54+  strategy: CodexdChildStrategy;
 55+  mode: CodexdServerMode;
 56+  endpoint: string;
 57+  status: CodexdManagedChildStatus;
 58+  command: string | null;
 59+  args: string[];
 60+  cwd: string | null;
 61+  pid: number | null;
 62+  startedAt: string | null;
 63+  exitedAt: string | null;
 64+  exitCode: number | null;
 65+  signal: string | null;
 66+  lastError: string | null;
 67+}
 68+
 69+export interface CodexdDaemonState {
 70+  started: boolean;
 71+  startedAt: string | null;
 72+  stoppedAt: string | null;
 73+  updatedAt: string;
 74+  pid: number | null;
 75+  child: CodexdManagedChildState;
 76+}
 77+
 78+export interface CodexdSessionRecord {
 79+  sessionId: string;
 80+  purpose: CodexdSessionPurpose;
 81+  threadId: string | null;
 82+  status: CodexdSessionStatus;
 83+  endpoint: string;
 84+  childPid: number | null;
 85+  createdAt: string;
 86+  updatedAt: string;
 87+  metadata: Record<string, string>;
 88+}
 89+
 90+export interface CodexdSessionRegistryState {
 91+  updatedAt: string | null;
 92+  sessions: CodexdSessionRecord[];
 93+}
 94+
 95+export interface CodexdRecentEvent {
 96+  seq: number;
 97+  createdAt: string;
 98+  level: CodexdEventLevel;
 99+  type: string;
100+  message: string;
101+  detail: Record<string, unknown> | null;
102+}
103+
104+export interface CodexdRecentEventCacheState {
105+  maxEntries: number;
106+  updatedAt: string | null;
107+  events: CodexdRecentEvent[];
108+}
109+
110+export interface CodexdStatusSnapshot {
111+  config: CodexdResolvedConfig;
112+  identity: CodexdDaemonIdentity;
113+  daemon: CodexdDaemonState;
114+  sessionRegistry: CodexdSessionRegistryState;
115+  recentEvents: CodexdRecentEventCacheState;
116+}
117+
118+export interface CodexdSmokeCheck {
119+  name: string;
120+  status: "failed" | "ok";
121+  detail: string;
122+}
123+
124+export interface CodexdSmokeResult {
125+  checks: CodexdSmokeCheck[];
126+  snapshot: CodexdStatusSnapshot;
127+}

  1@@ -0,0 +1,513 @@
  2+import { spawn } from "node:child_process";
  3+import { access } from "node:fs/promises";
  4+
  5+import type {
  6+  CodexdEnvironment,
  7+  CodexdManagedChildState,
  8+  CodexdRecentEvent,
  9+  CodexdResolvedConfig,
 10+  CodexdSessionPurpose,
 11+  CodexdSessionRecord,
 12+  CodexdSmokeCheck,
 13+  CodexdSmokeResult,
 14+  CodexdStatusSnapshot
 15+} from "./contracts.js";
 16+import { CodexdStateStore, type CodexdStateStoreOptions } from "./state-store.js";
 17+
 18+export interface CodexdProcessOutput {
 19+  on(event: "data", listener: (chunk: string | Uint8Array) => void): unknown;
 20+}
 21+
 22+export interface CodexdChildProcessLike {
 23+  pid?: number;
 24+  stderr?: CodexdProcessOutput;
 25+  stdout?: CodexdProcessOutput;
 26+  kill(signal?: string): boolean;
 27+  on(event: "error", listener: (error: Error) => void): this;
 28+  on(event: "exit", listener: (code: number | null, signal: string | null) => void): this;
 29+  on(event: "spawn", listener: () => void): this;
 30+  once(event: "error", listener: (error: Error) => void): this;
 31+  once(event: "exit", listener: (code: number | null, signal: string | null) => void): this;
 32+  once(event: "spawn", listener: () => void): this;
 33+}
 34+
 35+export interface CodexdSpawnOptions {
 36+  cwd: string;
 37+  env: CodexdEnvironment;
 38+}
 39+
 40+export interface CodexdSpawner {
 41+  spawn(command: string, args: readonly string[], options: CodexdSpawnOptions): CodexdChildProcessLike;
 42+}
 43+
 44+export interface CodexdDaemonOptions extends CodexdStateStoreOptions {
 45+  env?: CodexdEnvironment;
 46+  spawner?: CodexdSpawner;
 47+}
 48+
 49+export interface CodexdSessionInput {
 50+  metadata?: Record<string, string>;
 51+  purpose: CodexdSessionPurpose;
 52+  threadId?: string | null;
 53+}
 54+
 55+const MAX_CHILD_OUTPUT_PREVIEW = 160;
 56+const STOP_TIMEOUT_MS = 1_000;
 57+
 58+export class CodexdDaemon {
 59+  private child: CodexdChildProcessLike | null = null;
 60+  private readonly env: CodexdEnvironment;
 61+  private readonly stateStore: CodexdStateStore;
 62+  private readonly spawner: CodexdSpawner;
 63+  private started = false;
 64+
 65+  constructor(
 66+    private readonly config: CodexdResolvedConfig,
 67+    options: CodexdDaemonOptions = {}
 68+  ) {
 69+    this.env = options.env ?? (typeof process !== "undefined" ? process.env : {});
 70+    this.spawner = options.spawner ?? {
 71+      spawn(command, args, spawnOptions) {
 72+        return spawn(command, [...args], {
 73+          cwd: spawnOptions.cwd,
 74+          env: spawnOptions.env,
 75+          stdio: ["ignore", "pipe", "pipe"]
 76+        });
 77+      }
 78+    };
 79+    this.stateStore = new CodexdStateStore(config, options);
 80+  }
 81+
 82+  async start(): Promise<CodexdStatusSnapshot> {
 83+    await this.stateStore.initialize();
 84+
 85+    if (this.started) {
 86+      return this.stateStore.getSnapshot();
 87+    }
 88+
 89+    await this.stateStore.markDaemonStarted();
 90+    await this.stateStore.recordEvent({
 91+      level: "info",
 92+      type: "daemon.started",
 93+      message: `codexd started in ${this.config.server.mode} mode.`,
 94+      detail: {
 95+        endpoint: this.config.server.endpoint,
 96+        strategy: this.config.server.childStrategy
 97+      }
 98+    });
 99+
100+    if (this.config.server.childStrategy === "external") {
101+      await this.stateStore.updateChildState({
102+        status: "external",
103+        pid: null,
104+        startedAt: new Date().toISOString(),
105+        exitedAt: null,
106+        exitCode: null,
107+        signal: null,
108+        lastError: null
109+      });
110+      await this.stateStore.recordEvent({
111+        level: "info",
112+        type: "child.external",
113+        message: `codexd is pointing at external endpoint ${this.config.server.endpoint}.`
114+      });
115+      this.started = true;
116+      return this.stateStore.getSnapshot();
117+    }
118+
119+    await this.stateStore.updateChildState({
120+      status: "starting",
121+      pid: null,
122+      startedAt: null,
123+      exitedAt: null,
124+      exitCode: null,
125+      signal: null,
126+      lastError: null
127+    });
128+
129+    const child = this.spawner.spawn(this.config.server.childCommand, this.config.server.childArgs, {
130+      cwd: this.config.server.childCwd,
131+      env: {
132+        ...this.env,
133+        BAA_CODEXD_DAEMON_ID: this.stateStore.getSnapshot().identity.daemonId,
134+        BAA_CODEXD_SERVER_ENDPOINT: this.config.server.endpoint
135+      }
136+    });
137+    this.child = child;
138+    this.attachChildListeners(child);
139+
140+    try {
141+      await waitForChildSpawn(child);
142+    } catch (error) {
143+      await this.stateStore.updateChildState({
144+        status: "failed",
145+        pid: null,
146+        exitedAt: new Date().toISOString(),
147+        lastError: formatErrorMessage(error)
148+      });
149+      await this.stateStore.recordEvent({
150+        level: "error",
151+        type: "child.spawn.failed",
152+        message: formatErrorMessage(error)
153+      });
154+      this.child = null;
155+      throw error;
156+    }
157+
158+    await this.stateStore.updateChildState({
159+      status: "running",
160+      pid: child.pid ?? null,
161+      startedAt: new Date().toISOString(),
162+      exitedAt: null,
163+      exitCode: null,
164+      signal: null,
165+      lastError: null
166+    });
167+    await this.stateStore.recordEvent({
168+      level: "info",
169+      type: "child.started",
170+      message: `Started Codex child process ${child.pid ?? "unknown"}.`,
171+      detail: {
172+        command: this.config.server.childCommand,
173+        args: this.config.server.childArgs
174+      }
175+    });
176+
177+    this.started = true;
178+    return this.stateStore.getSnapshot();
179+  }
180+
181+  async stop(): Promise<CodexdStatusSnapshot> {
182+    await this.stateStore.initialize();
183+
184+    if (this.child != null) {
185+      const child = this.child;
186+      this.child = null;
187+
188+      const exited = waitForChildExit(child, STOP_TIMEOUT_MS);
189+      try {
190+        child.kill("SIGTERM");
191+      } catch (error) {
192+        await this.stateStore.recordEvent({
193+          level: "warn",
194+          type: "child.kill.failed",
195+          message: formatErrorMessage(error)
196+        });
197+      }
198+
199+      await exited;
200+    } else {
201+      const currentChildState = this.stateStore.getChildState();
202+
203+      if (currentChildState.status === "external") {
204+        await this.stateStore.updateChildState({
205+          status: "idle",
206+          pid: null,
207+          exitCode: null,
208+          signal: null,
209+          exitedAt: new Date().toISOString()
210+        });
211+      }
212+    }
213+
214+    await this.stateStore.markDaemonStopped();
215+    await this.stateStore.recordEvent({
216+      level: "info",
217+      type: "daemon.stopped",
218+      message: "codexd stopped."
219+    });
220+
221+    this.started = false;
222+    return this.stateStore.getSnapshot();
223+  }
224+
225+  getStatusSnapshot(): CodexdStatusSnapshot {
226+    return this.stateStore.getSnapshot();
227+  }
228+
229+  async registerSession(input: CodexdSessionInput): Promise<CodexdSessionRecord> {
230+    await this.stateStore.initialize();
231+    const now = new Date().toISOString();
232+    const session: CodexdSessionRecord = {
233+      sessionId: createSessionId(),
234+      purpose: input.purpose,
235+      threadId: input.threadId ?? null,
236+      status: "active",
237+      endpoint: this.config.server.endpoint,
238+      childPid: this.stateStore.getChildState().pid,
239+      createdAt: now,
240+      updatedAt: now,
241+      metadata: {
242+        ...(input.metadata ?? {})
243+      }
244+    };
245+
246+    await this.stateStore.upsertSession(session);
247+    await this.stateStore.recordEvent({
248+      level: "info",
249+      type: "session.registered",
250+      message: `Registered ${input.purpose} session ${session.sessionId}.`,
251+      detail: {
252+        sessionId: session.sessionId,
253+        threadId: session.threadId
254+      }
255+    });
256+
257+    return session;
258+  }
259+
260+  async closeSession(sessionId: string): Promise<CodexdSessionRecord | null> {
261+    await this.stateStore.initialize();
262+    const session = await this.stateStore.closeSession(sessionId);
263+
264+    if (session != null) {
265+      await this.stateStore.recordEvent({
266+        level: "info",
267+        type: "session.closed",
268+        message: `Closed session ${sessionId}.`,
269+        detail: {
270+          sessionId
271+        }
272+      });
273+    }
274+
275+    return session;
276+  }
277+
278+  private attachChildListeners(child: CodexdChildProcessLike): void {
279+    child.stdout?.on("data", (chunk) => {
280+      void this.handleChildOutput("stdout", chunk);
281+    });
282+    child.stderr?.on("data", (chunk) => {
283+      void this.handleChildOutput("stderr", chunk);
284+    });
285+    child.on("error", (error) => {
286+      void this.handleChildError(error);
287+    });
288+    child.on("exit", (code, signal) => {
289+      void this.handleChildExit(code, signal);
290+    });
291+  }
292+
293+  private async handleChildError(error: Error): Promise<void> {
294+    await this.stateStore.updateChildState({
295+      status: "failed",
296+      lastError: error.message
297+    });
298+    await this.stateStore.recordEvent({
299+      level: "error",
300+      type: "child.error",
301+      message: error.message
302+    });
303+  }
304+
305+  private async handleChildExit(code: number | null, signal: string | null): Promise<void> {
306+    const stoppedAt = new Date().toISOString();
307+    const status = code == null || code === 0 ? "stopped" : "failed";
308+
309+    await this.stateStore.updateChildState({
310+      status,
311+      pid: null,
312+      exitedAt: stoppedAt,
313+      exitCode: code,
314+      signal,
315+      lastError: status === "failed" ? `Child exited with code ${String(code)}.` : null
316+    });
317+    await this.stateStore.recordEvent({
318+      level: status === "failed" ? "error" : "info",
319+      type: "child.exited",
320+      message:
321+        status === "failed"
322+          ? `Codex child exited with code ${String(code)}.`
323+          : `Codex child exited${signal ? ` after ${signal}` : ""}.`,
324+      detail: {
325+        code,
326+        signal
327+      }
328+    });
329+  }
330+
331+  private async handleChildOutput(stream: "stderr" | "stdout", chunk: string | Uint8Array): Promise<void> {
332+    const text = normalizeOutputChunk(chunk);
333+
334+    if (text === "") {
335+      return;
336+    }
337+
338+    await this.stateStore.appendChildOutput(stream, text);
339+    await this.stateStore.recordEvent({
340+      level: stream === "stderr" ? "warn" : "info",
341+      type: `child.${stream}`,
342+      message: `${stream}: ${createOutputPreview(text)}`,
343+      detail: {
344+        bytes: text.length,
345+        stream
346+      }
347+    });
348+  }
349+}
350+
351+export async function runCodexdSmoke(
352+  baseConfig: CodexdResolvedConfig,
353+  options: CodexdDaemonOptions = {}
354+): Promise<CodexdSmokeResult> {
355+  const smokeConfig: CodexdResolvedConfig = {
356+    ...baseConfig,
357+    server: {
358+      ...baseConfig.server,
359+      childStrategy: "spawn",
360+      childCommand: typeof process !== "undefined" ? process.execPath : "node",
361+      childArgs: ["-e", EMBEDDED_SMOKE_PROGRAM],
362+      endpoint: "stdio://embedded-smoke-child"
363+    }
364+  };
365+  const daemon = new CodexdDaemon(smokeConfig, options);
366+
367+  await daemon.start();
368+  const session = await daemon.registerSession({
369+    purpose: "smoke",
370+    metadata: {
371+      source: "embedded-smoke"
372+    }
373+  });
374+
375+  await sleep(Math.max(smokeConfig.smokeLifetimeMs, 75));
376+  await daemon.closeSession(session.sessionId);
377+  const snapshot = await daemon.stop();
378+  const checks: CodexdSmokeCheck[] = [
379+    await buildFileCheck("structured_event_log", smokeConfig.paths.structuredEventLogPath),
380+    await buildFileCheck("stdout_log", smokeConfig.paths.stdoutLogPath),
381+    await buildFileCheck("stderr_log", smokeConfig.paths.stderrLogPath),
382+    await buildFileCheck("daemon_state", smokeConfig.paths.daemonStatePath),
383+    {
384+      name: "recent_event_cache",
385+      status: snapshot.recentEvents.events.length > 0 ? "ok" : "failed",
386+      detail: `${snapshot.recentEvents.events.length} cached events`
387+    },
388+    {
389+      name: "session_registry",
390+      status: hasClosedSmokeSession(snapshot.recentEvents.events, snapshot.daemon.child, snapshot)
391+        ? "ok"
392+        : "failed",
393+      detail: `${snapshot.sessionRegistry.sessions.length} recorded sessions`
394+    }
395+  ];
396+
397+  return {
398+    checks,
399+    snapshot
400+  };
401+}
402+
403+async function buildFileCheck(name: string, path: string): Promise<CodexdSmokeCheck> {
404+  try {
405+    await access(path);
406+    return {
407+      name,
408+      status: "ok",
409+      detail: path
410+    };
411+  } catch {
412+    return {
413+      name,
414+      status: "failed",
415+      detail: `missing: ${path}`
416+    };
417+  }
418+}
419+
420+function hasClosedSmokeSession(
421+  events: readonly CodexdRecentEvent[],
422+  childState: CodexdManagedChildState,
423+  snapshot: CodexdStatusSnapshot
424+): boolean {
425+  return (
426+    snapshot.sessionRegistry.sessions.some(
427+      (session) => session.purpose === "smoke" && session.status === "closed"
428+    ) &&
429+    (events.length > 0 || childState.exitedAt != null)
430+  );
431+}
432+
433+function createOutputPreview(text: string): string {
434+  const flattened = text.replace(/\s+/gu, " ").trim();
435+  return flattened.length <= MAX_CHILD_OUTPUT_PREVIEW
436+    ? flattened
437+    : `${flattened.slice(0, MAX_CHILD_OUTPUT_PREVIEW - 3)}...`;
438+}
439+
440+function createSessionId(): string {
441+  return `session-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
442+}
443+
444+function formatErrorMessage(error: unknown): string {
445+  if (error instanceof Error) {
446+    return error.message;
447+  }
448+
449+  return String(error);
450+}
451+
452+function normalizeOutputChunk(chunk: string | Uint8Array): string {
453+  return typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
454+}
455+
456+function sleep(ms: number): Promise<void> {
457+  return new Promise((resolve) => {
458+    setTimeout(resolve, ms);
459+  });
460+}
461+
462+function waitForChildExit(child: CodexdChildProcessLike, timeoutMs: number): Promise<void> {
463+  return new Promise((resolve) => {
464+    let settled = false;
465+    const complete = () => {
466+      if (settled) {
467+        return;
468+      }
469+
470+      settled = true;
471+      resolve();
472+    };
473+
474+    child.once("exit", () => {
475+      complete();
476+    });
477+    setTimeout(() => {
478+      complete();
479+    }, timeoutMs);
480+  });
481+}
482+
483+function waitForChildSpawn(child: CodexdChildProcessLike): Promise<void> {
484+  return new Promise((resolve, reject) => {
485+    let settled = false;
486+    const finish = (callback: () => void) => {
487+      if (settled) {
488+        return;
489+      }
490+
491+      settled = true;
492+      callback();
493+    };
494+
495+    child.once("spawn", () => {
496+      finish(resolve);
497+    });
498+    child.once("error", (error) => {
499+      finish(() => reject(error));
500+    });
501+    child.once("exit", (code, signal) => {
502+      finish(() => reject(new Error(`Child exited before spawn completion (code=${String(code)}, signal=${String(signal)}).`)));
503+    });
504+  });
505+}
506+
507+const EMBEDDED_SMOKE_PROGRAM = [
508+  'process.stdout.write("codexd smoke ready\\n");',
509+  'process.stderr.write("codexd smoke stderr\\n");',
510+  'setTimeout(() => {',
511+  '  process.stdout.write("codexd smoke done\\n");',
512+  '  process.exit(0);',
513+  "}, 25);"
514+].join(" ");