harnery 0.34.0 → 0.35.0

package/src/core/semantic/service-status.ts

@@ -0,0 +1,118 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { hostname } from "node:os";
+import { resolve } from "node:path";
+
+import { readSemanticManifest, semanticPaths } from "./storage.ts";
+
+export const SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION = 1 as const;
+const FOREIGN_STATUS_STALE_MS = 2 * 60_000;
+const MAX_FILE_BYTES = 512 * 1024;
+
+export type SemanticServiceState = "starting" | "running" | "stopping" | "stopped";
+export type SemanticServiceErrorCode = "ledger_unavailable" | "semantic_pass_failed";
+
+export interface SemanticServiceStatusRecord {
+  schema_version: typeof SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION;
+  pid: number;
+  host: string;
+  nonce: string;
+  state: SemanticServiceState;
+  started_at: string;
+  heartbeat_at: string;
+  calls_per_hour?: number;
+  sweep_count: number;
+  pass_count: number;
+  model_calls: number;
+  cache_hits: number;
+  last_sweep_at?: string;
+  last_pass_at?: string;
+  last_error_code?: SemanticServiceErrorCode;
+  stopped_at?: string;
+}
+
+export interface SemanticServiceStatus {
+  running: boolean;
+  stale: boolean;
+  record?: SemanticServiceStatusRecord;
+  newest_successful_pass?: string;
+  pending_count: number;
+}
+
+/** Read-only service health. This module cannot spawn, signal, or write. */
+export function readSemanticServiceStatus(coordRootRaw: string): SemanticServiceStatus {
+  const coordRoot = resolve(coordRootRaw);
+  const record = readStatusRecord(coordRoot);
+  const manifest = safeManifest(coordRoot);
+  if (!record) {
+    return {
+      running: false,
+      stale: false,
+      newest_successful_pass: manifest?.newest_successful_pass,
+      pending_count: manifest?.pending.length ?? 0,
+    };
+  }
+  const running = statusOwnerIsLive(record);
+  return {
+    running,
+    stale: !running && record.state !== "stopped",
+    record,
+    newest_successful_pass: manifest?.newest_successful_pass,
+    pending_count: manifest?.pending.length ?? 0,
+  };
+}
+
+function safeManifest(coordRoot: string) {
+  try {
+    return readSemanticManifest(coordRoot);
+  } catch {
+    return undefined;
+  }
+}
+
+function readStatusRecord(coordRoot: string): SemanticServiceStatusRecord | undefined {
+  const path = semanticPaths(coordRoot).service;
+  if (!existsSync(path)) return undefined;
+  try {
+    const value = readBoundedJson<SemanticServiceStatusRecord>(path, "semantic service status");
+    if (
+      value.schema_version !== SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION ||
+      !Number.isSafeInteger(value.pid) ||
+      value.pid < 1 ||
+      typeof value.host !== "string" ||
+      typeof value.nonce !== "string" ||
+      !validTimestamp(value.started_at) ||
+      !validTimestamp(value.heartbeat_at)
+    ) {
+      return undefined;
+    }
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
+function statusOwnerIsLive(record: SemanticServiceStatusRecord): boolean {
+  if (record.state === "stopped") return false;
+  if (record.host === hostname()) return pidAlive(record.pid);
+  const age = Date.now() - Date.parse(record.heartbeat_at);
+  return Number.isFinite(age) && age < FOREIGN_STATUS_STALE_MS;
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function readBoundedJson<T>(path: string, label: string): T {
+  const size = statSync(path).size;
+  if (size <= 0 || size > MAX_FILE_BYTES) throw new Error(`${label} has invalid size ${size}`);
+  return JSON.parse(readFileSync(path, "utf8")) as T;
+}
+
+function validTimestamp(value: unknown): value is string {
+  return typeof value === "string" && Number.isFinite(Date.parse(value));
+}

package/src/core/semantic/service.ts

@@ -0,0 +1,580 @@
+import { spawn } from "node:child_process";
+import { randomBytes, randomUUID } from "node:crypto";
+import {
+  appendFileSync,
+  chmodSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  watch,
+  writeFileSync,
+} from "node:fs";
+import { hostname } from "node:os";
+import { dirname, resolve } from "node:path";
+import {
+  type ReadLedgerV3SinceResult,
+  readEventV3ControlState,
+  readLedgerV3Since,
+} from "../events/v3/index.ts";
+import { eventV3ActiveWatchPath } from "../events/v3/reader.ts";
+import type { SemanticHarness } from "./contract.ts";
+import { runSemanticOnce, type SemanticOnceReport } from "./once.ts";
+import {
+  readSemanticServiceStatus,
+  SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION,
+  type SemanticServiceErrorCode,
+  type SemanticServiceStatus,
+  type SemanticServiceStatusRecord,
+} from "./service-status.ts";
+import {
+  listSemanticAgentDocuments,
+  readSemanticManifest,
+  semanticPaths,
+  writeSemanticManifest,
+} from "./storage.ts";
+
+export {
+  readSemanticServiceStatus,
+  SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION,
+  type SemanticServiceErrorCode,
+  type SemanticServiceState,
+  type SemanticServiceStatus,
+  type SemanticServiceStatusRecord,
+} from "./service-status.ts";
+
+export const SEMANTIC_SERVICE_DEFAULT_DEBOUNCE_MS = 5_000;
+export const SEMANTIC_SERVICE_DEFAULT_WAKE_MS = 1_000;
+export const SEMANTIC_SERVICE_DEFAULT_HEARTBEAT_MS = 5_000;
+const FOREIGN_STATUS_STALE_MS = 2 * 60_000;
+const MAX_FILE_BYTES = 512 * 1024;
+const MAX_LOG_BYTES = 512 * 1024;
+const REPEATED_ERROR_LOG_INTERVAL_MS = 60_000;
+
+interface SemanticServiceLease {
+  pid: number;
+  host: string;
+  nonce: string;
+  created_at: string;
+}
+
+export interface RunSemanticServiceDaemonInput {
+  coordRoot: string;
+  callsPerHour?: number;
+  debounceMs?: number;
+  wakeIntervalMs?: number;
+  heartbeatIntervalMs?: number;
+  maxSweeps?: number;
+  now?: () => Date;
+  readSince?: typeof readLedgerV3Since;
+  runOnce?: (input: {
+    coordRoot: string;
+    callsPerHour?: number;
+    debounceMs: number;
+    shouldStop: () => boolean;
+  }) => Promise<SemanticOnceReport>;
+  waitForWake?: (milliseconds: number) => Promise<void>;
+}
+
+export type EnsureSemanticServiceState =
+  | "running"
+  | "started"
+  | "paused"
+  | "inactive"
+  | "unavailable";
+
+export interface EnsureSemanticServiceResult {
+  state: EnsureSemanticServiceState;
+  status?: SemanticServiceStatus;
+  error?: string;
+}
+
+export interface EnsureSemanticServiceDependencies {
+  readStatus: (coordRoot: string) => SemanticServiceStatus;
+  start: (coordRoot: string) => Promise<SemanticServiceStatus>;
+  isPaused: (coordRoot: string) => boolean;
+  isActive: (coordRoot: string) => boolean;
+}
+
+export async function spawnSemanticService(
+  coordRootRaw: string,
+  options: { callsPerHour?: number } = {},
+): Promise<SemanticServiceStatus> {
+  const coordRoot = resolve(coordRootRaw);
+  const current = readSemanticServiceStatus(coordRoot);
+  if (current.running) {
+    throw new Error(`semantic service is already running under pid ${current.record?.pid}`);
+  }
+  const paths = semanticPaths(coordRoot);
+  mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+  const logFd = openSync(paths.log, "a", 0o600);
+  chmodSync(paths.log, 0o600);
+  const harnBin = new URL("../../../bin/harn", import.meta.url).pathname;
+  if (!existsSync(harnBin)) {
+    closeSync(logFd);
+    throw new Error(`cannot find harn executable at ${harnBin}`);
+  }
+  const args = ["semantic", "service", "daemon", "--root", coordRoot];
+  if (options.callsPerHour !== undefined) {
+    args.push("--calls-per-hour", String(options.callsPerHour));
+  }
+  let spawnError: Error | undefined;
+  const child = spawn(harnBin, args, {
+    cwd: coordRoot,
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    env: {
+      ...process.env,
+      HARNERY_COORD_ROOT_OVERRIDE: coordRoot,
+      HARNERY_OUTPUT_SESSION_TEE: "0",
+    },
+  });
+  child.once("error", (error) => {
+    spawnError = error;
+  });
+  closeSync(logFd);
+  child.unref();
+  const deadline = Date.now() + 5_000;
+  while (Date.now() < deadline) {
+    await delay(50);
+    if (spawnError) throw spawnError;
+    const status = readSemanticServiceStatus(coordRoot);
+    if (status.running && status.record?.pid === child.pid) return status;
+    if (child.exitCode !== null) break;
+  }
+  throw new Error(`semantic service failed to start; inspect ${paths.log}`);
+}
+
+/**
+ * Start semantic reading when V3 is active, unless an operator paused it.
+ *
+ * Dashboard hosts call this before launching their web process. A failed
+ * semantic launch is reported as data instead of throwing so the read-only
+ * dashboard remains available.
+ */
+export async function ensureSemanticServiceRunning(
+  coordRootRaw: string,
+  overrides: Partial<EnsureSemanticServiceDependencies> = {},
+): Promise<EnsureSemanticServiceResult> {
+  const coordRoot = resolve(coordRootRaw);
+  const dependencies: EnsureSemanticServiceDependencies = {
+    readStatus: readSemanticServiceStatus,
+    start: spawnSemanticService,
+    isPaused: (root) => existsSync(semanticPaths(root).stop),
+    isActive: (root) => readEventV3ControlState(root).state === "active",
+    ...overrides,
+  };
+  const status = dependencies.readStatus(coordRoot);
+  if (status.running) return { state: "running", status };
+  if (dependencies.isPaused(coordRoot)) return { state: "paused", status };
+  if (!dependencies.isActive(coordRoot)) return { state: "inactive", status };
+  try {
+    return { state: "started", status: await dependencies.start(coordRoot) };
+  } catch (error) {
+    return {
+      state: "unavailable",
+      status: dependencies.readStatus(coordRoot),
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function requestSemanticServiceStop(coordRootRaw: string): SemanticServiceStatus {
+  const coordRoot = resolve(coordRootRaw);
+  const status = readSemanticServiceStatus(coordRoot);
+  mkdirSync(semanticPaths(coordRoot).root, { recursive: true, mode: 0o700 });
+  writePrivateJsonAtomic(semanticPaths(coordRoot).stop, {
+    requested_at: new Date().toISOString(),
+    requested_by_pid: process.pid,
+  });
+  if (status.running && status.record?.host === hostname()) {
+    try {
+      process.kill(status.record.pid, "SIGTERM");
+    } catch {
+      // The durable stop request remains for a racing or restarted daemon.
+    }
+  }
+  return readSemanticServiceStatus(coordRoot);
+}
+
+export async function runSemanticServiceDaemon(
+  input: RunSemanticServiceDaemonInput,
+): Promise<SemanticServiceStatusRecord> {
+  const coordRoot = resolve(input.coordRoot);
+  const paths = semanticPaths(coordRoot);
+  const release = acquireSemanticServiceLease(coordRoot);
+  rmSync(paths.stop, { force: true });
+  const now = input.now ?? (() => new Date());
+  const debounceMs = Math.max(0, input.debounceMs ?? SEMANTIC_SERVICE_DEFAULT_DEBOUNCE_MS);
+  const wakeIntervalMs = positiveInterval(
+    input.wakeIntervalMs ?? SEMANTIC_SERVICE_DEFAULT_WAKE_MS,
+    "wake interval",
+  );
+  const heartbeatIntervalMs = positiveInterval(
+    input.heartbeatIntervalMs ?? SEMANTIC_SERVICE_DEFAULT_HEARTBEAT_MS,
+    "heartbeat interval",
+  );
+  const readSince = input.readSince ?? readLedgerV3Since;
+  const runOnce =
+    input.runOnce ??
+    (async (options) =>
+      await runSemanticOnce({
+        coordRoot: options.coordRoot,
+        callsPerHour: options.callsPerHour,
+        debounceMs: options.debounceMs,
+        shouldStop: options.shouldStop,
+      }));
+  const startedAt = now().toISOString();
+  const status: SemanticServiceStatusRecord = {
+    schema_version: SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION,
+    pid: process.pid,
+    host: hostname(),
+    nonce: randomUUID(),
+    state: "starting",
+    started_at: startedAt,
+    heartbeat_at: startedAt,
+    ...(input.callsPerHour !== undefined ? { calls_per_hour: input.callsPerHour } : {}),
+    sweep_count: 0,
+    pass_count: 0,
+    model_calls: 0,
+    cache_hits: 0,
+  };
+  let stopRequested = false;
+  let dirtySince: number | undefined;
+  let lastLoggedErrorCode: string | undefined;
+  let lastLoggedErrorAt = Number.NEGATIVE_INFINITY;
+  const writeStatus = (): void => {
+    status.heartbeat_at = now().toISOString();
+    writePrivateJsonAtomic(paths.service, status);
+  };
+  const requestStop = (): void => {
+    stopRequested = true;
+    status.state = "stopping";
+    writeStatus();
+  };
+  process.on("SIGINT", requestStop);
+  process.on("SIGTERM", requestStop);
+  status.state = "running";
+  writeStatus();
+  appendSemanticServiceLog(coordRoot, { event: "service_started" });
+  const heartbeat = setInterval(() => {
+    try {
+      writeStatus();
+    } catch {
+      // A later sweep or status read will expose the stopped or stale process.
+    }
+  }, heartbeatIntervalMs);
+  try {
+    while (!stopRequested && !existsSync(paths.stop)) {
+      const sweepAt = now();
+      status.sweep_count += 1;
+      try {
+        const before = safeManifest(coordRoot);
+        let read = readSince(coordRoot, before?.cursor, { authority: "active" });
+        if (read.reset_required) {
+          read = readSince(coordRoot, undefined, { authority: "active" });
+        }
+        requireCompleteLedger(read);
+        if (read.events.length > 0 || !before?.cursor) {
+          dirtySince ??= sweepAt.getTime();
+        }
+        const hasPending = (before?.pending.length ?? 0) > 0;
+        const hasEligibleDeferred = listSemanticAgentDocuments(coordRoot).some(
+          (document) =>
+            document.reader_outcome === "deferred" &&
+            Date.parse(document.receipt.eligible_after) <= sweepAt.getTime(),
+        );
+        if (
+          hasPending ||
+          hasEligibleDeferred ||
+          (dirtySince !== undefined && sweepAt.getTime() - dirtySince >= debounceMs)
+        ) {
+          const report = await runOnce({
+            coordRoot,
+            ...(input.callsPerHour !== undefined ? { callsPerHour: input.callsPerHour } : {}),
+            debounceMs,
+            shouldStop: () => stopRequested || existsSync(paths.stop),
+          });
+          status.pass_count += 1;
+          status.model_calls += report.model_calls;
+          status.cache_hits += report.cache_hits;
+          status.last_pass_at = report.completed_at;
+          status.last_error_code = undefined;
+          lastLoggedErrorCode = undefined;
+          const after = safeManifest(coordRoot);
+          if (after && read.cursor) {
+            after.cursor = read.cursor;
+            writeSemanticManifest(coordRoot, after);
+          }
+          dirtySince = undefined;
+          const logEntry = {
+            event: "pass",
+            evidence_count: report.evidence_count,
+            evidence_by_harness: report.evidence_by_harness,
+            model_calls: report.model_calls,
+            cache_hits: report.cache_hits,
+            accepted: report.outcomes.filter((outcome) => outcome.action === "accepted").length,
+            unavailable: report.outcomes.filter((outcome) => outcome.action === "unavailable")
+              .length,
+            invalid: report.outcomes.filter((outcome) => outcome.action === "invalid").length,
+            deferred: report.outcomes.filter((outcome) => outcome.action === "deferred").length,
+            harness_metrics: semanticHarnessMetrics(report),
+          };
+          if (report.model_calls > 0 || report.cache_hits > 0 || logEntry.unavailable > 0) {
+            appendSemanticServiceLog(coordRoot, logEntry);
+          }
+        }
+      } catch (error) {
+        status.last_error_code = serviceErrorCode(error);
+        if (
+          status.last_error_code !== lastLoggedErrorCode ||
+          sweepAt.getTime() - lastLoggedErrorAt >= REPEATED_ERROR_LOG_INTERVAL_MS
+        ) {
+          appendSemanticServiceLog(coordRoot, {
+            event: "sweep_error",
+            reason_code: status.last_error_code,
+          });
+          lastLoggedErrorCode = status.last_error_code;
+          lastLoggedErrorAt = sweepAt.getTime();
+        }
+      }
+      status.last_sweep_at = now().toISOString();
+      writeStatus();
+      if (input.maxSweeps !== undefined && status.sweep_count >= input.maxSweeps) break;
+      if (!stopRequested && !existsSync(paths.stop)) {
+        if (input.waitForWake) await input.waitForWake(wakeIntervalMs);
+        else await waitForLedgerWake(eventV3ActiveWatchPath(coordRoot), wakeIntervalMs);
+      }
+    }
+  } finally {
+    clearInterval(heartbeat);
+    process.off("SIGINT", requestStop);
+    process.off("SIGTERM", requestStop);
+    status.state = "stopped";
+    status.stopped_at = now().toISOString();
+    writeStatus();
+    appendSemanticServiceLog(coordRoot, {
+      event: "service_stopped",
+      sweeps: status.sweep_count,
+      passes: status.pass_count,
+      model_calls: status.model_calls,
+    });
+    release();
+  }
+  return status;
+}
+
+export function acquireSemanticServiceLease(coordRootRaw: string): () => void {
+  const path = semanticPaths(coordRootRaw).lease;
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const owner: SemanticServiceLease = {
+    pid: process.pid,
+    host: hostname(),
+    nonce: randomUUID(),
+    created_at: new Date().toISOString(),
+  };
+  const acquire = (): boolean => {
+    try {
+      const fd = openSync(path, "wx", 0o600);
+      try {
+        writeFileSync(fd, `${JSON.stringify(owner)}\n`, "utf8");
+      } finally {
+        closeSync(fd);
+      }
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      return false;
+    }
+  };
+  if (!acquire()) {
+    const existing = readLease(path);
+    if (existing && leaseOwnerIsLive(existing)) {
+      throw new Error(`semantic service is already running under pid ${existing.pid}`);
+    }
+    unlinkSync(path);
+    if (!acquire()) throw new Error("semantic service lease raced with another process");
+  }
+  return () => {
+    try {
+      const existing = readLease(path);
+      if (existing?.nonce === owner.nonce) unlinkSync(path);
+    } catch {
+      // A later explicit start can recover a stale private lease.
+    }
+  };
+}
+
+interface SemanticHarnessPassMetrics {
+  evidence_count: number;
+  model_calls: number;
+  cache_hits: number;
+  accepted: number;
+  unavailable: number;
+  invalid: number;
+  deferred: number;
+  duration_ms: number[];
+  input_bytes: number[];
+  output_bytes: number[];
+}
+
+function semanticHarnessMetrics(
+  report: SemanticOnceReport,
+): Record<SemanticHarness, SemanticHarnessPassMetrics> {
+  const metrics: Record<SemanticHarness, SemanticHarnessPassMetrics> = {
+    "claude-code": emptyHarnessMetrics(report.evidence_by_harness["claude-code"]),
+    codex: emptyHarnessMetrics(report.evidence_by_harness.codex),
+    cursor: emptyHarnessMetrics(report.evidence_by_harness.cursor),
+  };
+  for (const outcome of report.outcomes) {
+    const harness = metrics[outcome.source_harness];
+    if (outcome.model_call) harness.model_calls += 1;
+    if (outcome.action === "cached") harness.cache_hits += 1;
+    if (outcome.action === "accepted") harness.accepted += 1;
+    if (outcome.action === "unavailable") harness.unavailable += 1;
+    if (outcome.action === "invalid") harness.invalid += 1;
+    if (outcome.action === "deferred") harness.deferred += 1;
+    if (outcome.duration_ms !== undefined) harness.duration_ms.push(outcome.duration_ms);
+    if (outcome.input_bytes !== undefined) harness.input_bytes.push(outcome.input_bytes);
+    if (outcome.output_bytes !== undefined) harness.output_bytes.push(outcome.output_bytes);
+  }
+  return metrics;
+}
+
+function emptyHarnessMetrics(evidenceCount: number): SemanticHarnessPassMetrics {
+  return {
+    evidence_count: evidenceCount,
+    model_calls: 0,
+    cache_hits: 0,
+    accepted: 0,
+    unavailable: 0,
+    invalid: 0,
+    deferred: 0,
+    duration_ms: [],
+    input_bytes: [],
+    output_bytes: [],
+  };
+}
+
+function requireCompleteLedger(read: ReadLedgerV3SinceResult): void {
+  if (!read.complete || read.diagnostics.length > 0) throw new Error("ledger_unavailable");
+}
+
+function serviceErrorCode(error: unknown): SemanticServiceErrorCode {
+  return error instanceof Error && error.message === "ledger_unavailable"
+    ? "ledger_unavailable"
+    : "semantic_pass_failed";
+}
+
+function safeManifest(coordRoot: string) {
+  try {
+    return readSemanticManifest(coordRoot);
+  } catch {
+    return undefined;
+  }
+}
+
+function readLease(path: string): SemanticServiceLease | undefined {
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8")) as Partial<SemanticServiceLease>;
+    if (
+      !Number.isSafeInteger(value.pid) ||
+      (value.pid ?? 0) < 1 ||
+      typeof value.host !== "string" ||
+      typeof value.nonce !== "string" ||
+      !validTimestamp(value.created_at)
+    ) {
+      return undefined;
+    }
+    return value as SemanticServiceLease;
+  } catch {
+    return undefined;
+  }
+}
+
+function leaseOwnerIsLive(lease: SemanticServiceLease): boolean {
+  if (lease.host !== hostname()) {
+    const age = Date.now() - Date.parse(lease.created_at);
+    return Number.isFinite(age) && age < FOREIGN_STATUS_STALE_MS;
+  }
+  return pidAlive(lease.pid);
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+async function waitForLedgerWake(path: string, milliseconds: number): Promise<void> {
+  await new Promise<void>((done) => {
+    let settled = false;
+    let watcher: ReturnType<typeof watch> | undefined;
+    const finish = (): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      watcher?.close();
+      done();
+    };
+    const timer = setTimeout(finish, milliseconds);
+    try {
+      watcher = watch(path, { persistent: false }, finish);
+    } catch {
+      // The timer is the polling fallback when the active file does not exist yet.
+    }
+  });
+}
+
+function appendSemanticServiceLog(coordRoot: string, entry: Record<string, unknown>): void {
+  const path = semanticPaths(coordRoot).log;
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  appendFileSync(
+    path,
+    `${JSON.stringify({ schema_version: 1, ts: new Date().toISOString(), ...entry })}\n`,
+    { encoding: "utf8", mode: 0o600 },
+  );
+  chmodSync(path, 0o600);
+  if (statSync(path).size <= MAX_LOG_BYTES) return;
+  const buffer = readFileSync(path);
+  const tail = buffer.subarray(Math.max(0, buffer.length - Math.floor(MAX_LOG_BYTES / 2)));
+  const newline = tail.indexOf(10);
+  const body = newline >= 0 ? tail.subarray(newline + 1) : tail;
+  const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+  writeFileSync(temporary, body, { flag: "wx", mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+function writePrivateJsonAtomic(path: string, value: unknown): void {
+  const body = `${JSON.stringify(value, null, 2)}\n`;
+  if (Buffer.byteLength(body) > MAX_FILE_BYTES) {
+    throw new Error(`semantic service file exceeds ${MAX_FILE_BYTES} bytes`);
+  }
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  chmodSync(dirname(path), 0o700);
+  const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+  writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+  renameSync(temporary, path);
+  chmodSync(path, 0o600);
+}
+
+function validTimestamp(value: unknown): value is string {
+  return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+
+function positiveInterval(value: number, label: string): number {
+  if (!Number.isFinite(value) || value < 1) throw new Error(`${label} must be positive`);
+  return Math.floor(value);
+}
+
+function delay(milliseconds: number): Promise<void> {
+  return new Promise((done) => setTimeout(done, milliseconds));
+}