feature-factory 0.8.2 → 0.8.3

package/README.md

@@ -115,6 +115,8 @@ re-initialising the same run id. It is published by a staged, verified swap, so
 snapshot. A failed snapshot is reported and never prevents the park. `blocked`
 and `partial` are not snapshotted, and a snapshot is evidence for recovery rather than a resumable run.
 
+Qualified status reports `park_snapshot` for a parked run: the published path, or `null` when no snapshot
+exists. That is how an outside observer verifies the snapshot happened rather than assuming it.
 Malformed config, malformed payload, a non-zero exit, or unavailable exit status refuses before any
 run effect and never falls back:
 

package/WORKFLOW.md

@@ -148,12 +148,24 @@ resume; invocation flags do not select resumed behavior:
 An inability to ask a human never promotes interactive or headless to autonomous.
 
 Mode result needs-human means parked and explicitly resumable; only completed, partial, and blocked are final.
-Enter the parked stop with factory terminal R needs-human --reason TEXT; leave it only by explicit factory resume R --session $SESSION_ID --repo S, which refuses unless that session already holds a fresh lock: claim, then verify, then resume.
-Immediately after recording a `needs-human` terminalization, and before reporting the park to the operator,
-publish a parked control-plane snapshot exactly as *Parked control-plane snapshot* below requires. A park
-is not reported until that snapshot is published or its failure is recorded in the report.
+**The parked stop is one ordered sequence, and every rule in this document that says a run parks enters
+it.** Those rules name the cause; they do not restate the steps. Execute all three, in order, before
+reporting anything:
+
+1. Enter the parked stop with factory terminal R needs-human --reason TEXT; leave it only by explicit factory resume R --session $SESSION_ID --repo S, which refuses unless that session already holds a fresh lock: claim, then verify, then resume.
+2. Immediately after recording a `needs-human` terminalization, and before reporting the park to the operator,
+   publish a parked control-plane snapshot exactly as *Parked control-plane snapshot* below requires. A park
+   is not reported until that snapshot is published or its failure is recorded in the report.
+3. Report top-level needs-human as parked with its reason and explicit factory resume command.
+
+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
+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.
+
 For top-level needs-human, status exposes the durable next action, but no command may execute it before explicit factory resume.
-Report top-level needs-human as parked with its reason and explicit factory resume command.
 Retain the sandbox for top-level needs-human while parked, then explicitly resume it after the external fix.
 A park that asks a question about the request itself -- a contradiction between criteria, a scope lock,
 or a pinned constraint -- is not fixed by resuming. Resume continues from the existing manifest and

package/bin/factory.js

@@ -4,8 +4,8 @@
 // The orchestrator calls this CLI instead of writing control-plane state directly.
 // Flags are declared per command; unknown options fail rather than becoming missing fields.
 // Schema validation surrounds every state write.
-import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
@@ -153,6 +153,57 @@ function briefDigestFor(decision, state, runDir) {
   return state.plan_digest;
 }
 
+// Observability, not enforcement: the copy stays a driver step, because this CLI is forbidden copy and
+// delete primitives. What this answers has to be exact, and two earlier versions were not. "Does the
+// pathname exist" reported a snapshot from an earlier park as this park's evidence. Matching only `run.json`
+// then proved one file was copied after the current terminalization, not that the publication finished --
+// a driver that created the directory and copied that file first, or an interrupted copy, still read as
+// published. Both were false greens in the exact case this exists to catch, and both were caught in review.
+// So compare the inventory the publication contract already defines, in the same terms it defines it:
+// `.` and every descendant, each recording relative path, type, permission mode, SHA-256 for a regular
+// file and link target for a symlink, sorted lexically by relative path, with unsupported entry types
+// rejected. Two earlier versions of this comparison were narrower than the contract they claimed to check.
+// Recording sizes rather than digests -- on the theory that hashing was too costly for a continuously
+// polled command -- passed a same-length byte change and a mode-only change as faithful. Then walking into
+// the root without recording it passed a snapshot whose own directory mode differed from the plane's. Both
+// reported a tree that fails the contract's verification as published, while the documentation said altered
+// trees yield `null`, and a signal that disagrees with its own description is the thing this whole change
+// exists to remove. Hashing the plane costs about a millisecond; the cost theory was right and its
+// conclusion was wrong. Both caught in review.
+// Every path component is checked with `lstat` and never followed, since `lstat` on the final entry alone
+// still follows intermediate symlinks.
+function planeInventory(root) {
+  const entries = [];
+  const record = (rel, full) => {
+    const stat = lstatSync(full);
+    const mode = (stat.mode & 0o7777).toString(8);
+    if (stat.isSymbolicLink()) entries.push(`${rel} l ${mode} ${readlinkSync(full)}`);
+    else if (stat.isDirectory()) {
+      entries.push(`${rel} d ${mode}`);
+      for (const name of readdirSync(full)) record(rel === "." ? name : `${rel}/${name}`, join(full, name));
+    } else if (stat.isFile()) entries.push(`${rel} f ${mode} ${createHash("sha256").update(readFileSync(full)).digest("hex")}`);
+    else throw new CliError(`unsupported entry type in '${full}'`);
+  };
+  record(".", root);
+  return entries.sort().join("\n");
+}
+
+function observedParkSnapshot(repo, runId, runDir) {
+  const container = dirname(repo);
+  if (basename(container) !== ".factory-sandboxes" || basename(repo) !== runId) return null;
+  const operatorRoot = dirname(container);
+  const candidate = join(operatorRoot, CONTROL_PLANE, ".parked", runId);
+  try {
+    for (const component of [join(operatorRoot, CONTROL_PLANE), join(operatorRoot, CONTROL_PLANE, ".parked"), candidate]) {
+      if (!lstatSync(component).isDirectory()) return null;
+    }
+    if (planeInventory(candidate) !== planeInventory(runDir)) return null;
+    return readFileSync(join(candidate, "run.json")).equals(readFileSync(join(runDir, "run.json"))) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
 function runDirFor(flags, runId) {
   if (!runId) throw new CliError("a <run-id> is required");
   return join(resolve(flags.repo ?? process.cwd()), CONTROL_PLANE, runId);
@@ -903,6 +954,7 @@ const HANDLERS = {
       branch: run.branch,
       pr_base: run.pr_base ?? null,
       publishing_identity: run.publishing_identity ?? null,
+      park_snapshot: run.status === "needs-human" ? observedParkSnapshot(resolve(flags.repo ?? process.cwd()), runId, runDir) : null,
       pr_draft: run.pr_draft ?? true,
       lock: lock.state, dead_lock: run.status === "running" && lock.state === "stale",
       lock_session: lock.owner?.session ?? null,

package/package.json

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