omp-conductor 0.15.10 → 0.15.12

package/src/escalate.ts

@@ -20,12 +20,12 @@
  * those strings end up in daemon logs and, on the fallback path, in a public
  * issue comment.
  */
-import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
 import { availabilityOpen, interruptDisposition, type InterruptDisposition } from "./availability.ts";
+import { heldNoticeId } from "./notices.ts";
 import type { OrchestratorHandle } from "./orchestrator.ts";
 import type { Escalation, ProjectConfig, Store, Tracker } from "./types.ts";
 
@@ -240,7 +240,7 @@ export function createEscalator(
         }
         if (disposition !== "interrupt") {
           store.addHeldNotice({
-            id: createHash("sha256").update(`held-notice\0${key}`).digest("hex"),
+            id: heldNoticeId(key),
             project: p.name,
             category,
             summary: e.summary,

package/src/failure-class.ts

@@ -15,7 +15,7 @@
  * green test per class" possible without a daemon, a tracker or a network.
  */
 
-import type { FailureClass, RecoveryAction, RunRecord } from "./types.ts";
+import type { Caps, FailureClass, RecoveryAction, RunRecord } from "./types.ts";
 
 /** Facts the caller fetched, each only for the rows that need it. */
 export interface ClassifyFacts {
@@ -222,7 +222,32 @@ export function dispatchInfra(
 // front of the thrown message, so a bare /^git / would never match a real row.
 const DISPATCH_GIT_ERROR = /^(?:Error: )?git .+ exited \d+/s;
 
-export function classifyRun(run: RunRecord, facts: ClassifyFacts): Classification {
+/** The prefix the draining/restarting process writes to a run it killed. */
+const ADMIN_RESTART_MARKER = "admin restart:";
+
+/**
+ * The actor a draining restart recorded on a run it killed, or `undefined`
+ * when the row carries no such attribution. Read from `lastError` for the
+ * same reason {@link dispatchInfra} is read from it: it is the one surface a
+ * run's own row already persists, and the restarting process writes it the
+ * way `recordOperatorStop` writes "operator stopped: …". Recognised as an
+ * administrative kill, never a charging failure, because nothing the worker
+ * did ended it — #512's gap was that a killed session left no attribution.
+ */
+export function adminRestartAttribution(lastError: string | undefined): string | undefined {
+  if (lastError === undefined) return undefined;
+  const marker = lastError.indexOf(ADMIN_RESTART_MARKER);
+  if (marker === -1) return undefined;
+  const firstLine = lastError.slice(marker + ADMIN_RESTART_MARKER.length).trim().split("\n")[0];
+  if (firstLine === undefined || firstLine.trim() === "") return undefined;
+  return firstLine.trim();
+}
+
+export function classifyRun(
+  run: RunRecord,
+  facts: ClassifyFacts,
+  caps?: Pick<Caps, "workerWallClockMs">,
+): Classification {
   const hasArtifacts = run.prUrl !== undefined || run.headSha !== undefined || run.salvageSha !== undefined;
   const providerError =
     facts.sessionError ?? (run.lastError === undefined ? undefined : { message: run.lastError });
@@ -296,6 +321,22 @@ export function classifyRun(run: RunRecord, facts: ClassifyFacts): Classificatio
     }
   }
 
+  // A run the draining/restarting process attributed before it restarted the
+  // session host: killed under its own ceilings by an administrative action,
+  // not by anything the worker did. Costs no budget and requeues, naming the
+  // actor (#512). A killed session used to leave no attribution and fell
+  // through to `unknown`, charging a failure for an operator's restart.
+  if (run.state === "failed" || run.state === "killed") {
+    const actor = adminRestartAttribution(run.lastError);
+    if (actor !== undefined) {
+      return {
+        cls: "admin-kill",
+        recovery: "requeue",
+        evidence: `killed by an administrative restart (${actor}) — an operator's restart, not the run's work`,
+      };
+    }
+  }
+
   if (run.state === "blocked") {
     return {
       cls: "question",
@@ -337,7 +378,29 @@ export function classifyRun(run: RunRecord, facts: ClassifyFacts): Classificatio
             evidence: `turns ${run.turns}/${run.maxTurns}, no PR, no commits — $${run.spendUsd.toFixed(2)} spent`,
           };
     }
-    // Below its own ceiling, so nothing this worker did ended it: a daemon
+    // A run killed at the wall-clock cap is a cap kill too, even though its
+    // turns ceiling never tripped — the harness would have kept burning a
+    // worker slot until the ticks ran out (#490). The same split as the turns
+    // path: artifacts mean the next attempt resumes from real work; nothing to
+    // show means a human re-scopes, naming the time and spend consumed.
+    const wallClockCap = caps?.workerWallClockMs;
+    const wallClockElapsed =
+      run.endedAt === undefined ? undefined : run.endedAt - run.startedAt;
+    if (wallClockCap !== undefined && wallClockElapsed !== undefined && wallClockElapsed >= wallClockCap) {
+      const clock = `${Math.round(wallClockElapsed / 60_000)}m of ${Math.round(wallClockCap / 60_000)}m`;
+      return hasArtifacts
+        ? {
+            cls: "wall-clock-cap-progress",
+            recovery: "continue",
+            evidence: `wall clock ${clock} with work to continue from (${run.prUrl ?? run.salvageSha ?? run.headSha})`,
+          }
+        : {
+            cls: "wall-clock-cap-spinning",
+            recovery: "escalate",
+            evidence: `wall clock ${clock}, no PR, no commits — $${run.spendUsd.toFixed(2)} spent`,
+          };
+    }
+    // Below its own ceilings, so nothing this worker did ended it: a daemon
     // restart, a drain, an operator. Costs no budget and needs no human.
     return {
       cls: "admin-kill",

package/src/fleet.ts

@@ -29,6 +29,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { formatZonedMinute } from "./availability.ts";
 import { findProject, loadConfig, stateDir } from "./config.ts";
+import { clearArmChallenge, recordArmChallenge } from "./arm-challenge.ts";
 import { resolveProjectTopicId, sendTelegram } from "./escalate.ts";
 import { planUsageLine, readPlanUsage, sharedUsageSource } from "./usage.ts";
 import { readApprovalSurface, readDaemonProfile } from "./approval-surface.ts";
@@ -250,6 +251,18 @@ function armGate(projectName?: string): { path: string; named?: string } {
   return named === undefined ? { path } : { path, named };
 }
 
+/**
+ * This project's current tick-arm verdict — the marker the heartbeat reads,
+ * returned with the path that carries it so a verb can report what actually
+ * remains. Read-only: the same decision `disarm` takes, so control and status
+ * about one fleet cannot disagree (a verb telling the operator to re-arm a
+ * fleet that is already armed is the defect #375 removes).
+ */
+export function armState(projectName?: string): { path: string; armed: boolean } {
+  const { path, named } = armGate(projectName);
+  return { path, armed: resolveArmState(path, named).armed };
+}
+
 /**
  * Clears the arm gate for this project — and `wasArmed` is the gate the
  * heartbeat reads, not merely one file's presence.
@@ -362,23 +375,34 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
   }
 
   const send = deps.sendChallenge ?? sendTelegramMessage;
+  const timeoutMs = deps.timeoutMs ?? ARM_CHALLENGE_TIMEOUT_MS;
   // Read before the send, not after: a transcript untouched since this instant
   // cannot contain the reply, and that is what the waiter filters on.
   const sentAt = (deps.now ?? Date.now)();
+  // The orchestrator must be able to classify the reply as an *active* arming
+  // proof for as long as this handshake is live, so the authenticated record
+  // (hash + expiry, never the code) is written before the challenge goes out
+  // and cleared the moment this end settles (#415).
+  recordArmChallenge(named, code, sentAt + timeoutMs);
   try {
     await send(token, channel.owner, text, topicId);
   } catch (err) {
+    // The challenge never went out, so it must not linger as a classifiable
+    // proof either.
+    clearArmChallenge(named);
     throw new Error(
       `arm: outbound sendMessage failed — NOT armed: ${err instanceof Error ? err.message : String(err)}`,
     );
   }
 
-  const timeoutMs = deps.timeoutMs ?? ARM_CHALLENGE_TIMEOUT_MS;
   const injected = deps.waitForUserTurn;
   const scan: SessionScan = injected
     ? { seen: await injected(dir, code, sentAt, timeoutMs), scanned: [], ignored: [] }
     : await waitForChallengeInSessions(dir, code, sentAt, timeoutMs, deps);
   if (!scan.seen) {
+    // The proof missed its window: a lookalike reply must not stay classifiable
+    // after arming gave up, so the record is cleared before the failure lands.
+    clearArmChallenge(named);
     const listing = [
       `session dir: ${dir}`,
       ...scan.scanned.map((f) => `  watched: ${f}`),
@@ -402,6 +426,10 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
   // marker that re-arms the fleet, and turn into a meaningless legacy warning
   // the moment a second project is configured.
   if (arm.legacy === "honoured") rmSync(legacyArmedMarkerPath(), { force: true });
+  // The transcript proof landed and this project is armed: the record has done
+  // its job. A stale record would also keep a later unsolicited lookalike alive
+  // longer than the fresh challenge it was cut for.
+  clearArmChallenge(named);
   return { path, alreadyArmed, owner: channel.owner, challenge: code };
 }
 
@@ -1393,6 +1421,7 @@ export function formatFleetStatus(
   decisions: string | undefined = undefined,
   failureClasses: string | undefined = undefined,
   workerPhases: ReadonlyMap<number, WorkerPausePhase> = new Map(),
+  intake: string | undefined = undefined,
 ): string {
   const tickLine =
     layers.ticksDetail === undefined
@@ -1473,6 +1502,7 @@ export function formatFleetStatus(
     ...(brief === undefined ? [] : [brief]),
     ...(decisions === undefined ? [] : [decisions]),
     ...(failureClasses === undefined ? [] : [failureClasses]),
+    ...(intake === undefined ? [] : [intake]),
     ...(graphBlock === undefined ? [] : [graphBlock]),
     daemonBlock,
     "",
@@ -1656,6 +1686,7 @@ export async function renderStatus(projectName?: string): Promise<string> {
     decisionStatusLine(project.name),
     failureClassBlock(project.name),
     workerPhases,
+    intakeStatusLine(project.name),
   );
 }
 
@@ -1734,6 +1765,32 @@ function decisionStatusLine(projectName: string): string | undefined {
   }
 }
 
+/**
+ * One line naming how many raw ideas are still pending (#299), or nothing when
+ * there are none.
+ *
+ * Deliberately absent at zero, unlike the decision line: an empty intake is the
+ * common state of a healthy fleet, and a row that prints "0 pending" every
+ * status would be permanent noise. Only a nonzero backlog is news, exactly like
+ * {@link failureClassBlock}. Omitted on any throw, like the other optional rows.
+ * Exported so the conditional is testable against a real store.
+ */
+export function intakeStatusLine(projectName: string): string | undefined {
+  const path = dbPath();
+  if (!existsSync(path)) return undefined;
+  let store: Store | undefined;
+  try {
+    store = openStore(path);
+    const pending = store.pendingIntake(projectName);
+    if (pending.length === 0) return undefined;
+    return `intake    ${pending.length} pending idea(s) — omp-conductor intake list`;
+  } catch {
+    return undefined;
+  } finally {
+    store?.close();
+  }
+}
+
 // ---------------------------------------------------------------------------
 // arm proof helpers
 // ---------------------------------------------------------------------------

package/src/gitops.ts

@@ -17,6 +17,7 @@
  * branch cannot disagree.
  */
 
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 
 import { parseChainSource, type ChainEntry } from "./chain-check.ts";
@@ -321,3 +322,159 @@ export async function readBaseChain(
     return { ok: false, stderr: err instanceof Error ? err.message : String(err) };
   }
 }
+
+// ------------------------------------------- the shared-host critical-base guard
+
+/**
+ * The stale-base admission verdict (#428): whether a preserved continuation
+ * branch may be reattached at all, once a project marks a base commit as
+ * critical. Fail closed — a branch that cannot be *proven* to contain every
+ * marker is refused.
+ */
+export type CriticalBaseVerdict =
+  /** No preserved branch for this issue in the mirror — a clean first attempt. */
+  | { state: "no-branch" }
+  /** The reattach source contains every configured marker. */
+  | { state: "fresh" }
+  /** The reattach source predates a marker and cannot be safely advanced to it,
+   *  so the dispatcher must not reattach it. `range` names the base commits
+   *  the branch has not absorbed, for the hold's recovery wording. */
+  | { state: "stale"; marker: string; range: string[] }
+  /** The marker could not be verified at all (unresolvable, fetch failed). */
+  | { state: "unknown"; error: string };
+
+/** The stubborn-session view of the probe, injectable for deterministic tests. */
+export type CriticalBaseProbe = (
+  repo: RepoTarget,
+  markers: readonly string[],
+  branch: string,
+) => Promise<CriticalBaseVerdict>;
+
+/** The bounded sample of base commits a held branch is missing. */
+const CRITICAL_BASE_RANGE_MAX = 8;
+
+/**
+ * Answer whether the preserved branch {@link addRunRepo} would reattach
+ * contains every configured critical-base marker (#428). A base safety fix
+ * protects only branches forked after it landed; a continuation forked before
+ * it still carries the dangerous code, and re-running the lifecycle suite it
+ * retains on a shared host is what SIGTERMed the production daemon.
+ *
+ * The reattach source is the mirror's `refs/heads/<branch>`. When it lacks a
+ * marker but the live remote branch now carries it and the reattach source is
+ * that live head's ancestor, the operator advanced the branch on GitHub (e.g.
+ * merged base into the PR branch): the fast-forward is folded into the mirror
+ * — safe and work-preserving, the same reconcile `pushRunBranch` performs —
+ * and the marker is accepted. Judged against the reattach source, never the
+ * live head alone, so a stale local copy cannot smuggle pre-fix code back in.
+ */
+export async function probeCriticalBase(
+  project: Pick<ProjectConfig, "mirrorRoot">,
+  repo: RepoTarget,
+  branch: string,
+  markers: readonly string[],
+  exec: Exec = spawnCaptured,
+): Promise<CriticalBaseVerdict> {
+  const mirror = mirrorPath(project, repo);
+  // A mirror is where preserved branches live; without one there is nothing to
+  // reattach. Judged "no branch" rather than "unknown" so a fleet that has not
+  // yet created a mirror is not deadlocked at admission.
+  if (!existsSync(mirror)) return { state: "no-branch" };
+  const branchRef = `refs/heads/${branch}`;
+  const env = credentialedEnv();
+
+  const present = await exec(
+    ["git", "--git-dir", mirror, "show-ref", "--verify", "--quiet", branchRef],
+    { env },
+  );
+  if (present.code !== 0) return { state: "no-branch" };
+
+  // The configured marker is a commit that landed on base, so base has to be
+  // resolvable to prove anything about the branch against it. Fetch today's
+  // base tip into the mirror's tracking refs first, so the judgement is against
+  // the current base rather than whatever a run last left behind.
+  const baseRef = `refs/remotes/origin/${repo.defaultBranch}`;
+  const fetched = await exec(
+    ["git", "--git-dir", mirror, "fetch", "--no-tags", "origin", `+refs/heads/${repo.defaultBranch}:${baseRef}`],
+    { env },
+  );
+  if (fetched.code !== 0) {
+    return {
+      state: "unknown",
+      error: scrubUserinfo(fetched.stderr.trim() || fetched.stdout.trim() || `git fetch exited ${String(fetched.code)}`),
+    };
+  }
+
+  for (const marker of markers) {
+    const resolved = await exec(
+      ["git", "--git-dir", mirror, "rev-parse", "--verify", `${marker}^{commit}`],
+      { env },
+    );
+    if (resolved.code !== 0) {
+      return {
+        state: "unknown",
+        error: `critical-base marker "${marker}" is not resolvable in the ${repo.name} mirror`,
+      };
+    }
+    const markerSha = resolved.stdout.trim();
+    if (markerSha === "") {
+      return { state: "unknown", error: `critical-base marker "${marker}" resolved to no commit` };
+    }
+
+    const localHas = await exec(
+      ["git", "--git-dir", mirror, "merge-base", "--is-ancestor", markerSha, branchRef],
+      { env },
+    );
+    if (localHas.code === 0) continue;
+
+    // The reattach source lacks the marker. If the live branch now carries it
+    // and the reattach source is its ancestor, the operator advanced the branch
+    // on GitHub (e.g. merged base into the PR branch): fold that fast-forward
+    // into the reattach source — safe, work-preserving — and accept the marker.
+    const tracked = `refs/remotes/origin/${branch}`;
+    const liveFetched = await exec(
+      ["git", "--git-dir", mirror, "fetch", "--no-tags", "origin", `+refs/heads/${branch}:${tracked}`],
+      { env },
+    );
+    if (liveFetched.code !== 0) {
+      return {
+        state: "unknown",
+        error: scrubUserinfo(liveFetched.stderr.trim() || liveFetched.stdout.trim() || `git fetch ${branch} exited ${String(liveFetched.code)}`),
+      };
+    }
+    const liveHas = await exec(
+      ["git", "--git-dir", mirror, "merge-base", "--is-ancestor", markerSha, tracked],
+      { env },
+    );
+    if (liveHas.code === 0) {
+      const localIsAncestor = await exec(
+        ["git", "--git-dir", mirror, "merge-base", "--is-ancestor", branchRef, tracked],
+        { env },
+      );
+      if (localIsAncestor.code === 0) {
+        await exec(["git", "--git-dir", mirror, "fetch", "--no-tags", "origin", `+${branchRef}:${branchRef}`], { env });
+        continue;
+      }
+    }
+
+    // Predates the marker and cannot be safely advanced to it. Name the base
+    // commits the branch has not absorbed so the hold's recovery is concrete.
+    const range: string[] = [];
+    const missing = await exec(
+      ["git", "--git-dir", mirror, "log", "--oneline", "--format=%h", `${branchRef}..${baseRef}`],
+      { env },
+    );
+    if (missing.code === 0) {
+      range.push(
+        ...missing.stdout
+          .trim()
+          .split("\n")
+          .filter((line) => line.length > 0)
+          .slice(0, CRITICAL_BASE_RANGE_MAX),
+      );
+    }
+    return { state: "stale", marker: markerSha, range };
+  }
+
+  return { state: "fresh" };
+}

package/src/graph-health.ts

@@ -264,7 +264,7 @@ export async function probeCodeGraph(
   const repos: CodeGraphRepoHealth[] = configured.map((repo) => {
     const clone: CheckState = deps.exists(repo.graphProject) ? "present" : "missing";
     const index: CheckState = roots === undefined ? "unknown" : roots.has(repo.graphProject) ? "present" : "missing";
-    if (clone === "missing") reasons.push(`${repo.name}: configured clone is missing`);
+    if (clone === "missing") reasons.push(`${repo.name}: no code-graph clone at ${repo.graphProject}; run \`omp-conductor setup graph\``);
     if (index === "missing") reasons.push(`${repo.name}: no indexed project exactly matches ${repo.graphProject}`);
     return { name: repo.name, path: repo.graphProject, clone, index };
   });

package/src/label-projection.ts

@@ -90,4 +90,4 @@ export async function projectLabels(
     if (!progressed) break;
   }
   return { applied, deferred };
-}
+}

package/src/lifecycle.ts

@@ -66,6 +66,18 @@ const LOG_TAIL_BYTES = 4_096;
 export function runtimeDir(): string {
   const override = process.env["OMP_CONDUCTOR_RUNTIME_DIR"];
   if (override !== undefined && override.length > 0) return override;
+  if (process.env["NODE_ENV"] === "test") {
+    // A test process must never read the host-global runtime dir: doing so
+    // names the real installed daemon's pid, and a test `stop` that inherits
+    // that record would signal — and stop — production's own unit (#399).
+    // Fail closed: a lifecycle test that omitted OMP_CONDUCTOR_RUNTIME_DIR
+    // (the runtime half of the test lifecycle seam) gets a loud error rather
+    // than a silent read of the operator's pidfile.
+    throw new Error(
+      "OMP_CONDUCTOR_RUNTIME_DIR must be set under NODE_ENV=test — " +
+        "refusing to read the host runtime directory (~/.omp/run/daemons/omp-conductor) from a test process",
+    );
+  }
   return join(homedir(), ".omp", "run", "daemons", "omp-conductor");
 }
 
@@ -178,6 +190,152 @@ export function livingDaemon(): DaemonRecord | undefined {
   return undefined;
 }
 
+/**
+ * The `daemon --once` lease file, one per process. Created `O_EXCL` so two
+ * simultaneous `--once` runs cannot both win ownership, and it names the
+ * holder's pid so a stale file (holder died) is removable rather than a
+ * permanent lock.
+ *
+ * The pidfile (`daemon.json`) is what makes this process *visible* as the owner
+ * for the duration of the tick (`status`, `worker stop`, a concurrent `daemon`
+ * start, orphan reconciliation all probe it); the lease file is what makes
+ * ownership *exclusive* — it is the thing that lets two simultaneous `--once`
+ * processes serialise, which the pidfile alone cannot (each would just
+ * overwrite it). They are deliberately two files: the lease is never the
+ * daemon record, so a short-lived drill can never impersonate or clear the
+ * managed daemon's record by virtue of holding a lock.
+ */
+function onceLeasePath(): string {
+  return join(runtimeDir(), "once.lock");
+}
+
+interface OnceLeaseHolder {
+  pid: number;
+  startedAt: number;
+}
+
+/** Parses the lease file; garbage is the same answer as absence — "not held". */
+function readOnceLeaseHolder(): OnceLeaseHolder | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(onceLeasePath(), "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const pid = Reflect.get(parsed, "pid");
+  const startedAt = Reflect.get(parsed, "startedAt");
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 1) return undefined;
+  if (typeof startedAt !== "number" || !Number.isFinite(startedAt)) return undefined;
+  return { pid, startedAt };
+}
+
+/** Bounded attempts to clear a stale lease and re-acquire it. */
+const ONCE_LEASE_RETRIES = 3;
+
+/** A once tick has no log file of its own; the record's field is informational. */
+const ONCE_RECORD_LOG = "<once tick — no daemon log>";
+
+export interface OnceLease {
+  /** The owned record that makes this process the visible daemon for the tick. */
+  record: DaemonRecord;
+  /**
+   * Drops exclusivity — but only while it is still ours. A manager that
+   * claimed the record mid-tick must be left alone: clearing it would clear
+   * somebody else's daemon.
+   */
+  release(): void;
+}
+
+export type OnceLeaseAcquire = { ok: true; lease: OnceLease } | { ok: false; pid: number };
+
+/**
+ * Acquires the exclusive daemon/state ownership a `--once` tick must hold for
+ * its whole lifecycle (#431). A drill is still a dispatcher — it settles rows,
+ * projects labels, admits and launches workers — so it takes the same
+ * ownership the long-running dispatcher holds via the pidfile, and refuses
+ * (having done nothing) while a live daemon owns the record or another live
+ * `--once` holds the lease.
+ *
+ * Returns `{ ok: false, pid }` — having performed no mutation — when another
+ * live process owns the project/state. A stale lease and a stale record whose
+ * holder died are cleared and retried. On success the process both holds the
+ * exclusive lease file and has published itself as the daemon owner, so every
+ * ownership probe (`livingDaemon`, a `daemon` start, a second `--once`) sees
+ * this process for the whole tick.
+ */
+export function acquireOnceLease(
+  o: { port?: number; project?: string; logFile?: string } = {},
+): OnceLeaseAcquire {
+  // A live dispatcher already owns the shared record. Never run beside it.
+  const daemon = livingDaemon();
+  if (daemon !== undefined && daemon.pid !== process.pid) {
+    return { ok: false, pid: daemon.pid };
+  }
+
+  const dir = ensureRuntimeDir();
+  const path = onceLeasePath();
+
+  for (let attempt = 0; attempt < ONCE_LEASE_RETRIES; attempt++) {
+    let created = false;
+    try {
+      const fd = openSync(path, "wx", 0o600);
+      writeFileSync(fd, `${JSON.stringify({ pid: process.pid, startedAt: Date.now() })}\n`);
+      closeSync(fd);
+      created = true;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+      const holder = readOnceLeaseHolder();
+      if (holder !== undefined && isAlive(holder.pid)) {
+        // A live holder — another `--once` (or a process still finishing one).
+        return { ok: false, pid: holder.pid };
+      }
+      // Stale or unreadable holder: clear it and try once more.
+      rmSync(path, { force: true });
+      continue;
+    }
+    if (!created) continue;
+
+    const record: DaemonRecord = {
+      pid: process.pid,
+      port: o.port ?? DEFAULT_PORT,
+      startedAt: Date.now(),
+      logFile: o.logFile ?? ONCE_RECORD_LOG,
+      ...(o.project === undefined ? {} : { project: o.project }),
+    };
+    try {
+      writeRecord(record);
+    } catch (err) {
+      rmSync(path, { force: true });
+      throw err;
+    }
+
+    // Confirm we still own the shared record: a manager may have claimed it in
+    // the instant between our lease create and our record write.
+    const current = readRecord();
+    if (current !== undefined && current.pid === process.pid) {
+      return {
+        ok: true,
+        lease: {
+          record,
+          release: () => {
+            const owned = readRecord();
+            if (owned !== undefined && owned.pid === process.pid) clearRecord();
+            const holder = readOnceLeaseHolder();
+            if (holder !== undefined && holder.pid === process.pid) {
+              rmSync(path, { force: true });
+            }
+          },
+        },
+      };
+    }
+    rmSync(path, { force: true });
+    return { ok: false, pid: current?.pid ?? process.pid };
+  }
+
+  throw new Error("could not acquire the daemon lease — a stale holder kept reappearing");
+}
+
 /**
  * Probes the daemon's own health endpoint. Never throws: a refused connection,
  * a DNS-less host, a hung socket and a 500 are all just "not healthy", and the
@@ -892,8 +1050,17 @@ async function terminate(pid: number, timeoutMs: number): Promise<boolean> {
   return !isAlive(pid);
 }
 
-/** Sends a signal, treating "already gone" as success. Returns false if the send failed. */
-function signal(pid: number, sig: NodeJS.Signals): boolean {
+/** Whether a raw signal should be delivered to a pid. */
+export type SignalFn = (pid: number, sig: NodeJS.Signals) => boolean;
+
+/**
+ * The default signal sender. Production reaches the real `kill`. Under
+ * NODE_ENV=test it dispatches to the fail-closed refusal instead: a test
+ * process must never signal a pid it did not explicitly authorise, and the
+ * default authorises nothing (#399).
+ */
+function defaultSignal(pid: number, sig: NodeJS.Signals): boolean {
+  if (process.env["NODE_ENV"] === "test") return testSignal(pid, sig);
   try {
     process.kill(pid, sig);
     return true;
@@ -902,6 +1069,35 @@ function signal(pid: number, sig: NodeJS.Signals): boolean {
   }
 }
 
+/**
+ * Child-process CLI tests cannot inject {@link setSignalForTest}. Under
+ * NODE_ENV=test they therefore get a refusal: a test process may only signal
+ * a pid its own code explicitly authorised, and a child has authorised none.
+ * Without this, a child `stop` that reads the operator's real daemon.json
+ * (an *inherited* runtime record) would SIGTERM the installed daemon — the
+ * #399 incident.
+ */
+function testSignal(_pid: number, _sig: NodeJS.Signals): boolean {
+  return false;
+}
+
+let signalFn: SignalFn = defaultSignal;
+
+/**
+ * Test-only: replace the raw signal sender. Pass `undefined` to restore.
+ * A test that intentionally spawned a helper may authorise signals to exactly
+ * that helper pid; every other pid is refused. Ownership is never inferred
+ * from writing a record — a pidfile fixture authorises nothing (#399).
+ */
+export function setSignalForTest(fn: SignalFn | undefined): void {
+  signalFn = fn ?? defaultSignal;
+}
+
+/** Sends a signal, treating "already gone" as success. Returns false if the send failed. */
+function signal(pid: number, sig: NodeJS.Signals): boolean {
+  return signalFn(pid, sig);
+}
+
 /**
  * The tail of the daemon log, formatted for an error message. Reads the last
  * few KB by offset rather than the whole file, because the log is append-only