feature-factory 0.8.6 → 0.8.8

package/WORKFLOW.md

@@ -177,7 +177,8 @@ reporting anything:
 A park that completes only step 1 is an unreported park with no recovery evidence, which is the state
 this sequence exists to prevent. Verify step 2 the way an outside observer would: qualified status
 reports `park_snapshot` as the published path, or `null` when no snapshot exists. Status reports the path
-only while the snapshot is a complete copy of the live plane by the step 3 inventory and its manifest still
+only while the snapshot is a complete copy of the live plane by the step 3 inventory — `factory.lock`
+excluded, since a heartbeat may land between the copy and the read — and its manifest still
 matches the live one byte for byte, so `null` also covers an interrupted or altered copy and a snapshot
 left by an earlier park: neither is evidence for this park. Publishing again is what makes it correspond.
 
@@ -243,7 +244,12 @@ and "clean up the prior copy" are contradictory instructions once that rename ha
    outside `P`; do not copy slice worktrees or any other part of `S`.
 3. **Verify.** Build source and destination inventories exactly as the completed archive does — every
    entry's relative path, type and mode, a SHA-256 for each regular file, a link target for each symlink,
-   sorted lexically — and require exact equality. An unverified staging tree is never published.
+   sorted lexically — and require exact equality, **excluding the plane-root `factory.lock` only**. That
+   one entry is session liveness rather than run state and is the only thing in the plane designed to
+   change on a timer, so comparing it fails whenever a heartbeat lands between reading the source and
+   reading the copy. The exclusion is that exact path and nothing else: a `factory.lock` anywhere below
+   the plane root is run state and must match. Qualified status excludes the same single path for the same
+   reason. An unverified staging tree is never published.
 4. **Commit.** With no snapshot at the canonical path, rename `.staging-$R` onto it; that rename is the
    commit point. With one present, first rename the canonical snapshot to `.prior-$R`, then rename
    `.staging-$R` onto the canonical path; that second rename is the commit point. If the first rename

package/bin/factory.js

