@stigmer/cli 3.0.8

package/src/local/seedpack/content.ts

@@ -0,0 +1,223 @@
+// Resolution and on-demand acquisition of the seedpack content.
+//
+// The seedpack (system agents, skills, MCP servers, workflows under the
+// "stigmer" org) is the TS equivalent of the Go CLI's `go:embed`-ed bundle.
+// A lean `npx @stigmer/cli` must not carry ~300 content files (DD-002), so the
+// content ships as `@stigmer/seedpack` and is acquired on demand — the same
+// pattern as `@stigmer/runner-slim` and the managed Temporal binary.
+//
+// Two sources, tried in order (mirrors runtime/runner.ts):
+//   1. A repo-tree checkout (dev): `<repo>/seedpack`.
+//   2. The published `@stigmer/seedpack@<cli-version>`, installed on demand into
+//      ~/.stigmer/runtimes/<version>/ and read from
+//      node_modules/@stigmer/seedpack.
+//
+// The content-hash and extract logic mirror `@stigmer/seedpack` exactly (which
+// in turn mirrors the Go `seedpack` package); the CLI reimplements them over a
+// resolved directory so it stays decoupled from the package in the lean install
+// (where the package is not a dependency, only an on-demand artifact).
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, posix, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliExitError } from "../../errors/cli-exit-error.js";
+import { ExitCode } from "../../errors/exit-codes.js";
+import { log } from "../../logger.js";
+import { VERSION } from "../../version.js";
+import { runtimesDir } from "../paths.js";
+
+const SEEDPACK_PACKAGE = "@stigmer/seedpack";
+
+/**
+ * The canonical seedpack entries, in apply-safe order. Kept in sync with
+ * `SEEDPACK_ENTRIES` in `@stigmer/seedpack` and the `//go:embed` set in
+ * `seedpack/embed.go` — `tools/`, `icons/`, and `canary/` (CI canary metadata,
+ * not a resource) are deliberately excluded so the content set (and thus the
+ * idempotency hash) is identical across delivery paths.
+ */
+export const SEEDPACK_ENTRIES = [
+  "stigmer.yaml",
+  "organizations",
+  "skills",
+  "agents",
+  "workflows",
+  "mcp-servers",
+] as const;
+
+/** Marker file recording the last successfully-applied content hash. */
+export const MARKER_FILE = ".seedpack-bootstrapped";
+
+export interface SeedpackContent {
+  /** Absolute path to the content root (holds stigmer.yaml). */
+  readonly dir: string;
+  /** Where the content came from — surfaced in diagnostics. */
+  readonly source: "repo" | "package";
+}
+
+export interface ResolveSeedpackOptions {
+  home?: string;
+  /** Release version of @stigmer/seedpack to acquire (defaults to the CLI version). */
+  version?: string;
+  /** npm install implementation (injectable for tests). */
+  install?: (installDir: string, spec: string) => void;
+}
+
+/**
+ * Resolve the seedpack content directory: a repo-tree checkout in dev, else the
+ * on-demand-acquired `@stigmer/seedpack` package. Throws actionable guidance when
+ * acquisition is not possible (non-release build, or a failed/incomplete install).
+ */
+export function resolveSeedpackContent(opts: ResolveSeedpackOptions = {}): SeedpackContent {
+  const repo = repoSeedpackDir();
+  if (repo !== null) return { dir: repo, source: "repo" };
+  return { dir: acquireSeedpack(opts), source: "package" };
+}
+
+/**
+ * Acquire the published `@stigmer/seedpack@<version>` into
+ * ~/.stigmer/runtimes/<version>/ (idempotent) and return its package directory.
+ * The version is pinned to the CLI's own version so system content stays in
+ * lockstep with the control plane it bootstraps.
+ */
+export function acquireSeedpack(opts: ResolveSeedpackOptions = {}): string {
+  const home = opts.home ?? homedir();
+  const version = opts.version ?? VERSION;
+  if (!isAcquirableRelease(version)) {
+    throw new CliExitError(`cannot acquire ${SEEDPACK_PACKAGE} for a non-release build (${version})`, ExitCode.General, [
+      "Run from the repo (the seedpack/ tree is used directly in dev).",
+      "On-demand acquisition is only available for published releases.",
+    ]);
+  }
+
+  const installDir = join(runtimesDir(home), version);
+  const pkgDir = join(installDir, "node_modules", "@stigmer", "seedpack");
+  const marker = join(pkgDir, "stigmer.yaml");
+
+  if (!existsSync(marker)) {
+    log.info(`acquiring ${SEEDPACK_PACKAGE}`, { version, dir: installDir });
+    mkdirSync(installDir, { recursive: true });
+    // A stable package.json root keeps the install deterministic. npm install is
+    // additive and non-pruning, so this prefix is safely shared with the runner.
+    const rootPkg = join(installDir, "package.json");
+    if (!existsSync(rootPkg)) {
+      writeFileSync(rootPkg, `${JSON.stringify({ name: "stigmer-runtime", private: true, version: "0.0.0" }, null, 2)}\n`);
+    }
+    const install = opts.install ?? installSeedpack;
+    install(installDir, `${SEEDPACK_PACKAGE}@${version}`);
+  }
+
+  if (!existsSync(marker)) {
+    throw new CliExitError(`${SEEDPACK_PACKAGE} install did not produce ${marker}`, ExitCode.General, [
+      `Remove ${installDir} and retry.`,
+    ]);
+  }
+  return pkgDir;
+}
+
+// Install the seedpack package into an isolated prefix. Output is inherited so
+// the user sees the one-time download progress.
+function installSeedpack(installDir: string, spec: string): void {
+  try {
+    execFileSync("npm", ["install", spec, "--prefix", installDir, "--omit=dev", "--no-audit", "--no-fund"], {
+      stdio: "inherit",
+    });
+  } catch (err) {
+    throw new CliExitError(`failed to install ${spec}`, ExitCode.General, [
+      `Command: npm install ${spec} --prefix ${installDir}`,
+      "Ensure npm is on PATH and the network is reachable.",
+      String(err),
+    ]);
+  }
+}
+
+/**
+ * Deterministic SHA-256 over the canonical content, identical to
+ * `@stigmer/seedpack`'s `contentHash` (and the Go algorithm): files walked in
+ * lexical order, each contributing its forward-slash relative path, a NUL, and
+ * its bytes. Used as the idempotency marker.
+ */
+export function hashSeedpackContent(dir: string): string {
+  const hash = createHash("sha256");
+  for (const rel of listContentFiles(dir)) {
+    hash.update(rel);
+    hash.update(NUL);
+    hash.update(readFileSync(join(dir, rel)));
+  }
+  return `sha256:${hash.digest("hex").slice(0, 16)}`;
+}
+
+/**
+ * Copy the canonical entries from `srcDir` into `destDir`, producing a clean
+ * Stigmer project the declarative-apply path can process directly (never
+ * carrying build tooling or assets that happen to sit beside the content).
+ */
+export function extractSeedpack(srcDir: string, destDir: string): void {
+  mkdirSync(destDir, { recursive: true });
+  for (const entry of SEEDPACK_ENTRIES) {
+    const src = join(srcDir, entry);
+    if (!existsSync(src)) continue;
+    cpSync(src, join(destDir, entry), { recursive: true });
+  }
+}
+
+const NUL = Uint8Array.of(0);
+
+/** Lexically-sorted, forward-slash relative paths of every file under the canonical entries. */
+export function listContentFiles(root: string): string[] {
+  const files: string[] = [];
+  const walk = (abs: string): void => {
+    for (const dirent of readdirSync(abs, { withFileTypes: true })) {
+      const full = join(abs, dirent.name);
+      if (dirent.isDirectory()) walk(full);
+      else if (dirent.isFile()) files.push(toPosix(relative(root, full)));
+    }
+  };
+  for (const entry of SEEDPACK_ENTRIES) {
+    const abs = join(root, entry);
+    if (!existsSync(abs)) continue;
+    if (statSync(abs).isDirectory()) walk(abs);
+    else files.push(entry);
+  }
+  return files.sort();
+}
+
+/** The stored marker hash for `markerDir`, or null when never applied. */
+export function readMarker(markerDir: string): string | null {
+  try {
+    return readFileSync(join(markerDir, MARKER_FILE), "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Persist the applied content hash so a future run can skip unchanged content. */
+export function writeMarker(markerDir: string, hash: string): void {
+  mkdirSync(markerDir, { recursive: true });
+  writeFileSync(join(markerDir, MARKER_FILE), `${hash}\n`);
+}
+
+function toPosix(p: string): string {
+  return sep === posix.sep ? p : p.split(sep).join(posix.sep);
+}
+
+// A source build reports "0.0.0-dev" and the dev channel stamps "<v>-dev.<stamp>";
+// neither publishes a matching @stigmer/seedpack, so they are not acquirable.
+function isAcquirableRelease(version: string): boolean {
+  return !version.includes("-dev");
+}
+
+// Walk up from this module to a repo root containing seedpack/stigmer.yaml.
+function repoSeedpackDir(): string | null {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 10; i += 1) {
+    const candidate = join(dir, "seedpack");
+    if (existsSync(join(candidate, "stigmer.yaml"))) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}

package/src/local/setup/prompt.ts

@@ -0,0 +1,70 @@
+// Minimal terminal prompts for the setup wizard. Prompts and echoes are written
+// to stderr so stdout stays clean; secret entry switches the TTY to raw mode and
+// suppresses echo so API keys never appear on screen or in scrollback.
+
+import { createInterface } from "node:readline";
+
+/** Ask a yes/no question (default no). Returns true only for an explicit yes. */
+export async function confirm(question: string): Promise<boolean> {
+  const answer = (await promptLine(`${question} [y/N] `)).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+
+/** Read a line from stdin, showing `question` on stderr. */
+export function promptLine(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+/** Read a secret from stdin with echo suppressed (falls back to plain read on a
+ * non-TTY stdin, e.g. piped input). */
+export function promptSecret(question: string): Promise<string> {
+  const stdin = process.stdin;
+  if (stdin.isTTY !== true || typeof stdin.setRawMode !== "function") {
+    return promptLine(`${question}: `);
+  }
+
+  process.stderr.write(`${question}: `);
+  return new Promise((resolve) => {
+    let value = "";
+    stdin.setRawMode(true);
+    stdin.resume();
+
+    const finish = (): void => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.removeListener("data", onData);
+      process.stderr.write("\n");
+      resolve(value);
+    };
+
+    const onData = (chunk: Buffer): void => {
+      const char = chunk.toString("utf8");
+      switch (char) {
+        case "\n":
+        case "\r":
+        case "\u0004": // Ctrl-D
+          finish();
+          break;
+        case "\u0003": // Ctrl-C
+          stdin.setRawMode(false);
+          process.stderr.write("\n");
+          process.exit(130);
+          break;
+        case "\u007f": // Backspace
+        case "\b":
+          value = value.slice(0, -1);
+          break;
+        default:
+          value += char;
+      }
+    };
+
+    stdin.on("data", onData);
+  });
+}

package/src/local/setup/wizard.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import type { Config } from "../../config/config.js";
+import { readLlm } from "../llm-config.js";
+import { applyChoice, buildLlmForChoice } from "./wizard.js";
+
+function config(local?: unknown): Config {
+  return { backend: { type: "local", local } };
+}
+
+describe("buildLlmForChoice", () => {
+  it("applies provider defaults and overrides", () => {
+    expect(buildLlmForChoice("anthropic")).toEqual({ provider: "anthropic", model: "claude-sonnet-4.5" });
+    expect(buildLlmForChoice("anthropic", { apiKey: "k", model: "m" })).toEqual({
+      provider: "anthropic",
+      model: "m",
+      api_key: "k",
+    });
+    expect(buildLlmForChoice("ollama", { baseUrl: "http://host:1" })).toEqual({
+      provider: "ollama",
+      model: "qwen2.5-coder:7b",
+      base_url: "http://host:1",
+    });
+  });
+
+  it("returns undefined for skip (clears config)", () => {
+    expect(buildLlmForChoice("skip")).toBeUndefined();
+  });
+});
+
+describe("applyChoice", () => {
+  it("writes the selection while preserving siblings", () => {
+    const cfg = config({ temporal: { managed: true }, llm: { provider: "openai" } });
+    const updated = applyChoice(cfg, "anthropic", { apiKey: "k" });
+    expect(readLlm(updated)).toEqual({ provider: "anthropic", model: "claude-sonnet-4.5", api_key: "k" });
+    expect((updated.backend.local as { temporal: unknown }).temporal).toEqual({ managed: true });
+  });
+
+  it("skip clears the llm section", () => {
+    const updated = applyChoice(config({ llm: { provider: "openai" } }), "skip");
+    expect(readLlm(updated)).toBeUndefined();
+  });
+});

package/src/local/setup/wizard.ts

@@ -0,0 +1,78 @@
+// LLM provider selection for `stigmer setup`.
+//
+// The decision logic is a pure function (`buildLlmForChoice`) shared by the
+// non-interactive flag path and the interactive menu, so both produce identical
+// config and the rules are unit-testable in isolation. The interactive menu
+// (`runInteractiveWizard`) is a thin shell around it, mirroring the Go wizard's
+// provider list and API-key handling (env var first, then a hidden prompt).
+
+import type { Config } from "../../config/config.js";
+import { type LlmSettings, setLlm, withProviderDefaults } from "../llm-config.js";
+import { promptLine, promptSecret } from "./prompt.js";
+
+export type ProviderChoice = "anthropic" | "openai" | "ollama" | "skip";
+
+export interface SelectionInputs {
+  apiKey?: string;
+  model?: string;
+  baseUrl?: string;
+}
+
+/**
+ * Resolve a provider choice (plus optional overrides) to the LLM settings to
+ * persist. "skip" yields `undefined`, which clears the section.
+ */
+export function buildLlmForChoice(choice: ProviderChoice, inputs: SelectionInputs = {}): LlmSettings | undefined {
+  if (choice === "skip") return undefined;
+  return withProviderDefaults({
+    provider: choice,
+    model: inputs.model,
+    api_key: inputs.apiKey,
+    base_url: inputs.baseUrl,
+  });
+}
+
+/** Apply a provider choice to a config, returning the updated copy. */
+export function applyChoice(config: Config, choice: ProviderChoice, inputs: SelectionInputs = {}): Config {
+  return setLlm(config, buildLlmForChoice(choice, inputs));
+}
+
+/**
+ * Run the interactive provider menu against the current terminal. Returns the
+ * updated config, or `null` if the user aborts. For cloud providers, an API key
+ * already in the environment is used without prompting (matching the Go wizard).
+ */
+export async function runInteractiveWizard(config: Config, env: NodeJS.ProcessEnv = process.env): Promise<Config | null> {
+  process.stderr.write("\nChoose your LLM provider (required for agent execution):\n\n");
+  process.stderr.write("  [1] Anthropic  — Cloud API, best quality (requires API key)\n");
+  process.stderr.write("  [2] OpenAI     — Cloud API (requires API key)\n");
+  process.stderr.write("  [3] Ollama     — Free, local, offline (lower quality output)\n");
+  process.stderr.write("  [4] Skip       — Configure later (agents won't execute)\n\n");
+
+  for (;;) {
+    const choice = (await promptLine("Select [1-4]: ")).trim();
+    switch (choice) {
+      case "1":
+        return applyChoice(config, "anthropic", { apiKey: await resolveCloudKey("anthropic", env) });
+      case "2":
+        return applyChoice(config, "openai", { apiKey: await resolveCloudKey("openai", env) });
+      case "3":
+        return applyChoice(config, "ollama");
+      case "4":
+        return applyChoice(config, "skip");
+      default:
+        process.stderr.write("Invalid choice. Please enter 1, 2, 3, or 4.\n");
+    }
+  }
+}
+
+async function resolveCloudKey(provider: "anthropic" | "openai", env: NodeJS.ProcessEnv): Promise<string | undefined> {
+  const envVar = provider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY";
+  const existing = env[envVar];
+  if (existing) {
+    process.stderr.write(`Using ${envVar} from environment\n`);
+    return undefined; // env var takes precedence; do not persist a copy
+  }
+  const key = (await promptSecret(`Enter your ${provider === "anthropic" ? "Anthropic" : "OpenAI"} API key`)).trim();
+  return key === "" ? undefined : key;
+}

package/src/local/state/health-state.ts

@@ -0,0 +1,55 @@
+// The daemon's health snapshot, written atomically by the supervisor and read
+// by `stigmer status`.
+//
+// It is the single consistent view of every managed component. The supervisor
+// is the only writer; status (and any other reader) only reads. JSON keys are
+// snake_case to match the file the Go daemon writes, so the format is stable
+// across the migration.
+
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+
+export type ComponentLifecycle = "running" | "stopped" | "failed" | "unhealthy";
+
+/** Runtime state of a single managed component. */
+export interface ComponentState {
+  pid: number;
+  state: ComponentLifecycle;
+  started_at: string;
+  restart_count: number;
+  last_error?: string;
+  /** For components that announce readiness (the runner's "polling" marker):
+   * true once observed. Absent for components without a readiness signal. */
+  ready?: boolean;
+}
+
+/** The full snapshot persisted to `health-state.json`. */
+export interface HealthState {
+  daemon_pid: number;
+  started_at: string;
+  components: Record<string, ComponentState>;
+}
+
+/**
+ * Write the health state atomically: serialize to a temp file then rename over
+ * the target, so a reader never observes a half-written snapshot.
+ */
+export function writeHealthState(path: string, state: HealthState): void {
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  renameSync(tmp, path);
+}
+
+/** Load the health state, or null if it is missing or unparseable. */
+export function loadHealthState(path: string): HealthState | null {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(raw) as HealthState;
+  } catch {
+    return null;
+  }
+}

package/src/local/state/index.ts

@@ -0,0 +1,8 @@
+// Public surface of the local-stack state primitives.
+
+export { type ComponentLifecycle, type ComponentState, type HealthState, loadHealthState, writeHealthState } from "./health-state.js";
+export { type FileLock, acquireLock } from "./lock.js";
+export { DEFAULT_LOG_RETENTION_DAYS, cleanupOldLogs, rotateLogs } from "./log-rotation.js";
+export { readPidFile, removePidFile, writePidFile } from "./pidfile.js";
+export { findProcessByPort, isProcessAlive, killProcess, killProcessGroup } from "./proc.js";
+export { type StartupConfig, loadStartupConfig, removeStartupConfig, saveStartupConfig } from "./startup-config.js";

package/src/local/state/lock.ts

@@ -0,0 +1,77 @@
+// A single-instance file lock built on atomic O_EXCL file creation.
+//
+// Node has no portable `flock`, so the lock is a file whose existence is the
+// lock and whose contents are the owning PID. Creation uses the "wx" flag
+// (O_CREAT | O_EXCL), which is atomic on POSIX and Windows, so two racing
+// acquirers cannot both win. If the file already exists we read the owner PID:
+// a dead owner means a stale lock we may reclaim; a live owner means the lock
+// is genuinely held. This guards the Temporal dev server against double-start
+// the way the Go CLI's flock does, without a native dependency.
+
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { isProcessAlive } from "./proc.js";
+
+/** A held lock. Call release() exactly once when done. */
+export interface FileLock {
+  readonly path: string;
+  release(): void;
+}
+
+/**
+ * Try to acquire the lock at `path`. Returns a FileLock on success, or null if
+ * the lock is held by a live process. A lock left behind by a dead process is
+ * reclaimed automatically.
+ */
+export function acquireLock(path: string): FileLock | null {
+  mkdirSync(dirname(path), { recursive: true });
+
+  if (tryCreate(path)) return makeLock(path);
+
+  // The lock file exists. Reclaim it only if its owner is gone.
+  const owner = readOwner(path);
+  if (owner !== null && isProcessAlive(owner)) {
+    return null; // genuinely held by a live process
+  }
+
+  // Stale (or unreadable) lock: remove and retry exactly once. A failure on the
+  // retry means another process raced us to it — treat the lock as held.
+  rmSync(path, { force: true });
+  return tryCreate(path) ? makeLock(path) : null;
+}
+
+function tryCreate(path: string): boolean {
+  try {
+    const fd = openSync(path, "wx");
+    writeFileSync(fd, `${process.pid}\n`, "utf8");
+    closeSync(fd);
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "EEXIST") return false;
+    throw err;
+  }
+}
+
+function readOwner(path: string): number | null {
+  try {
+    const firstLine = readFileSync(path, "utf8").split("\n", 1)[0]?.trim() ?? "";
+    const pid = Number.parseInt(firstLine, 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function makeLock(path: string): FileLock {
+  let released = false;
+  return {
+    path,
+    release(): void {
+      if (released) return;
+      released = true;
+      // Only remove the file if we still own it, so we never delete a lock a
+      // different process acquired after ours was (somehow) gone.
+      if (readOwner(path) === process.pid) rmSync(path, { force: true });
+    },
+  };
+}

package/src/local/state/log-rotation.ts

@@ -0,0 +1,112 @@
+// Log rotation, run once at the start of every `up`.
+//
+// Each non-empty component log is renamed with a timestamp suffix so a fresh
+// run starts clean while the previous run's output is preserved for diagnosis.
+// Archived logs older than the retention window are then pruned. This mirrors
+// the Go CLI's `rotateLogsIfNeeded` + `cleanupOldLogs`.
+
+import { mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** Component log files eligible for rotation. */
+const ROTATABLE_LOGS = [
+  "daemon.log",
+  "stigmer-server.log",
+  "stigmer-server.err",
+  "runner.log",
+  "runner.err",
+  "temporal.log",
+  "llm.log",
+];
+
+/** Default retention for archived logs, in days. */
+export const DEFAULT_LOG_RETENTION_DAYS = 7;
+
+/**
+ * Rotate non-empty component logs in `logDir`, returning the number rotated.
+ * Creates the directory if needed and prunes archives past the retention
+ * window. A clock can be injected for deterministic tests.
+ */
+export function rotateLogs(
+  logDir: string,
+  options: { now?: Date; retentionDays?: number } = {},
+): number {
+  const now = options.now ?? new Date();
+  mkdirSync(logDir, { recursive: true });
+
+  const suffix = timestampSuffix(now);
+  let rotated = 0;
+  for (const name of ROTATABLE_LOGS) {
+    const oldPath = join(logDir, name);
+    let size: number;
+    try {
+      size = statSync(oldPath).size;
+    } catch {
+      continue; // missing log — nothing to rotate
+    }
+    if (size === 0) continue; // empty log — leave it in place
+
+    try {
+      renameSync(oldPath, `${oldPath}.${suffix}`);
+      rotated += 1;
+    } catch {
+      // A rotation failure must not block startup; leave the log and move on.
+    }
+  }
+
+  cleanupOldLogs(logDir, options.retentionDays ?? DEFAULT_LOG_RETENTION_DAYS, now);
+  return rotated;
+}
+
+/**
+ * Delete archived logs (`*.log.*` / `*.err.*`) older than `keepDays`, returning
+ * the count removed.
+ */
+export function cleanupOldLogs(
+  logDir: string,
+  keepDays: number = DEFAULT_LOG_RETENTION_DAYS,
+  now: Date = new Date(),
+): number {
+  const cutoff = now.getTime() - keepDays * 24 * 60 * 60 * 1000;
+  let entries: string[];
+  try {
+    entries = readdirSync(logDir);
+  } catch {
+    return 0;
+  }
+
+  let deleted = 0;
+  for (const entry of entries) {
+    if (!isArchivedLog(entry)) continue;
+    const path = join(logDir, entry);
+    let mtimeMs: number;
+    try {
+      mtimeMs = statSync(path).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (mtimeMs >= cutoff) continue;
+    try {
+      rmSync(path, { force: true });
+      deleted += 1;
+    } catch {
+      // Best-effort cleanup; a stuck file does not fail startup.
+    }
+  }
+  return deleted;
+}
+
+// Archived logs are the rotated copies: a base ending in `.log` or `.err`
+// followed by a timestamp suffix (e.g. `runner.log.2026-06-13-141502`).
+function isArchivedLog(name: string): boolean {
+  return /\.(log|err)\..+$/.test(name);
+}
+
+// Matches the Go layout "2006-01-02-150405" (local time): YYYY-MM-DD-HHmmss.
+function timestampSuffix(date: Date): string {
+  const p = (n: number, width = 2): string => String(n).padStart(width, "0");
+  return (
+    `${date.getFullYear()}-${p(date.getMonth() + 1)}-${p(date.getDate())}-` +
+    `${p(date.getHours())}${p(date.getMinutes())}${p(date.getSeconds())}`
+  );
+}