@promptctl/cc-candybar 1.0.0

package/src/config/loader/variables.ts

@@ -0,0 +1,260 @@
+// [LAW:types-are-the-program] The variable schema: a VariableDecl is discriminated
+// by `kind` (literal / input / env / file / shell / template / time / git / state),
+// declared as DATA (VARIABLE_SCHEMA) and interpreted by the tag-by-field-value
+// engine (taggedUnion). Each arm is a `fields` schema over its member's non-`kind`
+// fields, except `input`, whose `default` must match its `type` — a genuine
+// cross-field invariant carried as a closure. This file changes when a source
+// kind's shape changes; adding a kind is one new arm here plus its runtime impl.
+
+import {
+  GIT_FIELDS,
+  type GitField,
+  type EnvVarDecl,
+  type FileVarDecl,
+  type InputVarDecl,
+  type GitVarDecl,
+  type LiteralVarDecl,
+  type ShellVarDecl,
+  type StateVarDecl,
+  type TemplateVarDecl,
+  type TimeVarDecl,
+  type VariableDecl,
+} from "../dsl-types.js";
+import { findKeyLine } from "./diagnostics.js";
+import {
+  describeType,
+  fields,
+  isPlainObject,
+  objectJson,
+  optionalStringSpec,
+  optionalTypedDefault,
+  requireStringSpec,
+  optionalEnumSpec,
+  taggedUnion,
+  taggedUnionJson,
+  withConst,
+  type FieldSpec,
+  type FieldSpecMap,
+  type JsonNode,
+  type TaggedArm,
+  type TaggedUnionSchema,
+  type ValidateCtx,
+} from "./validate-core.js";
+import {
+  optionalCacheSpec,
+  requireCacheSpec,
+  ttlOnlyCacheSpec,
+} from "./cache.js";
+
+export function validateVariables(
+  ctx: ValidateCtx,
+  pathPrefix: string,
+  raw: unknown,
+): Record<string, VariableDecl> {
+  if (raw === undefined) return {};
+  if (!isPlainObject(raw)) {
+    ctx.issues.push({
+      path: pathPrefix,
+      message: `${pathPrefix} must be an object, got ${describeType(raw)}`,
+      line: findKeyLine(ctx.source, pathPrefix.split(".")),
+    });
+    return {};
+  }
+
+  const out: Record<string, VariableDecl> = {};
+  for (const [name, decl] of Object.entries(raw)) {
+    const parsed = taggedUnion(
+      ctx,
+      VARIABLE_SCHEMA,
+      `${pathPrefix}.${name}`,
+      decl,
+    );
+    if (parsed !== null) out[name] = parsed;
+  }
+  return out;
+}
+
+// [LAW:types-are-the-program] `value` is a required union literal with a bespoke
+// message whose line points at the variable (not `.value`) — a custom spec, since
+// the generic string/enum specs encode different line behavior.
+function literalValueSpec(): FieldSpec<string | number | boolean> {
+  return {
+    required: true,
+    json: { type: ["string", "number", "boolean"] },
+    parse: (ctx, path, _field, raw) => {
+      const value = raw.value;
+      if (
+        typeof value !== "string" &&
+        typeof value !== "number" &&
+        typeof value !== "boolean"
+      ) {
+        ctx.issues.push({
+          path: `${path}.value`,
+          message: `literal value must be string|number|boolean, got ${describeType(value)}`,
+          line: findKeyLine(ctx.source, path.split(".")),
+        });
+        return undefined;
+      }
+      return value;
+    },
+  };
+}
+
+// [LAW:types-are-the-program] `field` is a required member of the closed GitField
+// set with a bespoke one-of message — a custom spec for the same reason.
+function gitFieldSpec(): FieldSpec<GitField> {
+  return {
+    required: true,
+    json: { enum: [...GIT_FIELDS] },
+    parse: (ctx, path, _field, raw) => {
+      const field = raw.field;
+      if (
+        typeof field !== "string" ||
+        !GIT_FIELDS.includes(field as GitField)
+      ) {
+        ctx.issues.push({
+          path: `${path}.field`,
+          message: `git field must be one of: ${GIT_FIELDS.join(", ")}, got ${JSON.stringify(field)}`,
+          line: findKeyLine(ctx.source, [...path.split("."), "field"]),
+        });
+        return undefined;
+      }
+      return field as GitField;
+    },
+  };
+}
+
+// [LAW:types-are-the-program] `input`'s `default` carries the cross-field
+// invariant — it must match the declared `type` (an absent or invalid `type`
+// defaults the check to "string"). A field spec receives the WHOLE record, so it
+// reads its sibling `raw.type` to pick the expected type WITHOUT re-reporting a
+// bad type (the `type` field spec owns that error — reading raw here avoids the
+// duplicate issue). This is what lets `input` derive BOTH `parse` and `json` from
+// one field map via `arm()`, like every other arm — closing the last spot where
+// the two interpreters were authored independently [LAW:one-source-of-truth].
+function inputDefaultSpec(): FieldSpec<string | number | boolean> {
+  return {
+    required: false,
+    json: { type: ["string", "number", "boolean"] },
+    parse: (ctx, path, _field, raw) => {
+      const t = raw.type;
+      const expected =
+        t === "number" || t === "boolean" || t === "string" ? t : "string";
+      return optionalTypedDefault(ctx, path, raw, expected);
+    },
+  };
+}
+
+// [LAW:dataflow-not-control-flow] Each arm's field set is DATA over the member's
+// non-`kind` fields; the engine supplies the discriminator. `fields` runs every
+// spec (reporting all issues) and fails the arm when a required field is absent
+// or invalid — the conditional-spread + result-threading the old switch hand-rolled.
+const LITERAL_FIELDS: FieldSpecMap<Omit<LiteralVarDecl, "kind">> = {
+  value: literalValueSpec(),
+  default: optionalStringSpec(),
+};
+const INPUT_FIELDS: FieldSpecMap<Omit<InputVarDecl, "kind">> = {
+  path: requireStringSpec(),
+  type: optionalEnumSpec(["string", "number", "boolean"] as const),
+  default: inputDefaultSpec(),
+};
+const ENV_FIELDS: FieldSpecMap<Omit<EnvVarDecl, "kind">> = {
+  name: requireStringSpec(),
+  default: optionalStringSpec(),
+};
+const FILE_FIELDS: FieldSpecMap<Omit<FileVarDecl, "kind">> = {
+  path: requireStringSpec(),
+  readMode: optionalEnumSpec(["whole", "first-line"] as const),
+  regex: optionalStringSpec(),
+  cache: requireCacheSpec("file"),
+  default: optionalStringSpec(),
+};
+const SHELL_FIELDS: FieldSpecMap<Omit<ShellVarDecl, "kind">> = {
+  command: requireStringSpec(),
+  regex: optionalStringSpec(),
+  cache: requireCacheSpec("shell"),
+  default: optionalStringSpec(),
+};
+const TEMPLATE_FIELDS: FieldSpecMap<Omit<TemplateVarDecl, "kind">> = {
+  template: requireStringSpec(),
+  cache: optionalCacheSpec(),
+  default: optionalStringSpec(),
+};
+const TIME_FIELDS: FieldSpecMap<Omit<TimeVarDecl, "kind">> = {
+  layout: requireStringSpec(),
+  // [LAW:no-silent-failure] ttl-only: the runtime honors no other invalidation
+  // on a clock-driven var, so the loader rejects what it would otherwise have
+  // had to silently coerce.
+  cache: ttlOnlyCacheSpec(),
+  default: optionalStringSpec(),
+};
+const GIT_VAR_FIELDS: FieldSpecMap<Omit<GitVarDecl, "kind">> = {
+  field: gitFieldSpec(),
+  cache: requireCacheSpec("git"),
+  default: optionalStringSpec(),
+};
+const STATE_FIELDS: FieldSpecMap<Omit<StateVarDecl, "kind">> = {
+  key: requireStringSpec(),
+  default: optionalStringSpec(),
+};
+
+// [LAW:decomposition] A regular arm parses its non-`kind` fields via `fields` and
+// re-attaches the tag the engine already validated; null threading is preserved.
+function arm<
+  K extends VariableDecl["kind"],
+  M extends Omit<Extract<VariableDecl, { kind: K }>, "kind">,
+>(
+  kind: K,
+  fieldMap: FieldSpecMap<M>,
+): TaggedArm<Extract<VariableDecl, { kind: K }>> {
+  return {
+    // [LAW:one-source-of-truth] The arm's emit facet: the member object schema
+    // with its `kind` discriminator baked in — `objectJson` over the SAME field
+    // map `fields` validates, plus `{ kind: { const } }`. taggedUnionJson collects
+    // these verbatim into the union's anyOf.
+    json: withConst(objectJson(fieldMap), "kind", kind),
+    parse: (ctx: ValidateCtx, path: string, raw: Record<string, unknown>) => {
+      const body = fields(ctx, fieldMap, path, raw);
+      // [LAW:types-are-the-program] `fieldMap: FieldSpecMap<M>` is checked against
+      // the member's non-`kind` fields at each call site, so {kind, ...body} IS the
+      // member; TS can't relate the reconstruction to the distributed Extract for a
+      // generic K, hence the cast — the call-site check carries the real guarantee.
+      return body === null
+        ? null
+        : ({ kind, ...body } as unknown as Extract<VariableDecl, { kind: K }>);
+    },
+  };
+}
+
+const VARIABLE_SCHEMA: TaggedUnionSchema<VariableDecl, "kind"> = {
+  tag: "kind",
+  noun: "source kind",
+  arms: {
+    literal: arm("literal", LITERAL_FIELDS),
+    // [LAW:one-source-of-truth] `input`'s `default`/`type` cross-field invariant
+    // lives in `inputDefaultSpec` (a field spec reading its sibling), so `input`
+    // is one field map like every other arm — `arm()` derives both `parse` and
+    // `json` from INPUT_FIELDS, no hand-authored schema to keep in sync.
+    input: arm("input", INPUT_FIELDS),
+    env: arm("env", ENV_FIELDS),
+    file: arm("file", FILE_FIELDS),
+    shell: arm("shell", SHELL_FIELDS),
+    template: arm("template", TEMPLATE_FIELDS),
+    time: arm("time", TIME_FIELDS),
+    git: arm("git", GIT_VAR_FIELDS),
+    state: arm("state", STATE_FIELDS),
+  },
+};
+
+// [LAW:one-source-of-truth] One VariableDecl's schema, derived from the SAME
+// VARIABLE_SCHEMA the validator interprets — the tag-by-kind anyOf.
+export function variableDeclJson(): JsonNode {
+  return taggedUnionJson(VARIABLE_SCHEMA);
+}
+
+// [LAW:one-source-of-truth] The `variables` block (and a segment's nested `vars`)
+// is a name → VariableDecl map; both surfaces emit this one shape, symmetric to
+// both calling `validateVariables`.
+export function variablesMapJson(): JsonNode {
+  return { type: "object", additionalProperties: variableDeclJson() };
+}

