feature-factory 0.8.1 → 0.8.3

package/README.md

@@ -106,6 +106,17 @@ workflow, outcome, or acceptance criteria, so it reaches Gate 1 with nothing to
 non-zero exit instead refuses immediately, names the reference, and creates no session or run. Only the
 resolver author knows which of the two cases it is in, so the contract cannot make the choice for it.
 
+A `needs-human` terminalization is followed by a control-plane snapshot: the driver copies the run
+directory to `$O/.factory/.parked/<R>` immediately after recording the park. A parked run waits for
+outside intervention, and its control plane otherwise exists only inside the sandbox, so anything that
+removed the sandbox destroyed the manifest and every accepted gate with it. `.parked` cannot be a run
+id, so a snapshot never occupies the completed archive at `$O/.factory/<R>` and never blocks
+re-initialising the same run id. It is published by a staged, verified swap, so a failed later park cannot degrade the last good
+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,9 +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.
+**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
@@ -188,6 +203,61 @@ an observably clean tree: `worktree_clean` records false, the suite is skipped,
 classifies `unavailable`, which parks the run. Ignoring the root paths instead is not the fix — `.gitignore`
 is privileged precisely because ignoring a file conceals it from these checks.
 
+### Parked control-plane snapshot
+
+A parked run waits for outside intervention, and its control plane otherwise exists only inside the
+sandbox: the completed handoff is the only thing that archives it, and that handoff is entered only for
+`completed`. So anything that removed the sandbox destroyed the manifest, the approved gates, the ratified
+plan and every review verdict, leaving the run neither resumable nor reconstructable.
+
+Publish the live plane `P` to `$O/.factory/.parked/$R`. Inspect `$O/.factory` and `$O/.factory/.parked` with
+non-following metadata reads, creating each missing parent one directory at a time and requiring any present
+one to be a real directory rather than a symbolic link. Never write through a symlinked parent, and never
+write anywhere but under `$O/.factory/.parked`.
+
+**Publication has exactly one commit point: the rename that puts a verified staging tree onto the canonical
+path.** Every failure rule below is stated relative to it, because "leave the previous snapshot untouched"
+and "clean up the prior copy" are contradictory instructions once that rename has happened.
+
+1. **Preflight.** Require no entry at `$O/.factory/.parked/.staging-$R`. A residual
+   `$O/.factory/.parked/.prior-$R` is the trace of an earlier publication whose cleanup did not finish, not
+   a snapshot to preserve: remove it before staging, and if that removal fails, report it and stop without
+   touching the canonical snapshot or staging anything.
+2. **Stage.** Copy `P` to `.staging-$R`, preserving every entry, its mode, and symlinks as symlinks. `W` is
+   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.
+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
+   succeeds and the second fails, rename `.prior-$R` back onto the canonical path and report: nothing was
+   committed.
+5. **Before the commit point, no publication has occurred.** Any failure leaves the previous canonical
+   snapshot in place — restoring it from `.prior-$R` when it had already been moved — removes only
+   `.staging-$R`, and records the failure in the park report.
+6. **After the commit point, the published snapshot is authoritative and is never rolled back.** Removing
+   `.prior-$R` is cleanup, not part of publication: if it fails, report a cleanup warning naming the
+   residual path and leave the published snapshot exactly as committed. A later park removes that residual
+   at preflight, as step 1 requires.
+
+`.staging-$R` and `.prior-$R` cannot be run ids, so neither is ever a manifest candidate.
+
+Three properties make this safe to do at a park rather than only at completion:
+
+1. `.parked` cannot be a run id, so a snapshot never occupies the completed archive at `$O/.factory/$R` and
+   never becomes a manifest candidate. A run may park, resume, and later complete with its handoff archive
+   unaffected, and relaunching the same run id is not blocked by a snapshot left behind.
+2. It never touches `S`. The snapshot is a copy out; removal remains the completed handoff's guarded step
+   and nothing else's.
+3. A snapshot failure is reported and does not prevent or undo the park. Refusing to park because a copy
+   failed would leave `status: running` with nothing alive, which every health signal misreads — a worse
+   outcome than a missing snapshot.
+
+A snapshot is evidence for recovery, not a resumable run: resume operates on the sandbox manifest. Do not
+publish one for `blocked` or `partial`, which are not resumable, and never treat a snapshot as authority
+over the live plane.
+
 At every interactive gate, `changes: <feedback>` records `changes`, follows
 `changes-at-gate:<name>`, revises only the affected stage, and re-presents it pending. `stop` requires
 qualified status `next: stopped-at-gate:<name>` and releases the driver's lock. This is an unlocked

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.1",
+  "version": "0.8.3",
   "description": "Durable, observed control plane for /feature runs. Host-agnostic: no opencode dependency.",
   "type": "module",
   "license": "MIT",