feature-factory 0.7.0

package/state/index.js

@@ -0,0 +1,64 @@
+// The package's entire public surface for consumers (the opencode plugin, the TUI):
+// a read-only reader plus the schema. Anything that mutates goes through the CLI.
+//
+// Finding 6: `transition` used to be exported from here, and package.json exposes
+// this module as the package root — so the public API handed out mutation authority
+// while claiming to be read-only. It now lives in ./transition.js, which is not
+// exported from package.json and is imported only by bin/factory.js.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { GATE_NAMES, validateRun } from "./schema.js";
+
+export { CONTROL_PLANE, validateRun, SchemaError, RUN_KEYS, SCHEMA_VERSION, RUN_STATUSES, TERMINAL_STATUSES, MODES,
+  GATE_NAMES, GATE_STATUSES, STEP_STATUSES, SLICE_STATUSES, VALIDATOR_VERDICTS } from "./schema.js";
+
+export function readRun(runDir) {
+  return validateRun(JSON.parse(readFileSync(join(runDir, "run.json"), "utf8")));
+}
+
+// Read a run without validating, for diagnostics that must describe a broken
+// record rather than refuse to load it. Never use this to make a decision.
+export function readRunUnchecked(runDir) {
+  try {
+    return { ok: true, run: JSON.parse(readFileSync(join(runDir, "run.json"), "utf8")) };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+function nextSliceAction(slices) {
+  const blockedSlice = slices.find((slice) => slice.status === "blocked");
+  if (blockedSlice) return `blocked-slice:${blockedSlice.id}`;
+  const activeSlice = slices.find((slice) => ["running", "review"].includes(slice.status));
+  if (activeSlice) return `observe-slice:${activeSlice.id}`;
+  const pendingSlice = slices.find((slice) => slice.status === "pending");
+  return pendingSlice ? `dispatch-slice:${pendingSlice.id}` : undefined;
+}
+
+// The single answer to "what happens next". Both `factory status` and the opencode
+// sidebar need it, and two implementations of resume order would drift — which is the
+// defect class this codebase keeps finding. Read-only, so it belongs here.
+//
+// Resume: the first thing a returning session needs to know. Preserves the inherited
+// rules: a pending gate re-presents, a running slice re-observes, an
+// unaccepted step re-runs.
+export function nextAction(run) {
+  if (["completed", "partial", "blocked"].includes(run.status)) return `terminal:${run.status}`;
+  const openStep = run.steps.find((step) => step.status !== "accepted");
+  const sliceAction = nextSliceAction(run.slices);
+  for (const name of GATE_NAMES) {
+    const gate = run.gates[name];
+    // `pending` waits on a human; absent means the phase has not been reached, which is
+    // still not "done". But naming an absent gate while an agent is mid-round reads as
+    // "waiting on you" — so existing slice or step work is named instead.
+    if (gate === undefined) return sliceAction ?? (openStep ? `step:${openStep.agent}` : `gate:${name}`);
+    if (gate.status === "pending") return `gate:${name}`;
+    if (gate.status === "stop") return `stopped-at-gate:${name}`;
+    if (gate.status === "changes") return `changes-at-gate:${name}`;
+    if (name === "brief" && gate.status === "approved" && run.slices.length === 0) return "seed-slices";
+  }
+  if (sliceAction) return sliceAction;
+  if (openStep) return `step:${openStep.agent}`;
+  if (!run.pr_url) return "pr";
+  return "complete";
+}

package/state/review-archive.js

@@ -0,0 +1,48 @@
+// A review record lives at one path per subject, so each attempt overwrites the last. That is
+// fine while a run succeeds and fatal when it does not: attempts are budgeted, exhausting the
+// budget blocks a run, and `blocked` is final because `paths` freeze at seeding. The one
+// artifact an operator needs to understand why a run blocked -- what the reviewer actually
+// demanded on attempts 1 and 2 -- is the artifact the third attempt destroys.
+//
+// Run 216 is the case: its test-verifier was rejected twice and approved on the third. The
+// reasons for both rejections are unrecoverable. They were reconstructed from commit subjects,
+// which is guesswork wearing evidence's clothes.
+//
+// Instruction, not enforcement: losing a verdict cannot produce a false green, so a failed
+// archive must never fail the step that earned it. The caller reports where the copy landed,
+// or that it did not, rather than throwing.
+import { readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { writeProtectedJsonAtomic } from "../core/atomic-write.js";
+import { ProtectedWriteError } from "../core/atomic-write.js";
+
+// The attempt comes from the record, not from `--attempts`. The record is what is being
+// preserved, and a snapshot filed under a number the record does not itself claim would
+// misattribute a verdict to an attempt that did not produce it.
+export function attemptArchiveRef(ref, attempt) {
+  const dir = dirname(ref);
+  const stem = basename(ref).replace(/\.json$/u, "");
+  return join(dir === "." ? "" : dir, `${stem}.attempt-${attempt}.json`);
+}
+
+export async function archiveReviewAttempt(runDir, ref) {
+  if (typeof ref !== "string" || !ref.trim()) return null;
+  let record;
+  try {
+    record = JSON.parse(readFileSync(join(runDir, ref), "utf8"));
+  } catch {
+    return null;
+  }
+  const attempt = record?.attempt;
+  if (!Number.isSafeInteger(attempt) || attempt < 1) return null;
+  const archive = attemptArchiveRef(ref, attempt);
+  try {
+    // createOnly: an archive that can be overwritten is not an archive. A second record for
+    // the same attempt loses to the first, which is the one the verdict was recorded against.
+    await writeProtectedJsonAtomic(runDir, archive, record, { createOnly: true });
+  } catch (error) {
+    const exists = error instanceof ProtectedWriteError && /already exists/u.test(error.message);
+    if (!exists) return null;
+  }
+  return archive;
+}

package/state/schema.js

@@ -0,0 +1,339 @@
+// run.json adds mode, terminal_result, and pr_base to the inherited fifteen-field baseline.
+// pr_base comes from init, is immutable through the envelope, and feeds status and Step 6.
+// mode preserves autonomous intent; terminal_result records why a run stopped.
+// base_commit was removed because no consumer used it and existing refs answer its questions.
+// Every durable field needs a source, immutable route, and consumer.
+// Closed key sets reject unknown agent-produced state instead of warning.
+
+export const SCHEMA_VERSION = 1;
+
+// Where run state lives, relative to the repository. Was `.claude/factory`, and the privileged-path
+// list hedged with `.opencode/factory` too: two host dotfiles in a host-agnostic package.
+export const CONTROL_PLANE = ".factory";
+
+export const RUN_KEYS = Object.freeze([
+  "version", "run_id", "issue_key", "branch", "worktree", "pr_base", "pr_draft", "created_at", "updated_at",
+  "status", "mode", "max_parallel_slices", "max_retries",
+  "gates", "steps", "slices", "validator", "terminal_result", "pr_url",
+  // Digest of the plan bytes the brief gate approved, so the seed ratifies that plan and not a
+  // later edit of the same filename. See the check in `slices-seed`.
+  "plan_digest",
+  "bootstrap_command", "bootstrap_exit",
+]);
+
+export const RUN_STATUSES = Object.freeze(["running", "completed", "blocked", "partial", "needs-human"]);
+export const TERMINAL_STATUSES = Object.freeze(["completed", "blocked", "partial", "needs-human"]);
+export const MODES = Object.freeze(["interactive", "headless", "autonomous"]);
+
+export const GATE_NAMES = Object.freeze(["story", "brief", "pre_pr"]);
+export const GATE_STATUSES = Object.freeze(["pending", "approved", "changes", "stop"]);
+export const GATE_KEYS = Object.freeze(["status", "at", "artifact"]);
+
+export const STEP_STATUSES = Object.freeze(["running", "accepted", "rejected", "blocked"]);
+export const STEP_KEYS = Object.freeze(["agent", "status", "attempts", "review_ref", "evidence_ref"]);
+
+export const SLICE_STATUSES = Object.freeze(["pending", "running", "review", "merged", "blocked"]);
+export const SLICE_KEYS = Object.freeze([
+  "id", "stack", "depends_on", "status", "worktree", "branch", "attempts",
+  // `paths` is the ratified ownership declaration, seeded from plan/slices.json at
+  // the decompose gate. It lives here rather than being re-read from the plan at
+  // merge time so the set a transition validates against is the set the gate
+  // approved, and so ownership is decidable from run.json alone.
+  // base_ref is the integration head the slice branched from, recorded when it is
+  // dispatched. Without it a slice's own diff is undecidable after the merge - the
+  // integration branch by then contains the slice, so diffing against it is empty
+  // and every ownership check would silently pass.
+  //
+  // test_plan is ratified the same way and for the same reason. It replaced
+  // `observe --skip-tests-reason`, under which the orchestrator authored its own excuse
+  // for shipping an untested slice at the moment of observation - and any nonempty
+  // string was accepted, so "no tests needed" was a valid one. Whether a slice needs
+  // tests is a decision the decompose gate makes: a nonempty test_plan means an observed
+  // green run is required, and an empty one is an approved exemption. Empty by omission
+  // is not possible, because the field is required.
+  "paths", "path_amendments", "test_plan", "base_ref", "evidence_ref", "review_ref", "merge_commit",
+]);
+const PATH_AMENDMENT_KEYS = Object.freeze(["added_paths", "reason", "session", "at"]);
+
+export const VALIDATOR_VERDICTS = Object.freeze(["GO", "GO-WITH-NITS", "NO-GO"]);
+// reviewed_head is the fourth field, justified by attack 4: a verdict that does not
+// name the head it judged cannot be refused once that head moves.
+export const VALIDATOR_KEYS = Object.freeze(["verdict", "report", "reviewed_head", "loops"]);
+export const TERMINAL_RESULT_KEYS = Object.freeze(["status", "reason"]);
+
+// Finding 2: an invalid evidence ref was only rejected when consumed at merge, so a
+// foreign path could be recorded into run.json and sit there looking legitimate. Refs
+// are admitted at store time: run-local, no traversal, no absolute paths, and under
+// the directory that owns them.
+const REF_DIRS = Object.freeze({ evidence_ref: "evidence", review_ref: "reviews" });
+
+function runLocalRef(errors, holder, key, path) {
+  const value = holder[key];
+  if (value === null || value === undefined) return;
+  if (typeof value !== "string" || !value.trim()) {
+    errors.push({ path: `${path}.${key}`, message: "must be a non-empty string" });
+    return;
+  }
+  const parts = value.split(/[\\/]/u);
+  if (value.startsWith("/") || parts.includes("..") || parts.includes(".")) {
+    errors.push({ path: `${path}.${key}`, message: "must be run-local without traversal" });
+    return;
+  }
+  const dir = REF_DIRS[key];
+  if (dir && !value.startsWith(`${dir}/`)) {
+    errors.push({ path: `${path}.${key}`, message: `must be under ${dir}/` });
+  }
+}
+
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/u;
+const SHA = /^[0-9a-f]{40}$/u;
+const ID = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u;
+
+export class SchemaError extends Error {
+  constructor(errors) {
+    super(errors.map(({ path, message }) => `${path}: ${message}`).join("; "));
+    this.name = "SchemaError";
+    this.errors = errors;
+  }
+}
+
+export function validateRun(run) {
+  const errors = [];
+  object(errors, run, "run", RUN_KEYS);
+  if (errors.length) throw new SchemaError(errors);
+
+  if (run.version !== SCHEMA_VERSION) errors.push({ path: "run.version", message: `must be ${SCHEMA_VERSION}` });
+  pattern(errors, run, "run_id", ID, "run");
+  enumValue(errors, run, "status", RUN_STATUSES, "run");
+  enumValue(errors, run, "mode", MODES, "run");
+  for (const key of ["branch", "worktree"]) required(errors, run, key, "run");
+  for (const key of ["created_at", "updated_at"]) pattern(errors, run, key, ISO, "run");
+  for (const key of ["max_parallel_slices", "max_retries"]) positiveInt(errors, run, key, "run");
+  for (const key of ["issue_key", "pr_base", "pr_url", "plan_digest"]) optionalString(errors, run, key, "run");
+  if (Object.hasOwn(run, "pr_draft") && typeof run.pr_draft !== "boolean") {
+    errors.push({ path: "run.pr_draft", message: "must be a boolean" });
+  }
+  if (Object.hasOwn(run, "bootstrap_command") !== Object.hasOwn(run, "bootstrap_exit")) {
+    errors.push({ path: "run.bootstrap_command", message: "must be present exactly when bootstrap_exit is present" });
+  } else if (Object.hasOwn(run, "bootstrap_command")) {
+    required(errors, run, "bootstrap_command", "run");
+    if (run.bootstrap_exit !== null) nonNegativeInt(errors, run, "bootstrap_exit", "run");
+  }
+
+  gates(errors, run.gates);
+  steps(errors, run.steps);
+  slices(errors, run.slices);
+  validator(errors, run.validator);
+  terminalResult(errors, run.terminal_result, run.status);
+
+  if (errors.length) throw new SchemaError(errors);
+  return run;
+}
+
+function gates(errors, value) {
+  if (!isRecord(value)) return void errors.push({ path: "run.gates", message: "must be an object" });
+  const unknown = Object.keys(value).filter((key) => !GATE_NAMES.includes(key));
+  if (unknown.length) errors.push({ path: "run.gates", message: `unknown gates: ${unknown.join(", ")}` });
+  for (const name of GATE_NAMES) {
+    const gate = value[name];
+    if (gate === undefined) continue;
+    const path = `run.gates.${name}`;
+    if (!object(errors, gate, path, GATE_KEYS)) continue;
+    enumValue(errors, gate, "status", GATE_STATUSES, path);
+    if (gate.at !== null) optionalPattern(errors, gate, "at", ISO, path);
+    if (gate.artifact !== undefined && gate.artifact !== null) optionalString(errors, gate, "artifact", path);
+  }
+}
+
+function steps(errors, value) {
+  if (!Array.isArray(value)) return void errors.push({ path: "run.steps", message: "must be an array" });
+  const seen = new Set();
+  value.forEach((step, index) => {
+    const path = `run.steps[${index}]`;
+    if (!object(errors, step, path, STEP_KEYS)) return;
+    required(errors, step, "agent", path);
+    enumValue(errors, step, "status", STEP_STATUSES, path);
+    positiveInt(errors, step, "attempts", path);
+    for (const key of ["review_ref", "evidence_ref"]) runLocalRef(errors, step, key, path);
+    if (seen.has(step.agent)) errors.push({ path: `${path}.agent`, message: "duplicate step agent" });
+    seen.add(step.agent);
+  });
+}
+
+function slices(errors, value) {
+  if (!Array.isArray(value)) return void errors.push({ path: "run.slices", message: "must be an array" });
+  const ids = new Set(value.filter(isRecord).map((slice) => slice.id));
+  // Finding 5: the id set existed only for dependency validation, so two slices could
+  // share an id. Every later update maps by id and would then hit both rows.
+  const seenIds = new Set();
+  for (const slice of value.filter(isRecord)) {
+    if (seenIds.has(slice.id)) errors.push({ path: "run.slices", message: `duplicate slice id '${slice.id}'` });
+    seenIds.add(slice.id);
+  }
+  value.forEach((slice, index) => {
+    const path = `run.slices[${index}]`;
+    if (!object(errors, slice, path, SLICE_KEYS)) return;
+    pattern(errors, slice, "id", ID, path);
+    required(errors, slice, "stack", path);
+    enumValue(errors, slice, "status", SLICE_STATUSES, path);
+    positiveInt(errors, slice, "attempts", path);
+    for (const key of ["worktree", "branch"]) nullableString(errors, slice, key, path);
+    for (const key of ["evidence_ref", "review_ref"]) runLocalRef(errors, slice, key, path);
+    if (slice.base_ref !== null && slice.base_ref !== undefined) optionalPattern(errors, slice, "base_ref", SHA, path);
+    // Finding 3: requiring base_ref only at "merged" let a slice run and review with
+    // none, then receive its first value on the merge transition - chosen after the
+    // fact to exclude earlier commits from the ownership diff. The branch point is a
+    // fact established when the slice is activated, so it is required from the moment
+    // the slice leaves "pending".
+    if (slice.status !== "pending" && !SHA.test(String(slice.base_ref))) {
+      errors.push({ path: `${path}.base_ref`, message: `is required once a slice is ${slice.status}` });
+    }
+    if (slice.merge_commit !== null && slice.merge_commit !== undefined) {
+      optionalPattern(errors, slice, "merge_commit", SHA, path);
+    }
+    // An array, possibly empty - empty is the approved exemption - but never absent, so a
+    // slice cannot acquire an exemption by omitting the field.
+    if (!Array.isArray(slice.test_plan) || !slice.test_plan.every((entry) => stringValue(entry))) {
+      errors.push({ path: `${path}.test_plan`, message: "must be an array of strings; empty means tests were waived at the gate" });
+    }
+    if (!Array.isArray(slice.paths) || slice.paths.length === 0 || !slice.paths.every((entry) => stringValue(entry))) {
+      errors.push({ path: `${path}.paths`, message: "must be a non-empty array of paths" });
+    } else if (slice.paths.some((entry) => !repositoryRelativePath(entry))) {
+      // A declared path that escapes the repository would make ownership
+      // unenforceable, so it is refused at admission rather than at merge.
+      errors.push({ path: `${path}.paths`, message: "must be repository-relative without '..'" });
+    }
+    pathAmendments(errors, slice, path);
+    if (!Array.isArray(slice.depends_on)) {
+      errors.push({ path: `${path}.depends_on`, message: "must be an array" });
+    } else {
+      for (const dep of slice.depends_on) {
+        if (!ids.has(dep)) errors.push({ path: `${path}.depends_on`, message: `unknown slice '${dep}'` });
+        if (dep === slice.id) errors.push({ path: `${path}.depends_on`, message: "slice cannot depend on itself" });
+      }
+    }
+    // A merged slice must record what it merged; otherwise the merge proof has
+    // nothing to bind to.
+    if (slice.status === "merged" && !SHA.test(String(slice.merge_commit))) {
+      errors.push({ path: `${path}.merge_commit`, message: "is required when a slice is merged" });
+    }
+  });
+}
+
+function pathAmendments(errors, slice, path) {
+  if (slice.path_amendments === undefined) return;
+  if (!Array.isArray(slice.path_amendments)) {
+    errors.push({ path: `${path}.path_amendments`, message: "must be an array" });
+    return;
+  }
+  const recorded = new Set();
+  const currentPaths = Array.isArray(slice.paths) ? slice.paths : [];
+  slice.path_amendments.forEach((amendment, index) => {
+    const amendmentPath = `${path}.path_amendments[${index}]`;
+    if (!object(errors, amendment, amendmentPath, PATH_AMENDMENT_KEYS)) return;
+    for (const key of ["reason", "session"]) required(errors, amendment, key, amendmentPath);
+    pattern(errors, amendment, "at", ISO, amendmentPath);
+    if (!Array.isArray(amendment.added_paths) || amendment.added_paths.length === 0
+      || !amendment.added_paths.every((entry) => repositoryRelativePath(entry))) {
+      errors.push({ path: `${amendmentPath}.added_paths`, message: "must be a non-empty array of repository-relative paths without '..'" });
+      return;
+    }
+    for (const added of amendment.added_paths) {
+      if (recorded.has(added)) errors.push({ path: `${amendmentPath}.added_paths`, message: `duplicate recorded path '${added}'` });
+      recorded.add(added);
+      if (!currentPaths.includes(added)) errors.push({ path: `${amendmentPath}.added_paths`, message: `recorded path '${added}' must exist in slice paths` });
+    }
+  });
+}
+
+function validator(errors, value) {
+  if (value === null || value === undefined) return;
+  if (!object(errors, value, "run.validator", VALIDATOR_KEYS)) return;
+  enumValue(errors, value, "verdict", VALIDATOR_VERDICTS, "run.validator");
+  nullableString(errors, value, "report", "run.validator");
+  pattern(errors, value, "reviewed_head", SHA, "run.validator");
+  nonNegativeInt(errors, value, "loops", "run.validator");
+}
+
+function terminalResult(errors, value, status) {
+  if (value === null || value === undefined) {
+    if (TERMINAL_STATUSES.includes(status) && status !== "completed") {
+      errors.push({ path: "run.terminal_result", message: `is required when status is ${status}` });
+    }
+    return;
+  }
+  if (!object(errors, value, "run.terminal_result", TERMINAL_RESULT_KEYS)) return;
+  enumValue(errors, value, "status", TERMINAL_STATUSES, "run.terminal_result");
+  required(errors, value, "reason", "run.terminal_result");
+  if (value.status !== status && !(status === "running" && value.status === "needs-human")) {
+    errors.push({ path: "run.terminal_result.status", message: "must match run.status or preserve a resumed needs-human result" });
+  }
+}
+
+function object(errors, value, path, allowed) {
+  if (!isRecord(value)) {
+    errors.push({ path, message: "must be an object" });
+    return false;
+  }
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) {
+    errors.push({ path, message: `unknown keys: ${unknown.sort().join(", ")}` });
+    return false;
+  }
+  return true;
+}
+
+function required(errors, holder, key, path) {
+  if (!stringValue(holder[key])) errors.push({ path: `${path}.${key}`, message: "must be a non-empty string" });
+}
+
+function optionalString(errors, holder, key, path) {
+  if (holder[key] === undefined || holder[key] === null) return;
+  required(errors, holder, key, path);
+}
+
+function nullableString(errors, holder, key, path) {
+  if (holder[key] === null || holder[key] === undefined) return;
+  required(errors, holder, key, path);
+}
+
+function pattern(errors, holder, key, regex, path) {
+  if (typeof holder[key] !== "string" || !regex.test(holder[key])) {
+    errors.push({ path: `${path}.${key}`, message: `must match ${regex.source}` });
+  }
+}
+
+function optionalPattern(errors, holder, key, regex, path) {
+  if (holder[key] === undefined || holder[key] === null) return;
+  pattern(errors, holder, key, regex, path);
+}
+
+function enumValue(errors, holder, key, allowed, path) {
+  if (!allowed.includes(holder[key])) {
+    errors.push({ path: `${path}.${key}`, message: `must be one of ${allowed.join(" | ")}` });
+  }
+}
+
+function positiveInt(errors, holder, key, path) {
+  if (!Number.isSafeInteger(holder[key]) || holder[key] < 1) {
+    errors.push({ path: `${path}.${key}`, message: "must be a positive integer" });
+  }
+}
+
+function nonNegativeInt(errors, holder, key, path) {
+  if (!Number.isSafeInteger(holder[key]) || holder[key] < 0) {
+    errors.push({ path: `${path}.${key}`, message: "must be a non-negative integer" });
+  }
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function stringValue(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function repositoryRelativePath(value) {
+  return stringValue(value) && !value.startsWith("/") && !value.split("/").includes("..");
+}

package/state/session-lock.js

@@ -0,0 +1,104 @@
+// factory.lock retains the predecessor's session-lock record shape:
+//   { session, run_id, branch, claimed_at, heartbeat_at }
+// Unlike the brief run-json transition lock, this answers which session owns the
+// whole run and enables resume, steal, or abort. A fresh heartbeat means another
+// session is working; one older than the TTL may be stolen.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeProtectedJsonAtomic } from "../core/atomic-write.js";
+import { rm } from "node:fs/promises";
+import { withRunJsonLock } from "../core/run-lock.js";
+
+export const SESSION_LOCK_FILE = "factory.lock";
+export const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000;
+// `pid` is no longer written, but stays listed so locks written before it was dropped
+// still validate. Removing it would make every pre-existing lock fail the unknown-key
+// check below, read as absent, and let a second session claim a run that is still being
+// worked -- the dangerous direction. Why it was dropped, from #194: the recorded pid was
+// the CLI or the transient shell that invoked it, never the run's owner, so it could not
+// answer the liveness question its presence implied.
+export const SESSION_LOCK_KEYS = Object.freeze([
+  "session", "pid", "run_id", "branch", "claimed_at", "heartbeat_at",
+]);
+
+export class SessionLockHeldError extends Error {
+  constructor(owner) {
+    super(`run '${owner.run_id}' is held by session ${owner.session} (heartbeat ${owner.heartbeat_at})`);
+    this.name = "SessionLockHeldError";
+    this.owner = owner;
+  }
+}
+
+export function readSessionLock(runDir) {
+  try {
+    const value = JSON.parse(readFileSync(join(runDir, SESSION_LOCK_FILE), "utf8"));
+    return isValidLock(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+// "fresh" | "stale" | "absent". The caller routes on this; it is the only
+// question the lock answers.
+export function inspectSessionLock(runDir, { now = Date.now(), ttlMs = DEFAULT_SESSION_TTL_MS } = {}) {
+  const owner = readSessionLock(runDir);
+  if (!owner) return { state: "absent", owner: null };
+  const ageMs = now - Date.parse(owner.heartbeat_at);
+  // A future heartbeat is not evidence of staleness, so it counts as fresh.
+  if (!Number.isFinite(ageMs) || ageMs <= ttlMs) return { state: "fresh", owner };
+  return { state: "stale", owner };
+}
+
+export async function claimSessionLock(runDir, { session, runId, branch, now, ttlMs, force = false } = {}) {
+  return withRunJsonLock(runDir, async () => {
+    if (!session) throw new Error("factory lock requires a session id");
+    const at = new Date(now ?? Date.now()).toISOString();
+    const observed = inspectSessionLock(runDir, { now: now ?? Date.now(), ttlMs });
+    if (observed.state === "fresh" && observed.owner.session !== session && !force) {
+      throw new SessionLockHeldError(observed.owner);
+    }
+    const owner = {
+      session,
+      run_id: runId,
+      branch: branch ?? null,
+      // Re-claiming your own lock preserves when you first took it.
+      claimed_at: observed.owner?.session === session ? observed.owner.claimed_at : at,
+      heartbeat_at: at,
+    };
+    await writeProtectedJsonAtomic(runDir, SESSION_LOCK_FILE, owner);
+    return { ...owner, stolen_from: observed.state === "stale" || force ? observed.owner : null };
+  });
+}
+
+export async function refreshSessionLock(runDir, { session, now } = {}) {
+  return withRunJsonLock(runDir, async () => {
+    const owner = readSessionLock(runDir);
+    if (!owner) throw new Error("no factory.lock to refresh");
+    // Refreshing someone else's lock would silently extend a run you do not own.
+    if (session && owner.session !== session) throw new SessionLockHeldError(owner);
+    const next = { ...owner, heartbeat_at: new Date(now ?? Date.now()).toISOString() };
+    await writeProtectedJsonAtomic(runDir, SESSION_LOCK_FILE, next);
+    return next;
+  });
+}
+
+export async function releaseSessionLock(runDir, { session } = {}) {
+  return withRunJsonLock(runDir, async () => {
+    const owner = readSessionLock(runDir);
+    if (!owner) return { released: false, reason: "absent" };
+    if (session && owner.session !== session) throw new SessionLockHeldError(owner);
+    await rm(join(runDir, SESSION_LOCK_FILE), { force: true });
+    return { released: true, reason: null };
+  });
+}
+
+function isValidLock(value) {
+  return Boolean(value)
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && Object.keys(value).every((key) => SESSION_LOCK_KEYS.includes(key))
+    && typeof value.session === "string" && value.session.trim().length > 0
+    && typeof value.run_id === "string" && value.run_id.trim().length > 0
+    && Number.isFinite(Date.parse(value.claimed_at || ""))
+    && Number.isFinite(Date.parse(value.heartbeat_at || ""));
+}

package/state/transition.js

@@ -0,0 +1,26 @@
+// The sole run.json write path is private to bin/factory.js.
+// The package root exports reads, preserving the plugin's read-only boundary.
+//
+//   lock -> read -> validate -> apply -> validate -> CAS -> reobserve -> CAS -> rename
+//
+// Contracts validate every family before atomic rename replacement.
+// `apply` receives a structured clone, never the lock, file, or rename.
+// Initialization is the only write outside this path and uses create-only publication.
+import { validateRun } from "./schema.js";
+import { coordinateRunJsonTransition } from "../core/write-core.js";
+import { FAMILY_CONTRACTS } from "../core/contracts.js";
+
+export async function transition(runDir, { participants, apply, reobservers, hooks, finalGuard } = {}) {
+  const descriptor = Object.freeze({
+    participants: Object.freeze((participants ?? []).map((entry) => Object.freeze({ ...entry }))),
+    apply,
+  });
+  return coordinateRunJsonTransition(runDir, {
+    contracts: FAMILY_CONTRACTS,
+    descriptor,
+    validateRun,
+    reobservers: reobservers ?? new Map(),
+    atomicWriteHooks: hooks,
+    finalGuard,
+  });
+}