package/src/daemon/acquire.ts

@@ -0,0 +1,411 @@
+import fs from "node:fs";
+import net from "node:net";
+import { launchDetachedSync } from "../proc/launch";
+import process from "node:process";
+import { socketPath, spawnLockPath, daemonDir } from "./paths";
+
+// [LAW:single-enforcer] One primitive per runtime that owns the entire
+// "obtain a daemon" verb. Every spawn site in the Node runtime now flows
+// through this one path; the Rust client mirrors it in its own
+// obtain-daemon primitive. Both runtimes agree on socketPath() and
+// spawnLockPath() *and* on the lock mechanism: open(path, O_CREAT | O_EXCL)
+// — existence == held; release by unlinking. A Rust kick and a Node kick
+// are mutually recognizable.
+//
+// [LAW:dataflow-not-control-flow] Callers do not get to choose whether to
+// spawn. They request a daemon; this function returns one of three typed
+// outcomes. The decision lives in the data (connect result, lock acquisition,
+// re-check after lock).
+
+export type ObtainResult =
+  | { kind: "attached" }
+  | { kind: "started" }
+  | { kind: "failed"; reason: string };
+
+interface ObtainOpts {
+  // Total deadline for the entire obtain operation. After this elapses we
+  // return { kind: "failed" } even if a daemon could come up shortly. Default
+  // 2000ms — generous for cold start, tight enough to bound user-visible
+  // latency on a busted state directory.
+  totalTimeoutMs?: number;
+  // Per-connect probe timeout. AF_UNIX connect to a live listener is sub-ms;
+  // anything slower implies "no listener" in practice.
+  connectTimeoutMs?: number;
+  // How long to wait after spawning before giving up on the daemon coming up.
+  spawnReadyTimeoutMs?: number;
+  // After this much continuous contention on spawn.lock without a daemon
+  // appearing, give up on the lock and spawn anyway. The bind() inside the
+  // daemon arbitrates duplicates, so a stuck lock degrades to bind-arbitrated
+  // contention instead of a multi-second availability gap. Default
+  // totalTimeoutMs / 2.
+  lockFallbackMs?: number;
+  // Test hook: replace the actual spawn call. Returning false simulates
+  // "spawn failed"; default spawns the real daemon.
+  spawn?: () => boolean;
+}
+
+const DEFAULT_OPTS: Required<Omit<ObtainOpts, "spawn" | "lockFallbackMs">> = {
+  totalTimeoutMs: 2000,
+  connectTimeoutMs: 50,
+  spawnReadyTimeoutMs: 1500,
+};
+
+export async function obtainDaemon(
+  opts: ObtainOpts = {},
+): Promise<ObtainResult> {
+  const settings = { ...DEFAULT_OPTS, ...opts };
+  const spawnFn = opts.spawn ?? spawnDaemonDetachedReal;
+  const deadline = Date.now() + settings.totalTimeoutMs;
+  const lockFallbackMs =
+    opts.lockFallbackMs ?? Math.floor(settings.totalTimeoutMs / 2);
+
+  // [LAW:no-defensive-null-guards] obtainDaemon is typed Promise<ObtainResult>
+  // — synchronous filesystem failures (read-only FS, permission denial) must
+  // become typed failure outcomes, not throws that surprise the caller.
+  const setupErr = ensureStateDir();
+  if (setupErr) return { kind: "failed", reason: setupErr };
+
+  // Fast path: is a daemon already listening?
+  if (await canConnect(socketPath(), settings.connectTimeoutMs)) {
+    return { kind: "attached" };
+  }
+
+  // No daemon yet. Try to win the spawn-lock so we are the one to bring it up.
+  const contentionStart = Date.now();
+  while (Date.now() < deadline) {
+    const lock = tryAcquireSpawnLock();
+    if (lock.kind === "error") {
+      // [LAW:no-silent-fallbacks] Unrecoverable errors (EACCES, ENOTDIR,
+      // broken state dir) must not silently degrade into a contention loop
+      // + timeout. The caller gets an actionable reason.
+      return { kind: "failed", reason: `spawn-lock: ${lock.reason}` };
+    }
+    if (lock.kind === "held") {
+      try {
+        // Re-check: another caller may have spawned a daemon between our
+        // initial connect and our lock acquisition.
+        if (await canConnect(socketPath(), settings.connectTimeoutMs)) {
+          return { kind: "attached" };
+        }
+        return await spawnAndWaitForReady(
+          spawnFn,
+          settings.spawnReadyTimeoutMs,
+          settings.connectTimeoutMs,
+          deadline,
+          "",
+        );
+      } finally {
+        releaseSpawnLock();
+      }
+    }
+    // Lock contended. Another caller is in the spawn window — brief wait,
+    // then re-check for the socket they're bringing up.
+    await sleep(20);
+    if (await canConnect(socketPath(), settings.connectTimeoutMs)) {
+      return { kind: "attached" };
+    }
+    // [LAW:dataflow-not-control-flow] spawn.lock is an optimization; bind()
+    // is the load-bearing exclusion. If we've been contended past the
+    // fallback threshold (e.g. crashed lock holder, slow staleness reclaim),
+    // bypass the lock and let bind() inside the daemon arbitrate duplicates.
+    // Same shape as a fresh spawn — caller pays one extra Node startup cost
+    // in the worst case, which is the right trade for availability.
+    if (Date.now() - contentionStart > lockFallbackMs) {
+      return await spawnAndWaitForReady(
+        spawnFn,
+        settings.spawnReadyTimeoutMs,
+        settings.connectTimeoutMs,
+        deadline,
+        " (lock-fallback)",
+      );
+    }
+  }
+
+  return { kind: "failed", reason: "timeout obtaining daemon" };
+}
+
+// Spawn the daemon, then poll for it to bind. Returns the typed outcome.
+// Shared by the lock-held path and the lock-fallback path so they don't drift.
+async function spawnAndWaitForReady(
+  spawnFn: () => boolean,
+  spawnReadyTimeoutMs: number,
+  connectTimeoutMs: number,
+  outerDeadline: number,
+  reasonSuffix: string,
+): Promise<ObtainResult> {
+  // [LAW:no-defensive-null-guards] obtainDaemon is typed Promise<ObtainResult>.
+  // A synchronous throw from child_process.spawn (ENOENT, invalid options)
+  // must become a typed failure, not a rejected promise.
+  let didSpawn = false;
+  try {
+    didSpawn = spawnFn();
+  } catch (e) {
+    return {
+      kind: "failed",
+      reason: `spawn threw${reasonSuffix}: ${(e as Error).message}`,
+    };
+  }
+  if (!didSpawn) {
+    return {
+      kind: "failed",
+      reason: `spawn returned false${reasonSuffix}`,
+    };
+  }
+  const readyDeadline = Math.min(
+    Date.now() + spawnReadyTimeoutMs,
+    outerDeadline,
+  );
+  while (Date.now() < readyDeadline) {
+    if (await canConnect(socketPath(), connectTimeoutMs)) {
+      return { kind: "started" };
+    }
+    await sleep(20);
+  }
+  return {
+    kind: "failed",
+    reason: `daemon did not bind in time${reasonSuffix}`,
+  };
+}
+
+// Synchronous fire-and-forget kick — used for "daemon-miss" recovery where
+// the current render is already lost and we just want to warm the daemon for
+// the next refresh. Mirrors the Rust client's obtain_daemon_kick at the same
+// shape: lock + spawn + release, all synchronous, no await.
+//
+// [LAW:one-type-per-behavior] This is the Node mirror of Rust's
+// obtain_daemon_kick in rust-client/src/main.rs. Both runtimes use the same
+// existence-as-lock semantics so a Rust kick and a Node kick are mutually
+// recognizable. The bind() inside the daemon arbitrates any duplicate spawns
+// that slip past the lock.
+//
+// Why synchronous: callers (src/index.ts, src/install/index.ts) call this
+// immediately before process.exit(). An async variant would suspend on the
+// first await and never resume — process.exit would kill the process before
+// child_process.spawn ever runs. The lock+spawn must complete in synchronous
+// turn for the daemon to actually start.
+// If the spawn.lock has existed longer than this, the kick path assumes the
+// holder crashed mid-spawn and overrides to preserve availability.
+// Calibrated to be much larger than any legitimate hold:
+//   - A healthy kick holds for <10ms (fork + release).
+//   - obtainDaemon's lock-held path can hold up to spawnReadyTimeoutMs
+//     (1500ms default) while polling for the new daemon to bind.
+// 2s leaves a comfortable margin above the slowest legitimate holder while
+// still recovering from a crashed-mid-spawn holder well before STALE_LOCK_MS.
+const KICK_CONTENDED_OVERRIDE_MS = 2_000;
+
+export function obtainDaemonKick(opts: { spawn?: () => boolean } = {}): void {
+  if (ensureStateDir() !== null) return;
+  const spawnFn = opts.spawn ?? spawnDaemonDetachedReal;
+  const lock = tryAcquireSpawnLock();
+
+  // [LAW:dataflow-not-control-flow] Lock outcome is data, not control flow.
+  // - "contended": typically means another caller is in the spawn window;
+  //   trust them and return. BUT: if the lock has been held suspiciously
+  //   long, the holder is likely crashed mid-spawn — override and spawn
+  //   unlocked. bind() arbitrates any duplicates.
+  // - "error": spawn-lock unavailable (broken state dir, perms). Per the
+  //   architecture, spawn.lock is an *optimization* on top of bind()'s
+  //   load-bearing exclusion — a lock error should NOT make this kick a
+  //   hard stop on availability. Fall through to an unlocked spawn.
+  // - "held": normal path — spawn under the lock.
+  if (lock.kind === "contended") {
+    const ageMs = spawnLockAgeMs();
+    if (ageMs !== null && ageMs > KICK_CONTENDED_OVERRIDE_MS) {
+      process.stderr.write(
+        `cc-candybar: spawn-lock held ${ageMs}ms (likely crashed holder) — spawning unlocked\n`,
+      );
+      safeSpawn(spawnFn);
+    }
+    return;
+  }
+  if (lock.kind === "error") {
+    process.stderr.write(
+      `cc-candybar: spawn-lock unavailable (${lock.reason}) — spawning unlocked\n`,
+    );
+    safeSpawn(spawnFn);
+    return;
+  }
+  try {
+    safeSpawn(spawnFn);
+  } finally {
+    releaseSpawnLock();
+  }
+}
+
+function spawnLockAgeMs(): number | null {
+  try {
+    const st = fs.statSync(spawnLockPath());
+    return Date.now() - st.mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+// [LAW:no-defensive-null-guards] Kick path is fire-and-forget; a spawn
+// failure here is best-effort. Swallowing prevents an uncaught throw from
+// crashing the calling process at the wrong moment (right before its own
+// exit). Both failure modes (throw and false-return) are logged via stderr
+// so kick failures stay visible — silent failure is the worst outcome.
+function safeSpawn(spawnFn: () => boolean): void {
+  try {
+    if (!spawnFn()) {
+      process.stderr.write(
+        "cc-candybar: daemon spawn returned false (unable to resolve script path?)\n",
+      );
+    }
+  } catch (e) {
+    process.stderr.write(
+      `cc-candybar: daemon spawn failed: ${(e as Error).message}\n`,
+    );
+  }
+}
+
+// ─── Spawn-lock (Node side) ──────────────────────────────────────────────────
+//
+// O_EXLOCK / fcntl(F_SETLK) aren't reliably exposed across Node platforms, so
+// we use the simplest portable atomic primitive: open(path, "wx"). The file
+// records owner pid + timestamp. Staleness is time-based — if the file is
+// older than STALE_LOCK_MS we forcibly claim it. The spawn window is
+// sub-second in practice; 10s is a wide tolerance.
+//
+// [LAW:no-defensive-null-guards] The staleness reclaim is not a "the holder
+// might be dead, let me check" guard — it is the bounded-staleness policy of
+// the lock. The bind() in the daemon is the real correctness boundary; this
+// lock is a thundering-herd optimization, so a missed dedup just means one
+// extra Node process eats a bind() race and exits.
+
+const STALE_LOCK_MS = 10_000;
+
+let heldLock: { fd: number; path: string } | null = null;
+
+type LockOutcome =
+  | { kind: "held" }
+  | { kind: "contended" }
+  | { kind: "error"; reason: string };
+
+function tryAcquireSpawnLock(): LockOutcome {
+  const path = spawnLockPath();
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(path, "wx", 0o600);
+      try {
+        fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+      } catch {}
+      heldLock = { fd, path };
+      return { kind: "held" };
+    } catch (e) {
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code !== "EEXIST") {
+        // EACCES, ENOTDIR, ENOSPC, etc. are not contention — they are
+        // unrecoverable. Surface upward instead of pretending we lost a race.
+        return {
+          kind: "error",
+          reason: `openSync(${path}): ${code ?? (e as Error).message}`,
+        };
+      }
+    }
+    if (!isLockStale(path)) return { kind: "contended" };
+    try {
+      fs.unlinkSync(path);
+    } catch (e) {
+      // ENOENT means someone (the rightful holder, or another reclaimer)
+      // already removed the file — that's the desired post-condition, so
+      // continue to the retry. Other failures (EACCES, ENOSPC) are real.
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT") {
+        return {
+          kind: "error",
+          reason: `unlink stale spawn.lock: ${(e as Error).message}`,
+        };
+      }
+    }
+  }
+  return { kind: "contended" };
+}
+
+function isLockStale(path: string): boolean {
+  try {
+    const st = fs.statSync(path);
+    return Date.now() - st.mtimeMs > STALE_LOCK_MS;
+  } catch {
+    return true;
+  }
+}
+
+function releaseSpawnLock(): void {
+  if (!heldLock) return;
+  const { fd, path } = heldLock;
+  heldLock = null;
+  try {
+    fs.closeSync(fd);
+  } catch {}
+  try {
+    fs.unlinkSync(path);
+  } catch {}
+}
+
+// ─── State-dir setup ────────────────────────────────────────────────────────
+
+// Returns null on success, or a reason string on unrecoverable failure. Used
+// by both obtainDaemon (which converts to a `failed` result) and
+// obtainDaemonKick (which silently gives up — there is no caller to report to).
+function ensureStateDir(): string | null {
+  try {
+    fs.mkdirSync(daemonDir(), { recursive: true });
+    return null;
+  } catch (e) {
+    return `mkdir ${daemonDir()}: ${(e as Error).message}`;
+  }
+}
+
+// ─── Connect probe ──────────────────────────────────────────────────────────
+
+function canConnect(sockPath: string, timeoutMs: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const sock = net.connect(sockPath);
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const done = (result: boolean): void => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      sock.removeAllListeners();
+      sock.destroy();
+      resolve(result);
+    };
+    sock.once("connect", () => done(true));
+    sock.once("error", () => done(false));
+    timer = setTimeout(() => done(false), timeoutMs);
+    timer.unref();
+  });
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms).unref());
+}
+
+// ─── Default spawn implementation ───────────────────────────────────────────
+//
+// Cap V8 old-generation at 400 MB so GC fires before RSS hits the 512 MB hard
+// limit. The Rust client mirrors this in rust-client/src/main.rs
+// (spawn_daemon_detached) — keep the two in sync when changing this value.
+//
+// [LAW:single-enforcer] Routes through src/proc/launch so daemon-spawn shows
+// up in subprocess metering (category "daemon-spawn"). The launch primitive
+// owns the only child_process import in this file.
+function spawnDaemonDetachedReal(): boolean {
+  const node = process.execPath;
+  const script = process.argv[1];
+  if (!script) return false;
+  // [LAW:no-silent-fallbacks] launchDetachedSync returns the typed outcome
+  // synchronously, so the spawn-failure case (ENOENT, EACCES, EAGAIN under
+  // process-table pressure) propagates as `false` instead of being silently
+  // reported as success. The previous `void launch({detached:true})` form
+  // discarded the Promise and unconditionally returned true.
+  const result = launchDetachedSync({
+    bin: node,
+    args: ["--max-old-space-size=400", script, "daemon"],
+    category: "daemon-spawn",
+  });
+  return result.ok;
+}