feature-factory 0.8.2 → 0.8.4

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

@@ -99,36 +99,50 @@ must APPROVE before you accept that step. Story, research, and design are not au
 
 Before any intake action, including ticket, story, or design detection, branch intent, run-id
 derivation, manifest or state reads, and every `factory` command, process the raw invocation arguments
-as follows. The platform skill first performs any host-specific placement admission and supplies this
-workflow the unchanged admitted request. Placement is not a run mode.
-
-Ignore leading whitespace. The **mode prefix** is the maximal consecutive sequence of
-whitespace-delimited tokens that are exactly and case-sensitively `--autonomous` or `--headless`.
-The first other token ends the prefix.
-
-1. If both distinct flags occur in that prefix, in either order, return exactly:
+as follows.
+
+**The platform skill owns invocation-option admission, and this workflow never parses the
+invocation.** Each host skill defines the complete leading option prefix its `/feature` invocation
+accepts -- placement, mode, and host options such as `--base` and `--max-retries` -- consumes exactly
+those spans and their separators, and supplies this workflow two things: the **admitted mode tokens**,
+which are the exact case-sensitive `--autonomous` and `--headless` tokens it consumed, and the
+**admitted remainder**, the request bytes beginning at the first token it did not consume, preserved
+unchanged. This workflow never decides where that prefix ends. Placement is not a run mode.
+
+Defining a terminator here would contradict the skill that already applied one, and every option later
+added to a host would become request content on this side only. That is not hypothetical. `--base` and
+`--max-retries` were added to the host skills while this section still ended the prefix at the first
+non-mode token, so the two documents disagreed over whether `--max-retries 5 <run-id>` was an option
+pair or part of the run id. Read alone, this section silently derived the run id `max-retries-5-1606`;
+read alongside the skill, a driver correctly refused to run at all. Both documents governing the same
+bytes is the defect, so only one of them does.
+
+The rules below are host-independent and are stated over the admitted mode tokens and the admitted
+remainder.
+
+1. If both distinct mode tokens were admitted, in either order, return exactly:
    `conflicting mode flags: --autonomous and --headless; choose one`. Return immediately, before any
    intake, run-id derivation, state read, or CLI action. Never fall back to interactive or another
    mode.
-2. Otherwise remove every token in the recognized prefix and its separating whitespace. Use only the
-   unchanged remainder for ticket detection, story content, design detection, branch intent, and
-   run-id derivation.
+2. Otherwise use only the unchanged admitted remainder for ticket detection, story content, design
+   detection, branch intent, and run-id derivation.
 3. Apply exactly one mapping for a new manifest:
    - `--autonomous` maps only to `factory init --mode autonomous`.
    - `--headless` maps only to `factory init --mode headless`.
-   - With no recognized leading mode token, omit `--mode`; existing `factory init` records
+   - With no admitted mode token, omit `--mode`; existing `factory init` records
      `interactive`.
 
 Those three compatibility phrases name init command stems, not runnable invocations. The selected
 fresh-run invocation is fully qualified in Step 0 and ends with `--repo "$RUN_REPO"`.
 
-Repeated copies of one recognized flag are idempotent: remove them all and select that mode once. An
-exact mode token after the first other token is request content and neither selects nor conflicts.
+Repeated copies of one mode token are idempotent: the skill consumes them all and this workflow
+selects that mode once. A mode token the skill did not admit, standing after the first request token,
+is request content and neither selects nor conflicts.
 Natural-language intent, `--interactive`, capitalization variants, abbreviations, assignment or
 punctuation forms, quoted lookalikes, and near misses are request content, not selectors. Do not add a
 generic malformed-option rejection.
 
-After successful nonconflicting admission, reject an empty, whitespace-only, or mode-only remainder
+After successful nonconflicting admission, reject an empty or whitespace-only admitted remainder
 with exactly `missing /feature request; no run created.` This rejection and a mode conflict precede
 run-id derivation and every tool, client, state, or CLI action.
 
@@ -148,12 +162,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.4",
   "description": "Durable, observed control plane for /feature runs. Host-agnostic: no opencode dependency.",
   "type": "module",
   "license": "MIT",