@lyupro/codex-bridge 0.3.0 → 0.4.0

package/scripts/check-file-size.mjs

@@ -13,7 +13,7 @@
  * error mode, 2 internal error (config missing/malformed, or an exclude entry has no
  * matching exclusionRationale).
  *
- * Every exclude entry is classified as either a "pattern" (contains a `*`, sweeps a
+ * Every exclude entry is classified as either a "pattern" (contains a `*`, covers a
  * whole category — e.g. `**\/node_modules/**`) or a "specific path" (no `*`, names one
  * file). Specific paths must carry an exclusionRationale entry; patterns are exempt. This
  * is the structural guard against silently hiding a file in exclude without saying why.
@@ -21,6 +21,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { readJsonFile } from '../src/json-file.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const REPO_ROOT = path.resolve(HERE, '..');
@@ -31,17 +32,14 @@ const VALID_MODES = ['error', 'warning'];
 
 /** Reads and structurally validates .file-size-limit.json. Throws on anything wrong. */
 export async function loadConfig(configPath = CONFIG_PATH) {
-  let raw;
-  try {
-    raw = await fs.readFile(configPath, 'utf8');
-  } catch (err) {
-    throw new Error(`cannot read ${configPath}: ${err.message}`);
-  }
   let parsed;
   try {
-    parsed = JSON.parse(raw);
+    parsed = await readJsonFile(configPath);
   } catch (err) {
-    throw new Error(`${configPath} is not valid JSON: ${err.message}`);
+    if (err.cause) {
+      throw new Error(`${configPath} is not valid JSON: ${err.cause.message}`, { cause: err.cause });
+    }
+    throw new Error(`cannot read ${configPath}: ${err.message}`);
   }
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
     throw new Error(`${configPath} must contain a JSON object`);
@@ -69,7 +67,7 @@ export async function loadConfig(configPath = CONFIG_PATH) {
   return parsed;
 }
 
-/** A pattern (contains `*`) sweeps a category; a specific path (no `*`) names one file. */
+/** A pattern (contains `*`) covers a category; a specific path (no `*`) names one file. */
 export function isSpecificExclude(entry) {
   return !entry.includes('*');
 }

package/src/agents/codex-build.md

@@ -28,6 +28,8 @@ job is to report the run status honestly, including failure.
 
 - The task statement: what to change and the completion criteria.
 - The path to the repository. If none is given, use the current working directory.
+- Scope patterns are globs relative to the repository root. A pattern that matches nothing there is
+  refused before the run starts; a file this task is meant to create is declared with `--scope-new`.
 - Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
   `order id` as `--order-id`, `scope` as `--scope`. Never invent a value, never edit one, never
   reuse an order id from another order — the runner chains runs by that label, and a made-up label

package/src/agents/codex-review.md

@@ -27,6 +27,8 @@ opinion, not a verdict.
   - branch against base — `--mode base:<branch>`;
   - specific commit — `--mode commit:<sha>`.
 - The path to the repository. If none is given, use the current working directory.
+- Scope patterns are globs relative to the repository root. A pattern that matches nothing there is
+  refused before the run starts.
 - Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
   `order id` as `--order-id`. Never invent a value, never edit one, never reuse an order id from
   another order — the runner chains runs by that label, and a made-up label is how a repeat run

package/src/agents/codex-scout.md

@@ -23,6 +23,8 @@ files, do not run grep, do not retell the report, and do not reason about the ta
 
 - The task statement (what to find out / what to diagnose / what to review).
 - The path to the repository. If none is given, work in the current working directory.
+- Scope patterns are globs relative to the repository root. A pattern that matches nothing there is
+  refused before the run starts.
 - Optional: `effort: <none|minimal|low|medium|high|xhigh|max>` — Codex reasoning depth.
 - Optional: `slug: <short-name>` for the run folder.
 - Every input listed under **Required dispatcher inputs** above, passed on exactly as given:

package/src/cli-names.mjs

@@ -0,0 +1,6 @@
+/** Names this CLI answers to. */
+
+// Plan_17 §5 found installer and test hook lists drifting; keep executable spellings here so a
+// new alias cannot silently bypass the prune guard. Under src/ because the installed guard reads
+// it too, and cli/ is not copied into the host.
+export const CLI_NAMES = Object.freeze(['codex-bridge', 'codexb']);

package/src/conventions.md

@@ -0,0 +1,44 @@
+# Delegated-run conventions
+
+These are the host conventions for every Codex run. Each block records a real acceptance
+violation caught in this repository and turns it into a guard for the next run.
+
+## Task boundaries - Plan_16 acceptance incident
+
+- Do not refactor code the task did not ask to change.
+- Do not delete code on your own initiative.
+- Do not change behavior branches whose behavior the task does not mention, even inside an
+  allowed file.
+
+The 2026-08-06 Plan_16 acceptance finding applied a new reason order to a transport branch that
+already named its reason. Preserve existing branches unless the task explicitly changes them.
+
+## Contracts without silent defaults - Plan_16 reasonFrom incident
+
+- Require arguments that the contract needs instead of supplying a default.
+- Fail loud when a required value is absent; do not silently fall back.
+- Keep volatile identifiers such as model IDs and API versions in configuration, not runtime code.
+
+The 2026-08-06 `reasonFrom(runDir, eventData = {})` finding replaced a required contract with a
+silent default. Missing inputs must remain visible at the boundary that can explain them.
+
+## Structure and size - 2026-08-06 projects reload incident
+
+- Keep every source file at or below 400 lines.
+- Give each module one responsibility.
+- Do not create `utils.mjs` dumping grounds.
+- Never split coherent pieces solely to reach the line limit.
+
+The 2026-08-06 `projects` reload finding exposed pseudo-duplicate exports and just-in-case code.
+Keep related code together, but remove a real responsibility or create a focused module when a
+boundary is needed.
+
+## Tests and comments - 2026-08-05 step 2b incident
+
+- Add a guard test for every invariant accepted by the task.
+- Splitting a file must delete no test case.
+- Comments explain WHY and name the incident or decision that makes the rule necessary.
+
+The 2026-08-05 step 2b acceptance found the abandoned-run check below the commit check. Test the
+ordering invariant itself, and leave the incident in the comment so a later cleanup does not
+silently undo it.

package/src/heartbeat.mjs

@@ -51,7 +51,7 @@ export function heartbeatAge(runDir, now = Date.now()) {
 
 /**
  * How long a run has been silent, in words. It lives beside the age it formats because both the
- * worktree lock's refusal and `sweep`'s report have to name the same silence to the same operator;
+ * worktree lock's refusal and `unlock`'s report have to name the same silence to the same operator;
  * two copies of this drifted apart the moment they were written.
  */
 export function formatSilence(age) {

package/src/hooks/live-runs.mjs

@@ -2,8 +2,8 @@
  * Shared, fail-open knowledge of live Codex runs.
  *
  * The reply guard and the worktree lock must answer the same question: a status.json is live
- * only while it says `running`, its runner pid accepts signal 0, and its progress heartbeat is
- * fresh. Keeping those probes and the directory scan here prevents the two protections from
+ * only while it says `running`, its runner pid is judged alive for this run, and its progress
+ * heartbeat is fresh. Keeping those probes and the directory scan here prevents the two protections from
  * disagreeing about a run, which would recreate the 2026-08-06 incident where a dead Codex
  * child left its worker and lock looking live through a grandchild-held stdio pipe.
  *
@@ -14,16 +14,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { isHeartbeatFresh } from '../heartbeat.mjs';
+import { readJsonFileSync } from '../json-file.mjs';
+import { IDENTITY_DEAD, IDENTITY_FOREIGN, processIdentity } from '../process-identity.mjs';
 
-/** Signal 0 tests existence without stopping the process; EPERM still means that it exists. */
-export const isPidAlive = (pid) => {
-  if (typeof pid !== 'number') return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === 'EPERM';
-  }
+/**
+ * The hook requires pid judgment plus a fresh heartbeat. Identity uncertainty stays live here
+ * (fail-open), while the identity module deliberately treats a missing heartbeat as unverified;
+ * isHeartbeatFresh() keeps its pre-Plan_20 missing-file compatibility for this separate question.
+ */
+export const isPidAlive = (pid, runDir, status = {}) => {
+  const identity = processIdentity({ runDir, status: { ...status, pid } });
+  return identity !== IDENTITY_DEAD && identity !== IDENTITY_FOREIGN;
 };
 
 /**
@@ -56,13 +57,13 @@ function recognizedStatus(runDir, status) {
     && isNonEmptyString(status.agent)
     && isNonEmptyString(status.slug)
     && isNonEmptyString(status.repo)
-    && isPidAlive(status.pid)
-    && isHeartbeatFresh(runDir);
+    && isHeartbeatFresh(runDir)
+    && isPidAlive(status.pid, runDir, status);
 }
 
 function readStatus(runDir) {
   try {
-    return JSON.parse(fs.readFileSync(path.join(runDir, 'status.json'), 'utf8'));
+    return readJsonFileSync(path.join(runDir, 'status.json'));
   } catch {
     return null;
   }

package/src/hooks/order-gate.mjs

@@ -14,7 +14,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { missingInputs } from '../required-inputs.mjs';
+import { diagnoseInput, missingInputs } from '../required-inputs.mjs';
 import { SUBAGENT_TOOLS } from '../hook-definitions.mjs';
 
 const HOME = os.homedir();
@@ -56,7 +56,12 @@ if (!missing.length) pass();
 const reason = [
   'Order gate denied the Agent call because required dispatcher input(s) are missing or still placeholders.',
   'Write each value in tool_input.prompt using `label: value` before launching the dispatcher:',
-  ...missing.map((entry) => `- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`),
+  ...missing.flatMap((entry) => {
+    const lines = [`- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`];
+    const diagnosis = diagnoseInput(toolInput.prompt, entry.label);
+    if (diagnosis) lines.push(`  found \`${diagnosis.line}\`, ${diagnosis.reason}`);
+    return lines;
+  }),
 ].join('\n');
 
 process.stdout.write(JSON.stringify({

package/src/hooks/prune-guard.mjs

@@ -11,6 +11,7 @@
  * Anything unrecognised passes. A guard that misreads its input must not break unrelated host work.
  */
 import fs from 'node:fs';
+import { CLI_NAMES } from '../cli-names.mjs';
 import { SHELL_TOOLS } from '../hook-definitions.mjs';
 
 const SHELL_TOOL_NAMES = new Set(SHELL_TOOLS);
@@ -18,10 +19,17 @@ const pass = () => process.exit(0);
 
 // The binary, then the verb, with any path in front of it: an agent reaches the CLI as
 // `codex-bridge`, as `node bin/codex-bridge.mjs`, or through an absolute path, and a guard that
-// only knew the bare name would be bypassed by the spelling everyone uses inside a clone. Matching
-// a lone `prune` is not an option either — `git prune` and `npm prune` are not this package's
-// business, and a guard that breaks unrelated work is a guard that gets uninstalled.
-const PRUNE_CALL = /(^|[\s;&|(`])(\S*[\\/])?codex-bridge(\.mjs)?\s+prune(\s|$)/;
+// only knew the bare name would be bypassed by the spelling everyone uses inside a clone. Plan_19
+// adds a second executable spelling, so build this matcher from the shared list instead of
+// repeating names here. Matching a lone `prune` is not an option either — `git prune` and
+// `npm prune` are not this package's business, and a guard that breaks unrelated work is a guard
+// that gets uninstalled.
+const escapeRegex = (name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const CLI_NAME_PATTERN = CLI_NAMES.map(escapeRegex).join('|');
+const PRUNE_CALL = new RegExp(
+  '(^|[\\s;&|(`])(\\S*[\\\\/])?(?:' + CLI_NAME_PATTERN
+    + ')(\\.mjs)?\\s+prune(\\s|$)',
+);
 
 let input;
 try {

package/src/hooks/reply-guard.mjs

@@ -29,6 +29,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { readJsonFileSync } from '../json-file.mjs';
 import { isPidAlive, liveRuns, normalizePath } from './live-runs.mjs';
 
 const HOME = os.homedir();
@@ -120,7 +121,7 @@ const takeTry = (agentId, kind) => {
   if (!agentId) return 'untracked';
   let seen;
   try {
-    seen = JSON.parse(fs.readFileSync(BLOCKED_FILE, 'utf8'));
+    seen = readJsonFileSync(BLOCKED_FILE);
   } catch {
     seen = {};
   }
@@ -253,7 +254,7 @@ const statusPath = path.join(runDir, 'status.json');
 if (fs.existsSync(statusPath)) {
   let runStatus = null;
   try {
-    runStatus = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
+    runStatus = readJsonFileSync(statusPath);
   } catch {
     runStatus = null;
   }
@@ -317,7 +318,7 @@ if (!fs.existsSync(metaPath)) {
 
 let meta;
 try {
-  meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+  meta = readJsonFileSync(metaPath);
 } catch {
   pass();
 }

package/src/json-file.mjs

@@ -0,0 +1,30 @@
+/**
+ * Reads JSON written by another program and keeps its file boundary in one place.
+ *
+ * Plan_24 records the live Windows incident: PowerShell Out-File -Encoding utf8 wrote a BOM
+ * that Claude Code accepted but JSON.parse rejected. Readers must strip that BOM consistently.
+ */
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+
+function parseJson(file, raw) {
+  const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new Error(`cannot parse ${file}: ${error.message}`, { cause: error });
+  }
+}
+
+export async function readJsonFile(file) {
+  return parseJson(file, await fsp.readFile(file, 'utf8'));
+}
+
+export async function readJsonFileWithRaw(file) {
+  const raw = await fsp.readFile(file, 'utf8');
+  return { raw, value: parseJson(file, raw) };
+}
+
+export function readJsonFileSync(file) {
+  return parseJson(file, fs.readFileSync(file, 'utf8'));
+}

package/src/meta/chain.mjs

@@ -9,6 +9,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
+import { startedRuns } from './pre-start.mjs';
 import { normalizePath, readJson } from './paths.mjs';
 
 /**
@@ -69,15 +70,16 @@ export function chainRuns(runsRoot, repo, slug, taskHash = '', orderId = '') {
 }
 
 /**
- * The tree as it stood before the task began: state-before.txt of the FIRST run of the
- * chain. The first and not the previous one, because a middle run can end without an
- * "after" snapshot at all — 2026-07-31_114736 wrote eleven files and left neither
- * state-after.txt nor meta.json — and its own "before" is then the last honest base.
- * null when there is no chain or that first run never got a snapshot; an existing but
+ * The tree as it stood before the task began: state-before.txt of the FIRST STARTED run of the
+ * chain. A pre-start folder has no snapshot, so treating it as first made the next pass lose
+ * its baseline in the Plan_23 incident; after that, the first started run is still preferred
+ * over a later one because a middle run can end without an "after" snapshot at all.
+ * null when there is no started run or that first run never got a snapshot; an existing but
  * empty snapshot is a clean tree, which is data, not absence.
  */
 export function chainBaseline(runsRoot, repo, slug, taskHash = '', orderId = '') {
-  const [first] = chainRuns(runsRoot, repo, slug, taskHash, orderId);
+  const chain = chainRuns(runsRoot, repo, slug, taskHash, orderId);
+  const [first] = startedRuns(runsRoot, chain);
   if (!first) return null;
   try {
     return fs.readFileSync(path.join(runsRoot, first, 'state-before.txt'), 'utf8');

package/src/meta/paths.mjs

@@ -4,9 +4,10 @@
  * Two sides spell the same file differently — git prints repo-relative paths with forward
  * slashes, Codex writes whatever it likes — so nothing above this module compares a path
  * before it has been through here. This is also the only module that touches the
- * filesystem for reading: everything else receives text, JSON or a byte count from it.
+ * filesystem for reading artifacts: everything else receives text, JSON or a byte count from it.
  */
 import fs from 'node:fs';
+import { readJsonFileSync } from '../json-file.mjs';
 
 /** One line, no newlines, bounded length — a five-line reply must stay five lines. */
 export const line = (value, max = 200) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
@@ -20,17 +21,12 @@ export const readText = (file) => {
 };
 
 /**
- * A run's JSON artifact, or null when there is none to read. The byte-order mark is stripped
- * first: JSON.parse rejects it, and a status.json rewritten by a Windows editor or by
- * PowerShell's `Set-Content -Encoding utf8` would then read as "no such run" — silently
- * excusing that run from every check that looks it up.
+ * A run's JSON artifact, or null when there is none to read. The shared reader strips the
+ * byte-order mark that PowerShell's `Out-File -Encoding utf8` added in the Plan_24 incident.
  */
 export const readJson = (file) => {
   try {
-    const text = fs.readFileSync(file, 'utf8');
-    // Compared by code point rather than matched by a literal: a byte-order mark in the
-    // source of this file would be invisible to the next reader.
-    return JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+    return readJsonFileSync(file);
   } catch {
     return null;
   }

package/src/meta/pre-start.mjs

@@ -0,0 +1,30 @@
+/**
+ * Identifies runs that never started Codex and removes them from paid-run views.
+ *
+ * The explicit state is the durable contract for new guard refusals; the second branch keeps
+ * folders written before this fix from poisoning the next launch. Do not infer this from
+ * events.jsonl: retention.mjs deletes that transport file from old paid runs, while
+ * meta.events_bytes is recorded at verdict time and survives cleanup. The Plan_23 incident
+ * showed why confusing those cases would remove repeat protection from a run that spent quota.
+ */
+
+import path from 'node:path';
+
+import { readJson } from './paths.mjs';
+
+export function abortedPreStart(runDir) {
+  const status = readJson(path.join(runDir, 'status.json'));
+  if (status?.state === 'aborted_pre_start') return true;
+  if (status?.state !== 'failed') return false;
+
+  const meta = readJson(path.join(runDir, 'meta.json'));
+  return meta?.exit === null
+    && meta?.session_id == null
+    && meta?.events_bytes === 0
+    && meta?.stderr_bytes === 0
+    && meta?.tokens_reported !== true;
+}
+
+export function startedRuns(runsRoot, runs) {
+  return runs.filter((run) => !abortedPreStart(path.join(runsRoot, run)));
+}

package/src/meta/run-state.mjs

@@ -10,24 +10,26 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { changedPaths, line, normalizePath, readJson, readText, size } from './paths.mjs';
+import {
+  IDENTITY_ALIVE,
+  IDENTITY_UNVERIFIED,
+  processIdentity,
+} from '../process-identity.mjs';
 
 /**
- * Is this pid still running? EPERM means the process exists and belongs to someone else,
- * which for our purposes is alive — treating it as dead would mark a live run abandoned.
+ * Is this pid still running for this run? Unknown identity remains live here: treating an
+ * unverified process as dead would mark a live run abandoned, and readers must fail open.
  */
-export const pidAlive = (pid) => {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === 'EPERM';
-  }
+const isAliveIdentity = (identity) => identity === IDENTITY_ALIVE || identity === IDENTITY_UNVERIFIED;
+
+const pidAlive = (pid, runDir, status = {}) => {
+  const identity = processIdentity({ runDir, status: { ...status, pid } });
+  return isAliveIdentity(identity);
 };
 
 /**
- * This module deliberately judges by the pid alone, while hooks/live-runs.mjs also requires a
- * fresh progress heartbeat. The two answer different questions, and merging them broke both:
+ * This module deliberately judges by the run's pid identity alone, while hooks/live-runs.mjs also
+ * requires a fresh progress heartbeat. The two answer different questions, and merging them broke both:
  *
  * - a hook asks "may the operator edit this tree", and a stalled run must stop holding that
  *   lock — the operator is editing knowingly, and a stale run should not cost them 25 minutes;
@@ -80,7 +82,8 @@ export function markAbandoned(runsRoot, currentTree) {
     if (!entry.isDirectory()) continue;
     const runDir = path.join(runsRoot, entry.name);
     const status = readJson(path.join(runDir, 'status.json'));
-    if (!status || status.state !== 'running' || pidAlive(status.pid)) continue;
+    if (!status || status.state !== 'running') continue;
+    if (pidAlive(status.pid, runDir, status)) continue;
     const metaPath = path.join(runDir, 'meta.json');
     const meta = readJson(metaPath);
     if (!meta && fs.existsSync(metaPath)) continue;
@@ -138,6 +141,11 @@ export function markAbandoned(runsRoot, currentTree) {
  * are not looked at — running scouting alongside a build is the normal way to work.
  */
 export function activeRun(runsRoot, repo, agent = 'codex-build') {
+  return activeRunDetails(runsRoot, repo, agent)?.run || null;
+}
+
+/** Finds the same active run while retaining identity uncertainty for a refusal message. */
+export function activeRunDetails(runsRoot, repo, agent = 'codex-build') {
   let entries;
   try {
     entries = fs.readdirSync(runsRoot, { withFileTypes: true });
@@ -151,7 +159,8 @@ export function activeRun(runsRoot, repo, agent = 'codex-build') {
     const status = readJson(path.join(runDir, 'status.json'));
     if (!status || status.state !== 'running' || status.agent !== agent) continue;
     if (normalizePath(status.repo) !== wanted) continue;
-    if (pidAlive(status.pid)) return entry.name;
+    const identity = processIdentity({ runDir, status });
+    if (isAliveIdentity(identity)) return { run: entry.name, identity };
   }
   return null;
 }
@@ -194,7 +203,9 @@ export function abandonedBranchDrift(runsRoot, repo, currentBranch) {
  * the runner itself. It still goes through meta.json, so there is no second path by
  * which a reply could exist without an artifact backing it.
  */
-export function writeFailure(runDir, agent, reason, extraLines = []) {
+// The marker is reserved for refusals before Codex starts; Plan_23 showed that calling those
+// ordinary failures makes a no-quota folder consume the same continuation slot as paid work.
+export function writeFailure(runDir, agent, reason, extraLines = [], preStart = false) {
   const meta = {
     agent,
     project: path.basename(path.dirname(runDir)),
@@ -214,7 +225,11 @@ export function writeFailure(runDir, agent, reason, extraLines = []) {
     env: readJson(path.join(runDir, 'env.json')),
   };
   fs.writeFileSync(path.join(runDir, 'meta.json'), `${JSON.stringify(meta, null, 2)}\n`);
-  writeStatus(runDir, { state: 'failed', status: 'FAIL', finished_at: meta.finished_at });
+  writeStatus(runDir, {
+    state: preStart ? 'aborted_pre_start' : 'failed',
+    status: 'FAIL',
+    finished_at: meta.finished_at,
+  });
   const reply = [`FAIL — ${meta.reason}`, ...extraLines, `Run: ${runDir}`].join('\n');
   return { meta, reply };
 }

package/src/process-identity.mjs

@@ -0,0 +1,140 @@
+/**
+ * Answers whether a recorded pid belongs to the process that started this run.
+ *
+ * Signal 0 is the cheap usual probe. A permission error means only that a process exists, not
+ * that it is this run's process, so a stale or missing heartbeat falls through to the OS start
+ * time probe. `foreign` is a known-dead diagnostic for callers that need to explain pid reuse;
+ * readers treat it like `dead`, while `unverified` remains fail-open.
+ */
+import { spawnSync } from 'node:child_process';
+import { heartbeatAge, HEARTBEAT_STALE_MS } from './heartbeat.mjs';
+
+export const IDENTITY_ALIVE = 'alive';
+export const IDENTITY_DEAD = 'dead';
+export const IDENTITY_FOREIGN = 'foreign';
+export const IDENTITY_UNVERIFIED = 'unverified';
+export const PROCESS_START_TOLERANCE_MS = 1_000;
+export const LEGACY_START_GRACE_MS = 30_000;
+
+const signalZero = (pid) => process.kill(pid, 0);
+
+function defaultCommandRunner(command, args) {
+  return spawnSync(command, args, { encoding: 'utf8', windowsHide: true });
+}
+
+function timestamp(value) {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function commandStartTime(pid, commandRunner = defaultCommandRunner) {
+  try {
+    const command = process.platform === 'win32' ? 'powershell.exe' : 'ps';
+    const args = process.platform === 'win32'
+      ? [
+          '-NoProfile',
+          '-NonInteractive',
+          '-Command',
+          // Get-Process answers only for processes of the same user, and the pid this exists to
+          // recognise was taken by a SYSTEM service — so CIM has to answer after it. Get-CimInstance
+          // returns CreationDate as a DateTime already; the DMTF converter belongs to the older
+          // Get-WmiObject and throws "dmtfDate out of range" on this value, which cost this probe
+          // its whole purpose once. No $ErrorActionPreference = 'Stop' either: one failing source
+          // must fall through to the next rather than end the script.
+          [
+            `$process = Get-Process -Id ${pid} -ErrorAction SilentlyContinue`,
+            "if ($process) { try { $start = $process.StartTime; if ($start) { $start.ToUniversalTime().ToString('o'); exit 0 } } catch {} }",
+            `$cim = Get-CimInstance Win32_Process -Filter \"ProcessId=${pid}\" -ErrorAction SilentlyContinue`,
+            "if ($cim -and $cim.CreationDate) { $cim.CreationDate.ToUniversalTime().ToString('o') }",
+          ].join('; '),
+        ]
+      : ['-o', 'lstart=', '-p', String(pid)];
+    const result = commandRunner(command, args);
+    if (!result || result.error || result.status !== 0) return null;
+    const output = String(result.stdout ?? '').trim();
+    return timestamp(output);
+  } catch {
+    return null;
+  }
+}
+
+function heartbeatIsFreshForIdentity(runDir, now) {
+  if (typeof runDir !== 'string' || !runDir.trim()) return false;
+  const age = heartbeatAge(runDir, now);
+  // isHeartbeatFresh() deliberately treats a missing file as fresh for pre-Plan_20 records.
+  // Identity is stricter: a missing heartbeat proves nothing about THIS process, so it must probe.
+  return age !== null && age <= HEARTBEAT_STALE_MS;
+}
+
+function optionsFor(input) {
+  return input && typeof input === 'object' ? input : {};
+}
+
+export function processAlive(pid, kill = signalZero) {
+  if (!Number.isInteger(pid) || pid <= 0 || pid > 0x7fff_ffff) return false;
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EACCES' || error?.code === 'EPERM';
+  }
+}
+
+/**
+ * Return alive/dead/unverified, with foreign as the explicit known-not-this-run case.
+ *
+ * The probe and signal-0 runner are injectable so tests can exercise every branch without
+ * touching a real process. `commandRunner` receives the same command/arguments pair as spawnSync.
+ */
+export function processIdentity(input = {}) {
+  const options = optionsFor(input);
+  const status = options.status && typeof options.status === 'object' ? options.status : options;
+  const pid = options.pid ?? status.pid;
+  if (!Number.isInteger(pid) || pid <= 0 || pid > 0x7fff_ffff) return IDENTITY_DEAD;
+
+  const kill = options.kill || options.signalZero || signalZero;
+  try {
+    kill(pid, 0);
+  } catch (error) {
+    if (error?.code === 'ESRCH') return IDENTITY_DEAD;
+    if (error?.code === 'EINVAL') return IDENTITY_DEAD;
+    if (error?.code !== 'EACCES' && error?.code !== 'EPERM') return IDENTITY_UNVERIFIED;
+  }
+
+  const now = options.now ?? Date.now();
+  if (!options.ignoreHeartbeat && heartbeatIsFreshForIdentity(options.runDir, now)) {
+    return IDENTITY_ALIVE;
+  }
+
+  const probe = options.probe || options.processStartProbe
+    || ((value) => commandStartTime(value, options.commandRunner));
+  let processStartedAt;
+  try {
+    processStartedAt = timestamp(probe(pid, options));
+  } catch {
+    processStartedAt = null;
+  }
+  if (processStartedAt === null) return IDENTITY_UNVERIFIED;
+
+  const hasRecordedStart = Object.prototype.hasOwnProperty.call(status, 'process_started_at')
+    && status.process_started_at !== null
+    && status.process_started_at !== '';
+  if (hasRecordedStart) {
+    const recordedStart = timestamp(status.process_started_at);
+    if (recordedStart === null) return IDENTITY_UNVERIFIED;
+    return Math.abs(processStartedAt - recordedStart) <= PROCESS_START_TOLERANCE_MS
+      ? IDENTITY_ALIVE
+      : IDENTITY_FOREIGN;
+  }
+
+  const startedAt = timestamp(status.started_at);
+  if (startedAt === null) return IDENTITY_UNVERIFIED;
+  return processStartedAt > startedAt + LEGACY_START_GRACE_MS
+    ? IDENTITY_FOREIGN
+    : IDENTITY_ALIVE;
+}
+
+export const probeProcessStart = commandStartTime;