infinity-harness 2.7.0 → 2.8.1

package/src/core/runState.ts

@@ -0,0 +1,151 @@
+/**
+ * infinity-harness — core/runState.ts (Core owns type + path, Daemon owns writes).
+ *
+ * v2.7's `src/runState.ts` had { armed, runId, startedAt, sessions, stoppedAt, stopReason }.
+ * v3 extends it with: baseModel, tiers (preflight results), budget (byTier UsageTotals + caps).
+ * Existing fields are kept; the file stays `harness/run.json`.
+ *
+ * Core owns the type, the path spelling, and the read helpers used by Interfaces.
+ * Daemon owns the writes (arm, heartbeat, budget, preflight) — but the types
+ * are here so Interfaces and Core can read the same truth without importing
+ * the Daemon.
+ */
+
+import { runStatePath } from "./paths.ts";
+import { readJsonSafe, writeJsonAtomic, removeFile } from "./fsx.ts";
+
+export type ProviderModel = { provider: string; id: string; thinkingLevel?: string };
+
+export type TierPreflight = { provider: string; id: string; preflight: "ok" | "fail"; servedModel?: string; reason?: string };
+
+export type TierResults = Partial<Record<"A" | "B" | "C" | "D" | "X", TierPreflight>>;
+
+export type UsageTotals = { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number; calls: number };
+
+export function createUsageTotals(): UsageTotals {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, calls: 0 };
+}
+
+export type Budget = {
+  byTier: Partial<Record<"A" | "B" | "C" | "D" | "X", UsageTotals>>;
+  cap: { totalTokens?: number | null; costUsd?: number | null; wallClockMs?: number | null };
+  stopOnExhaustion?: boolean;
+};
+
+export type RunState = {
+  armed: boolean;
+  runId: string;
+  startedAt: string;
+  sessions: number;
+  stoppedAt: string | null;
+  stopReason: string | null;
+  /** Captured from ctx.model at arm time. The detached Daemon has no ctx. */
+  baseModel: ProviderModel | null;
+  /** Preflight outcome per tier. A failing tier blocks arming. */
+  tiers: TierResults;
+  /** Per-tier spend and caps. X outside consultation is a defect signal, not a budget. */
+  budget: Budget;
+  wallClockMs?: number;
+  escalation?: { level: string | null; since: string | null };
+};
+
+export function newRunState(runId: string, now = new Date()): RunState {
+  return {
+    armed: true,
+    runId,
+    startedAt: now.toISOString(),
+    sessions: 1,
+    stoppedAt: null,
+    stopReason: null,
+    baseModel: null,
+    tiers: {},
+    budget: { byTier: {}, cap: {}, stopOnExhaustion: true },
+  };
+}
+
+export function loadRunState(targetDir: string): RunState | null {
+  const raw = readJsonSafe<Record<string, unknown> | null>(runStatePath(targetDir), null);
+  if (!raw || typeof raw.runId !== "string" || !raw.runId) return null;
+  const sessions = typeof raw.sessions === "number" && (raw.sessions as number) > 0 ? (raw.sessions as number) : 1;
+  // Back-compat: older file had no baseModel/tiers/budget — treat as null/empty.
+  const baseModel = (() => {
+    const bm = (raw as Record<string, unknown>).baseModel;
+    if (!bm || typeof bm !== "object" || Array.isArray(bm)) return null;
+    const b = bm as Record<string, unknown>;
+    if (typeof b.provider === "string" && typeof b.id === "string") return { provider: String(b.provider), id: String(b.id), ...(typeof b.thinkingLevel === "string" ? { thinkingLevel: b.thinkingLevel } : {}) } as ProviderModel;
+    // legacy: baseModel was a string "provider/id"
+    if (typeof raw.baseModel === "string" && String(raw.baseModel).trim()) {
+      const s = String(raw.baseModel).trim();
+      const parts = s.split("/");
+      if (parts.length >= 2) return { provider: parts[0]!, id: parts.slice(1).join("/") };
+      return { provider: "anthropic", id: s };
+    }
+    return null;
+  })();
+  const tiersRaw = (raw as Record<string, unknown>).tiers;
+  const tiers: TierResults = (tiersRaw && typeof tiersRaw === "object" && !Array.isArray(tiersRaw) ? tiersRaw : {}) as TierResults;
+  const budgetRaw = (raw as Record<string, unknown>).budget;
+  const budget: Budget = (budgetRaw && typeof budgetRaw === "object" && !Array.isArray(budgetRaw)
+    ? budgetRaw as Budget
+    : { byTier: {}, cap: {}, stopOnExhaustion: true });
+  if (!budget.byTier || typeof budget.byTier !== "object") budget.byTier = {};
+  if (!budget.cap || typeof budget.cap !== "object") budget.cap = {};
+  return {
+    armed: raw.armed === true,
+    runId: raw.runId as string,
+    startedAt: typeof raw.startedAt === "string" ? (raw.startedAt as string) : new Date(0).toISOString(),
+    sessions,
+    stoppedAt: typeof raw.stoppedAt === "string" ? (raw.stoppedAt as string) : null,
+    stopReason: typeof raw.stopReason === "string" ? (raw.stopReason as string) : null,
+    baseModel,
+    tiers,
+    budget,
+    ...(typeof (raw as Record<string, unknown>).wallClockMs === "number" ? { wallClockMs: (raw as Record<string, unknown>).wallClockMs as number } : {}),
+    ...(typeof (raw as Record<string, unknown>).escalation === "object" ? { escalation: (raw as Record<string, unknown>).escalation as RunState["escalation"] } : {}),
+  };
+}
+
+export function saveRunState(targetDir: string, state: RunState): void {
+  try { writeJsonAtomic(runStatePath(targetDir), state); } catch { /* run bookkeeping must not kill the session */ }
+}
+
+export function armRun(targetDir: string, runId: string, now = new Date()): RunState {
+  const existing = loadRunState(targetDir);
+  const state = existing && existing.armed ? { ...existing, stoppedAt: null, stopReason: null } : newRunState(runId, now);
+  saveRunState(targetDir, state);
+  return state;
+}
+
+export function disarmRun(targetDir: string, reason: string, now = new Date()): RunState | null {
+  const existing = loadRunState(targetDir);
+  if (!existing) return null;
+  const state: RunState = { ...existing, armed: false, stoppedAt: now.toISOString(), stopReason: reason };
+  saveRunState(targetDir, state);
+  return state;
+}
+
+export function countSession(targetDir: string): RunState | null {
+  const existing = loadRunState(targetDir);
+  if (!existing) return null;
+  const state = { ...existing, sessions: existing.sessions + 1 };
+  saveRunState(targetDir, state);
+  return state;
+}
+
+export function clearRunState(targetDir: string): void {
+  try { removeFile(runStatePath(targetDir)); } catch { /* nothing to clear */ }
+}
+
+export function runIdFor(targetDir: string, fallback: string): string {
+  const state = loadRunState(targetDir);
+  return state && state.armed ? state.runId : fallback;
+}
+
+/** Parse a legacy baseModel string "provider/id" into a ProviderModel. */
+export function parseBaseModelString(s: string | null | undefined): ProviderModel | null {
+  if (!s || !String(s).trim()) return null;
+  const str = String(s).trim();
+  const parts = str.split("/");
+  if (parts.length >= 2) return { provider: parts[0]!, id: parts.slice(1).join("/") };
+  return { provider: "anthropic", id: str };
+}