@@ -10,7 +10,7 @@ import { pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { readFileSync } from "node:fs";
-import { nextAction, readRun, readRunUnchecked } from "../state/index.js";
+import { nextAction, nextActionRecord, readRun, readRunUnchecked } from "../state/index.js";
 import { transition } from "../state/transition.js";
 import { buildEvidence, deriveReviewReady, EVIDENCE_KEYS, evidenceRef, git, observeAncestry, observeCleanliness, observeTrackedCleanliness, observeWorktree, privilegedPaths, proveInitContainment, resolveWorktree, runBootstrap, unownedPaths } from "../observe/index.js";
 import { assertPublicationReady, assertReviewBinding, observeMergeProof, readEvidence, readReview, readValidatorReview } from "../observe/review.js";
@@ -23,7 +23,7 @@ import { resolveSpawnExecutable } from "../core/executable.js";
 import { dispatchInitPublication } from "./init-publication.js";
 import { CONTROL_PLANE, SCHEMA_VERSION, GATE_NAMES, GATE_STATUSES, MODES, SLICE_STATUSES, STEP_STATUSES, TERMINAL_STATUSES, repositoryRelativePath, validateRun } from "../state/schema.js";
 import {
-  claimSessionLock, inspectSessionLock, refreshSessionLock, releaseSessionLock, SessionLockHeldError,
+  claimSessionLock, inspectSessionLock, refreshSessionLock, releaseSessionLock, SESSION_LOCK_FILE, SessionLockHeldError,
 } from "../state/session-lock.js";
 
 export const COMMANDS = Object.freeze({
@@ -175,6 +175,15 @@ function briefDigestFor(decision, state, runDir) {
 function planeInventory(root) {
   const entries = [];
   const record = (rel, full) => {
+    // The session lock is liveness, not run state, and it is the one entry in the plane designed to change
+    // on a timer. Comparing it made every snapshot invalid within one heartbeat: a live park published a
+    // complete, byte-correct plane and `status` reported `park_snapshot: null` eleven seconds later,
+    // because the copy held `heartbeat_at` 23:28:25 and the plane had moved to 23:28:36. The whole point
+    // of the field was to answer "did the driver publish it", and it answered "no" for a snapshot that was
+    // there -- the same disagree-with-your-own-description defect the 0.8.3 work existed to remove,
+    // reintroduced by the check built to remove it. Every existing test publishes and reads back with no
+    // heartbeat in between, which is why three review rounds and a real park all missed it.
+    if (rel === SESSION_LOCK_FILE) return;
     const stat = lstatSync(full);
     const mode = (stat.mode & 0o7777).toString(8);
     if (stat.isSymbolicLink()) entries.push(`${rel} l ${mode} ${readlinkSync(full)}`);
@@ -963,12 +972,31 @@ const HANDLERS = {
       pr_draft: run.pr_draft ?? true,
       lock: lock.state, dead_lock: run.status === "running" && lock.state === "stale",
       lock_session: lock.owner?.session ?? null,
-      gates: Object.fromEntries(GATE_NAMES.filter((name) => run.gates[name]).map((name) => [name, run.gates[name].status])),
-      steps: run.steps.map((step) => `${step.agent}:${step.status}(${step.attempts})`),
-      slices: run.slices.map((slice) => `${slice.id}:${slice.status}(${slice.attempts})`),
-      validator: run.validator?.verdict ?? null,
+      // The whole gate record, not just its status. `at` and `artifact` were dropped here while sitting
+      // intact in `run.json` -- and `at` is what tells a controller whether "approved" happened a minute
+      // ago or three hours ago, which is most of what "is this run stuck" means.
+      gates: Object.fromEntries(GATE_NAMES.filter((name) => run.gates[name])
+        .map((name) => [name, { status: run.gates[name].status, at: run.gates[name].at ?? null, artifact: run.gates[name].artifact ?? null }])),
+      // Structured, not `${agent}:${status}(${attempts})`. Attempts are the field a controller reads to
+      // decide whether an attempt was consumed, and reaching them meant regexing a display string out of
+      // a JSON contract. Nothing in the suite asserted the string form, so it was a public shape with no
+      // coverage -- which is how a rendering artifact survived in a machine-readable payload. The content
+      // is unchanged; only the shape is. Breaking for anyone parsing the strings, which is safe here
+      // because an exact-match `FACTORY_VERSION` pin already forces consumers to move deliberately.
+      steps: run.steps.map((step) => ({ agent: step.agent, status: step.status, attempts: step.attempts })),
+      slices: run.slices.map((slice) => ({ id: slice.id, status: slice.status, attempts: slice.attempts })),
+      // Same narrowing: the record carries `report`, `reviewed_head` and `loops`, and only the verdict
+      // came out. `loops` says whether validation is converging; `reviewed_head` says what it judged.
+      validator: run.validator
+        ? { verdict: run.validator.verdict, report: run.validator.report ?? null,
+            reviewed_head: run.validator.reviewed_head ?? null, loops: run.validator.loops ?? null }
+        : null,
       pr_url: run.pr_url,
       terminal_result: run.terminal_result,
+      // Both, deliberately. `next_action` is the machine answer; `next` is its rendering, derived from the
+      // same record by one formatter so they cannot drift, and kept because the driver contract, the
+      // sidebar and a lot of prose name `next: gate:story`.
+      next_action: nextActionRecord(run),
       next: nextAction(run),
     });
   },
@@ -1163,7 +1191,8 @@ const HANDLERS = {
     });
     if (outcome?.refusal) throw new CliError(`${outcome.refusal}; run remains needs-human and its historical terminal result is preserved`);
     return emit(flags, {
-      run_id: runId, status: next.status, terminal_result: next.terminal_result, next: nextAction(next),
+      run_id: runId, status: next.status, terminal_result: next.terminal_result,
+      next_action: nextActionRecord(next), next: nextAction(next),
     });
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-factory",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "Durable, observed control plane for /feature runs. Host-agnostic: no opencode dependency.",
   "type": "module",
   "license": "MIT",

package/state/index.js

@@ -28,11 +28,11 @@ export function readRunUnchecked(runDir) {
 
 function nextSliceAction(slices) {
   const blockedSlice = slices.find((slice) => slice.status === "blocked");
-  if (blockedSlice) return `blocked-slice:${blockedSlice.id}`;
+  if (blockedSlice) return { kind: "blocked-slice", subject: blockedSlice.id };
   const activeSlice = slices.find((slice) => ["running", "review"].includes(slice.status));
-  if (activeSlice) return `observe-slice:${activeSlice.id}`;
+  if (activeSlice) return { kind: "observe-slice", subject: activeSlice.id };
   const pendingSlice = slices.find((slice) => slice.status === "pending");
-  return pendingSlice ? `dispatch-slice:${pendingSlice.id}` : undefined;
+  return pendingSlice ? { kind: "dispatch-slice", subject: pendingSlice.id } : undefined;
 }
 
 // The single answer to "what happens next". Both `factory status` and the opencode
@@ -42,23 +42,35 @@ function nextSliceAction(slices) {
 // 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}`;
+// `{kind, subject}`, because the answer is two facts and a consumer that must split a string on `:` to
+// recover them is parsing a rendering. `subject` is null for the kinds that name no target.
+export function nextActionRecord(run) {
+  if (["completed", "partial", "blocked"].includes(run.status)) return { kind: "terminal", subject: run.status };
   const openStep = run.steps.find((step) => step.status !== "accepted");
+  const stepAction = openStep ? { kind: "step", subject: openStep.agent } : null;
   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 (gate === undefined) return sliceAction ?? stepAction ?? { kind: "gate", subject: name };
+    if (gate.status === "pending") return { kind: "gate", subject: name };
+    if (gate.status === "stop") return { kind: "stopped-at-gate", subject: name };
+    if (gate.status === "changes") return { kind: "changes-at-gate", subject: name };
+    if (name === "brief" && gate.status === "approved" && run.slices.length === 0) return { kind: "seed-slices", subject: null };
   }
   if (sliceAction) return sliceAction;
-  if (openStep) return `step:${openStep.agent}`;
-  if (!run.pr_url) return "pr";
-  return "complete";
+  if (stepAction) return stepAction;
+  if (!run.pr_url) return { kind: "pr", subject: null };
+  return { kind: "complete", subject: null };
+}
+
+// The string form is DERIVED from the record rather than computed beside it, so the two cannot disagree.
+// Retained because the driver contract, the sidebar and a great deal of prose all name `next: gate:story`,
+// and because a human-facing label is a fair thing for a CLI to keep -- as long as it is a projection of
+// the structured answer and not a second implementation of it.
+export function nextAction(run) {
+  const { kind, subject } = nextActionRecord(run);
+  return subject === null ? kind : `${kind}:${subject}`;
 }