package/src/core/settings.ts

@@ -188,6 +188,125 @@ export const SETTINGS: SettingsGroup[] = [
         help: "A paused pipeline refuses to advance and stops the continuous run.",
         type: { kind: "boolean" },
       },
+      {
+        path: "pilot",
+        file: "config",
+        label: "Pilot",
+        help: "Run-level preset over per-phase modes. copilot every phase stops, autopilot builds without you, full is hands-off intake->SHIP.",
+        type: { kind: "choice", choices: ["copilot", "autopilot", "full"] },
+      },
+      {
+        path: "tiers.A.provider",
+        file: "config",
+        label: "Tier A provider",
+        help: "Provider for general harness work (orchestration, short-lived A workers).",
+        type: { kind: "text", placeholder: "anthropic", allowEmpty: true },
+      },
+      {
+        path: "tiers.A.id",
+        file: "config",
+        label: "Tier A model",
+        help: "Model id for tier A general work.",
+        type: { kind: "text", placeholder: "claude-sonnet-4-5", allowEmpty: true },
+      },
+      {
+        path: "tiers.B.provider",
+        file: "config",
+        label: "Tier B provider",
+        help: "Provider for easy tasks.",
+        type: { kind: "text", placeholder: "anthropic", allowEmpty: true },
+      },
+      {
+        path: "tiers.B.id",
+        file: "config",
+        label: "Tier B model",
+        help: "Model id for B (easy). Empty means use baseModel X.",
+        type: { kind: "text", placeholder: "claude-sonnet-4-5", allowEmpty: true },
+      },
+      {
+        path: "tiers.C.provider",
+        file: "config",
+        label: "Tier C provider",
+        help: "Provider for moderate tasks.",
+        type: { kind: "text", placeholder: "anthropic", allowEmpty: true },
+      },
+      {
+        path: "tiers.C.id",
+        file: "config",
+        label: "Tier C model",
+        help: "Model id for C (moderate).",
+        type: { kind: "text", placeholder: "claude-opus-4-5", allowEmpty: true },
+      },
+      {
+        path: "tiers.D.provider",
+        file: "config",
+        label: "Tier D provider",
+        help: "Provider for difficult tasks.",
+        type: { kind: "text", placeholder: "anthropic", allowEmpty: true },
+      },
+      {
+        path: "tiers.D.id",
+        file: "config",
+        label: "Tier D model",
+        help: "Model id for D (difficult).",
+        type: { kind: "text", placeholder: "claude-opus-4-5", allowEmpty: true },
+      },
+      {
+        path: "tiers.X.provider",
+        file: "config",
+        label: "Tier X provider",
+        help: "Provider for consultation / escalation (strongest).",
+        type: { kind: "text", placeholder: "anthropic", allowEmpty: true },
+      },
+      {
+        path: "tiers.X.id",
+        file: "config",
+        label: "Tier X model",
+        help: "Model id for X (consultation).",
+        type: { kind: "text", placeholder: "claude-opus-4-5", allowEmpty: true },
+      },
+      {
+        path: "limits.unitWallClockMs",
+        file: "config",
+        label: "Unit wall-clock ms",
+        help: "How long one worker may run before abort + dispose. Default 30m.",
+        type: { kind: "number", min: 60000, max: 7200000, unit: "ms" },
+      },
+      {
+        path: "limits.maxRecycles",
+        file: "config",
+        label: "Max recycles",
+        help: "How many compaction recycles one unit tolerates before stopping. Default 2.",
+        type: { kind: "number", min: 0, max: 10 },
+      },
+      {
+        path: "limits.maxReworkPerUnit",
+        file: "config",
+        label: "Max rework per unit",
+        help: "How many times a unit may go back to rework. Default 2.",
+        type: { kind: "number", min: 0, max: 10 },
+      },
+      {
+        path: "limits.maxReplansPerPhase",
+        file: "config",
+        label: "Max replans per phase",
+        help: "How many plan mutations a phase may have. Default 3.",
+        type: { kind: "number", min: 0, max: 10 },
+      },
+      {
+        path: "limits.tokenCap",
+        file: "config",
+        label: "Token cap",
+        help: "Total tokens before the run stops. Null means unconstrained.",
+        type: { kind: "number", min: 1000, max: 100000000 },
+      },
+      {
+        path: "limits.costCap",
+        file: "config",
+        label: "Cost cap USD",
+        help: "Spend ceiling across A/B/C/D/X. Null means unconstrained.",
+        type: { kind: "number", min: 0, max: 100000 },
+      },
     ],
   },
   {
@@ -388,16 +507,23 @@ export const SETTINGS: SettingsGroup[] = [
         path: "execution.parallelAt",
         file: "config",
         label: "Parallel at",
-        help: "Legacy engine only. The background engine runs one unit at a time, in its own session, at the level you chose for session handoff.",
+        help: "The plan-phase for parallel work. The background engine runs one worker until worktrees land, so this is only the future parallelism knob.",
         type: { kind: "choice", choices: ["off", "goal", "phase", "sprint", "feature", "task", "subtask"] },
       },
       {
         path: "execution.maxWorkers",
         file: "config",
         label: "Max workers",
-        help: "Legacy engine only. The background engine runs one worker; parallel background workers are not wired up yet.",
+        help: "Hard cap on concurrent workers (1..16). Guarded by lock and budget; 1 until worktrees exist. Effective from Daemon.",
         type: { kind: "number", min: 1, max: 16 },
       },
+      {
+        path: "execution.isolation",
+        file: "config",
+        label: "Isolation",
+        help: "How concurrent workers stay out of each others way. none forces maxWorkers=1 and no worktree.",
+        type: { kind: "choice", choices: ["worktree", "none"] },
+      },
     ],
   },
   {
@@ -465,7 +591,7 @@ export const SETTINGS: SettingsGroup[] = [
         path: "gates.antiPlaceholder.enabled",
         file: "config",
         label: "Reject placeholders",
-        help: "Fail the gate on TODO-implement, FIXME, 'not implemented' and friends in source.",
+        help: "Fail the gate when source still has unfinished markers.",
         type: { kind: "boolean" },
       },
     ],
@@ -681,6 +807,7 @@ export function writeSetting(targetDir: string, setting: Setting, value: unknown
 
 /** How a value is shown in the menu. Empty model slots read as inherited. */
 export function formatValue(setting: Setting, value: unknown): string {
+  if (setting.path === "execution.isolation") return typeof value === "string" && value.trim() ? value : "worktree";
   switch (setting.type.kind) {
     case "boolean":
       return value ? "on" : "off";

package/src/core/types.ts

@@ -74,6 +74,22 @@ export type SubtaskStatus = (typeof SUBTASK_STATUSES)[number];
 
 export type Difficulty = "easy" | "moderate" | "difficult";
 
+export type PilotMode = "copilot" | "autopilot" | "full";
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+export type TierSpec = {
+  provider: string;
+  id: string;
+  thinkingLevel?: ThinkingLevel | "";
+};
+
+export type TierId = "A" | "B" | "C" | "D" | "X";
+
+export type TierMap = Partial<Record<TierId, TierSpec>>;
+
+export type ExecutionIsolation = "worktree" | "none";
+
 // ── Feature list (the SSOT on disk) ─────────────────────────────────────────
 
 export type Subtask = {
@@ -95,6 +111,8 @@ export type Task = {
   difficulty?: Difficulty;
   modelHint?: string;
   criteria?: string[];
+  /** When true this task must run alone — whole-tree isolation (lockfile regen, codemod). */
+  serialize?: boolean;
   /** Free-form extras are preserved verbatim on round-trip. */
   [k: string]: unknown;
 };
@@ -185,6 +203,8 @@ export type ExecutionPolicy = {
   parallelAt: HandoffGranularity;
   /** Max parallel workers (1..16). Guarded by lock and budget. */
   maxWorkers: number;
+  /** How concurrent workers stay out of each other's way. */
+  isolation: ExecutionIsolation;
 };
 
 export type ExecutionEngine = "background" | "main-session";
@@ -319,6 +339,19 @@ export type HarnessConfig = {
   workflow: { id: string; name: string } | null;
   display: DisplayPolicy;
   intake: IntakeState;
+  /** Run-level pilot preset over per-phase modes. `full` = hands-off intake→SHIP. */
+  pilot: PilotMode;
+  /** Tier definitions A/B/C/D/X. Each is provider+id+thinking. Empty means use baseModel. */
+  tiers: TierMap;
+  /** Global caps that bound a run. */
+  limits: {
+    unitWallClockMs: number;
+    maxRecycles: number;
+    maxReworkPerUnit: number;
+    maxReplansPerPhase: number;
+    tokenCap: number | null;
+    costCap: number | null;
+  };
   /** Set when a gate passed but the phase needs a human signature first. */
   awaitingApproval: Phase | null;
   /** Budgets that bound an unattended continuous run. See src/loop.ts. */

package/src/daemon/budget.ts

@@ -0,0 +1,94 @@
+/**
+ * infinity-harness — daemon/budget.ts
+ *
+ * Per-tier token+cost accounting. Uses pi's UsageTotals shape.
+ * - `byTier` holds cumulative per-tier spend (one UsageTotals per A/B/C/D/X).
+ * - `cap` is the budget ceiling (costUsd / totalTokens / wallClockMs).
+ * - The X-leak tripwire: X tokens outside a consultation worker are a defect.
+ *
+ * pi reports usage cumulatively per session (last message_end usage IS the
+ * session total, not a delta). So per-session we keep the MAX, and per-tier
+ * we sum finished sessions' totals via addUsageToTotals semantics.
+ */
+
+import type { UsageTotals, Budget, RunState } from "../core/runState.ts";
+import type { TierId } from "../core/types.ts";
+import { createUsageTotals } from "../core/runState.ts";
+
+export type Tier = TierId;
+
+export type Caps = { costUsd?: number | null; totalTokens?: number | null; wallClockMs?: number | null };
+
+export type BudgetState = Budget; // alias for the RunState's budget shape
+
+export function emptyBudget(): Budget {
+  return { byTier: {}, cap: {}, stopOnExhaustion: true };
+}
+
+export function addUsageForTier(budget: Budget, tier: Tier, usage: Partial<UsageTotals> & { input?: number; output?: number; cacheRead?: number; cacheWrite?: number; cost?: number; calls?: number }): void {
+  const byTier = (budget.byTier ??= {});
+  const cur: UsageTotals = byTier[tier] ?? createUsageTotals();
+  cur.input += usage.input ?? 0;
+  cur.output += usage.output ?? 0;
+  cur.cacheRead += usage.cacheRead ?? 0;
+  cur.cacheWrite += usage.cacheWrite ?? 0;
+  cur.cost += usage.cost ?? 0;
+  cur.calls += usage.calls ?? 1;
+  byTier[tier] = cur;
+}
+
+export function totalTokens(budget: Budget): number {
+  let n = 0;
+  for (const u of Object.values(budget.byTier ?? {})) n += (u.input ?? 0) + (u.output ?? 0) + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0);
+  return n;
+}
+
+export function totalCost(budget: Budget): number {
+  let c = 0;
+  for (const u of Object.values(budget.byTier ?? {})) c += u.cost ?? 0;
+  return c;
+}
+
+export function isCapExceeded(budget: Budget): { exceeded: boolean; reason: string | null } {
+  const cap = budget.cap ?? {};
+  const tokens = totalTokens(budget);
+  const cost = totalCost(budget);
+  if (typeof cap.totalTokens === "number" && cap.totalTokens > 0 && tokens >= cap.totalTokens) return { exceeded: true, reason: `token cap ${cap.totalTokens} exceeded (${tokens})` };
+  if (typeof cap.costUsd === "number" && cap.costUsd > 0 && cost >= cap.costUsd) return { exceeded: true, reason: `cost cap $${cap.costUsd} exceeded ($${cost.toFixed(2)})` };
+  return { exceeded: false, reason: null };
+}
+
+/**
+ * X-leak tripwire. True when X has accrued cost/tokens while no consultation
+ * worker is alive. The Daemon treats this as a hard stop with reason.
+ */
+export function hasXLeak(budget: Budget, hasConsultationWorker: boolean): boolean {
+  if (hasConsultationWorker) return false;
+  const x = (budget.byTier as Record<string, UsageTotals | undefined>)["X"];
+  if (!x) return false;
+  return (x.cost ?? 0) > 0 || (x.input ?? 0) + (x.output ?? 0) > 0 || (x.calls ?? 0) > 0;
+}
+
+export function xLeakReason(budget: Budget): string {
+  const x = (budget.byTier as Record<string, UsageTotals | undefined>)["X"];
+  const cost = x?.cost ?? 0;
+  const tokens = (x?.input ?? 0) + (x?.output ?? 0);
+  return `X accrued ${tokens} tokens ($${cost.toFixed(2)}) with no consultation worker — routing leak`;
+}
+
+export function budgetFromRunState(runState: RunState | null): Budget {
+  if (!runState?.budget) return emptyBudget();
+  return runState.budget;
+}
+
+export function budgetSummary(budget: Budget): string {
+  const parts: string[] = [];
+  for (const tier of ["A","B","C","D","X"] as Tier[]) {
+    const u = (budget.byTier as Record<string, UsageTotals | undefined>)[tier];
+    if (!u || (!u.calls && !u.cost && !u.input && !u.output)) continue;
+    parts.push(`${tier}:${u.input}+${u.output} $${(u.cost ?? 0).toFixed(2)} ×${u.calls}`);
+  }
+  const cap = budget.cap ?? {};
+  const capStr = [cap.totalTokens ? `tokens ${cap.totalTokens}` : null, cap.costUsd ? `$${cap.costUsd}` : null].filter(Boolean).join(" / ");
+  return parts.length ? `${parts.join(" | ")}${capStr ? ` — cap ${capStr}` : ""}` : (capStr ? `cap ${capStr}` : "no spend yet");
+}

package/src/daemon/guard.ts

@@ -0,0 +1,113 @@
+/**
+ * infinity-harness — daemon/guard.ts
+ *
+ * Single-owner lock + daemon.json heartbeat + bounded stop.
+ * The Daemon is the single writer; Interfaces are readers. A second pi window
+ * on the same project must become a viewer, not a rival Daemon.
+ *
+ * daemon.json is the trust root: { pid, port, token, startedAt, heartbeatAt, runId }.
+ * Token is a random per-run secret; file is 0600. Server binds 127.0.0.1 only.
+ * Guides: Daemon writes it, liveness is process.kill(pid,0), heartbeat every 20s,
+ * stale after 90s. v2.7 shipped HEARTBEAT_MS/OWNER_STALE_MS at 20s/90s.
+ */
+
+import { randomBytes, randomUUID } from "node:crypto";
+import { existsSync, writeFileSync, readFileSync, chmodSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import { daemonPath } from "../core/paths.ts";
+import { readJsonSafe, writeJsonAtomic, fileExists, ensureDir } from "../core/fsx.ts";
+import { dirname } from "node:path";
+
+export const HEARTBEAT_MS = 20_000;
+export const OWNER_STALE_MS = 90_000;
+
+export type DaemonInfo = {
+  pid: number;
+  port: number;
+  token: string;
+  startedAt: string;
+  heartbeatAt: string;
+  runId: string;
+};
+
+function readDaemonRaw(targetDir: string): DaemonInfo | null {
+  const raw = readJsonSafe<DaemonInfo | null>(daemonPath(targetDir), null);
+  if (!raw || typeof raw.pid !== "number" || !raw.runId) return null;
+  return raw as DaemonInfo;
+}
+
+export function loadDaemon(targetDir: string): DaemonInfo | null {
+  const info = readDaemonRaw(targetDir);
+  if (!info) return null;
+  return info;
+}
+
+export function isDaemonAlive(info: DaemonInfo | null): boolean {
+  if (!info) return false;
+  // Heartbeat stale?
+  const age = Date.now() - new Date(info.heartbeatAt).getTime();
+  if (Number.isFinite(age) && age > OWNER_STALE_MS) {
+    // Also check pid liveness as tiebreaker.
+    try { process.kill(info.pid, 0); return false; } catch { return false; }
+  }
+  try { process.kill(info.pid, 0); return true; } catch { return false; }
+}
+
+export function isDaemonRunning(targetDir: string): boolean {
+  const info = loadDaemon(targetDir);
+  if (!info) return false;
+  return isDaemonAlive(info);
+}
+
+export function writeDaemon(targetDir: string, info: DaemonInfo): void {
+  ensureDir(dirname(daemonPath(targetDir)));
+  writeJsonAtomic(daemonPath(targetDir), info);
+  try { chmodSync(daemonPath(targetDir), 0o600); } catch {}
+}
+
+export function heartbeat(targetDir: string): DaemonInfo | null {
+  const info = loadDaemon(targetDir);
+  if (!info || !isDaemonAlive(info)) return null;
+  const next: DaemonInfo = { ...info, heartbeatAt: new Date().toISOString() };
+  writeDaemon(targetDir, next);
+  return next;
+}
+
+export function clearDaemon(targetDir: string): void {
+  try { if (existsSync(daemonPath(targetDir))) unlinkSync(daemonPath(targetDir)); } catch {}
+}
+
+export function newDaemonInfo(runId: string, port: number): DaemonInfo {
+  return {
+    pid: process.pid,
+    port,
+    token: randomBytes(24).toString("base64url"),
+    startedAt: new Date().toISOString(),
+    heartbeatAt: new Date().toISOString(),
+    runId,
+  };
+}
+
+/**
+ * Guard: refuse to start a second Daemon when one is alive.
+ * Returns null when clear, or the live DaemonInfo when blocked.
+ */
+export function guardSingleOwner(targetDir: string): DaemonInfo | null {
+  const live = loadDaemon(targetDir);
+  if (live && isDaemonAlive(live)) return live;
+  // Stale file — clear it so the next start succeeds.
+  if (live && !isDaemonAlive(live)) clearDaemon(targetDir);
+  return null;
+}
+
+/**
+ * Start heartbeat interval. Returns stop function.
+ */
+export function startHeartbeat(targetDir: string): () => void {
+  const timer = setInterval(() => {
+    try { heartbeat(targetDir); } catch {}
+  }, HEARTBEAT_MS);
+  // Don't keep process alive just for heartbeat if nothing else is running.
+  if (typeof (timer as NodeJS.Timeout & { unref?: () => void }).unref === "function") (timer as unknown as { unref: () => void }).unref();
+  return () => clearInterval(timer);
+}