feature-factory 0.10.4 → 0.10.5

package/README.md

@@ -47,11 +47,13 @@ resolved Git top level:
 }
 ```
 
-The root has two required properties, `resolve` and `verify`, and five optional properties: `publish`,
-`pr_draft`, `verify_timeout_ms`, `bootstrap`, and `bootstrap_timeout_ms`. Required commands and any present
+The root has two required properties, `resolve` and `verify`, and six optional properties: `publish`,
+`pr_draft`, `verify_timeout_ms`, `bootstrap`, `bootstrap_timeout_ms`, and `max_retries`. Required commands and any present
 `publish` or `bootstrap` are non-empty strings. There is no `publishing_identity` key, and a file carrying one is malformed because the
 optional set is closed. A present `pr_draft` must be a JSON boolean and omission means `true`. Both timeouts are
 positive safe integers. `bootstrap_timeout_ms` requires `bootstrap`.
+A present `max_retries` must be a positive integer. It is the run's attempt budget when `init` runs
+without `--max-retries`, which still outranks it; omission leaves the default `3`.
 Each omitted timeout independently defaults to `900000`; neither shares the other's budget. The file is
 operator-owned, committed, and protected as a privileged path: a run cannot create, write, merge,
 archive, package, or repair it.
@@ -66,9 +68,9 @@ value stops the run instead of publishing under whatever credential the host hap
 it from `gh`, the token, stored authentication, or Git configuration: an expectation read from the
 credential being checked would always match.
 
-Validation refuses the first matching defect in this order: unreadable or invalid JSON, a non-object root, or unknown keys; invalid `pr_draft`; invalid `bootstrap`; `bootstrap_timeout_ms` without `bootstrap`; invalid `bootstrap_timeout_ms`; invalid `verify_timeout_ms`; missing or invalid required entries; then invalid `publish`.
+Validation refuses the first matching defect in this order: unreadable or invalid JSON, a non-object root, or unknown keys; invalid `pr_draft`; invalid `bootstrap`; `bootstrap_timeout_ms` without `bootstrap`; invalid `bootstrap_timeout_ms`; invalid `verify_timeout_ms`; missing or invalid required entries; invalid `publish`; then invalid `max_retries`.
 
-The named forms are `.factory.json entry 'pr_draft' must be a boolean`, `.factory.json entry 'bootstrap' must be a non-empty string`, `.factory.json entry 'bootstrap_timeout_ms' requires a declared bootstrap command`, `.factory.json entry 'bootstrap_timeout_ms' must be a positive integer`, and `.factory.json entry 'verify_timeout_ms' must be a positive integer`.
+The named forms are `.factory.json entry 'pr_draft' must be a boolean`, `.factory.json entry 'bootstrap' must be a non-empty string`, `.factory.json entry 'bootstrap_timeout_ms' requires a declared bootstrap command`, `.factory.json entry 'bootstrap_timeout_ms' must be a positive integer`, `.factory.json entry 'verify_timeout_ms' must be a positive integer`, and `.factory.json entry 'max_retries' must be a positive integer`.
 
 A present invalid, unreadable, incomplete, wrong-type, whitespace-only, or unknown-property config refuses closed.
 
@@ -287,14 +289,18 @@ report `null`, skips all three guards; an absent config does not affect them.
 
 Before each guard, inherited `GH_TOKEN` must exist and contain at least one character. Missing or empty
 means identity is unobservable without invoking `gh`, the network, stored authentication, credential
-queries, or any fallback. A prepared environment submits exactly this read-only network probe as one
+queries, or any fallback. A prepared environment submits exactly this command as one
 ordinary host shell step with cwd exactly `RUN_REPO`, inherited environment, and no stdin:
 
 ```sh
-gh api --method GET /user --jq .login
+factory identity "$R" --json --repo "$RUN_REPO"
 ```
 
-The direct stdout bytes, stderr bytes, and numeric status are parsed strictly. Only numeric zero, empty
+The CLI runs the read-only network probe `gh api --method GET /user --jq .login` itself, with separate
+stdout and stderr pipes, so a host whose shell tool combines the two streams can still run the guard. It
+returns JSON whose `reason` is null on a match and is otherwise the complete rendered park reason.
+
+The probe's stdout bytes, stderr bytes, and numeric status are parsed strictly. Only numeric zero, empty
 stderr, and exactly one ASCII GitHub login plus one LF are observable; the required LF alone is removed,
 then the raw login is compared exactly and case-sensitively with the raw declaration. `gh auth status`
 does not prove the publishing identity.

package/WORKFLOW.md

@@ -547,8 +547,8 @@ The optional repository-owned file is `$O/.factory.json`:
 ```
 
 The root must be a JSON object with the two required own properties `resolve` and `verify`,
-plus only the optional own properties `publish`, `pr_draft`, `verify_timeout_ms`, `bootstrap`, and
-`bootstrap_timeout_ms`. `resolve`, `verify`, `publish`, and `bootstrap` are command strings; every present
+plus only the optional own properties `publish`, `pr_draft`, `verify_timeout_ms`, `bootstrap`,
+`bootstrap_timeout_ms`, and `max_retries`. `resolve`, `verify`, `publish`, and `bootstrap` are command strings; every present
 command must be non-empty. `publish` was required and invoked nowhere until this release, so every
 consumer wrote a command that could not run. It is optional now and contributes only the file candidate
 to the one Step 6 publishing selection. Inherited `FACTORY_PUBLISHING_COMMAND` or the default may win, so
@@ -559,9 +559,10 @@ key is malformed, because the optional set above is closed. `pr_draft` must be a
 when present and defaults to `true` when absent. Both timeout values must be positive
 safe integers when present, and `bootstrap_timeout_ms` is valid only with a declared `bootstrap`.
 `verify_timeout_ms` and `bootstrap_timeout_ms` each independently default to `900000` milliseconds;
-neither timeout shares or consumes the other's budget.
+neither timeout shares or consumes the other's budget. A present `max_retries` must be a positive integer. It is the run's attempt budget when `init` runs
+without `--max-retries`, which still outranks it; omission leaves the default `3`.
 
-Validation refuses the first matching defect in this order: unreadable or invalid JSON, a non-object root, or unknown keys; invalid `pr_draft`; invalid `bootstrap`; `bootstrap_timeout_ms` without `bootstrap`; invalid `bootstrap_timeout_ms`; invalid `verify_timeout_ms`; missing or invalid required entries; then invalid `publish`.
+Validation refuses the first matching defect in this order: unreadable or invalid JSON, a non-object root, or unknown keys; invalid `pr_draft`; invalid `bootstrap`; `bootstrap_timeout_ms` without `bootstrap`; invalid `bootstrap_timeout_ms`; invalid `verify_timeout_ms`; missing or invalid required entries; invalid `publish`; then invalid `max_retries`.
 
 Do not use the obsolete summary “Validation refuses the first matching defect in this order: unreadable or invalid JSON, a non-object root, or unknown keys; invalid `bootstrap`; `bootstrap_timeout_ms` without `bootstrap`; invalid `bootstrap_timeout_ms`; invalid `verify_timeout_ms`; then missing or invalid required entries.” because it omits the earlier `pr_draft` check.
 
@@ -1073,53 +1074,41 @@ reconciliation, reading `status.next`, dispatch, or any transition. For a parked
 immediately after explicit resume has been verified `running` with unchanged historical result, real
 next action, and the same fresh owner. No operation may intervene on either side of this guard.
 
-At every one of the three guards, before submitting a host shell step, inspect only the inherited
-environment value and require `GH_TOKEN` to exist and contain at least one character. Missing or empty
-`GH_TOKEN` is immediately the same unobservable reason below. Do not invoke `gh`, hit the network,
-inspect stored authentication, query or attempt credentials, or run any fallback in that case.
-
-After that preflight succeeds, submit exactly this command as one ordinary host shell step with cwd
-exactly `RUN_REPO`, the inherited environment including that nonempty `GH_TOKEN`, and no stdin:
+At every one of the three guards, submit exactly this command as one ordinary host shell step with cwd
+exactly `RUN_REPO`, the inherited environment, and no stdin:
 
 ```sh
-gh api --method GET /user --jq .login
+factory identity "$R" --json --repo "$RUN_REPO"
 ```
 
-Use the host result directly as three separate values: exact stdout bytes, exact stderr bytes, and the
-numeric status. Do not use command substitution, pipes, redirection, shell capture variables, temporary
-files, nested capture, retry, fallback, `gh auth`, credential queries, Git configuration, a token in
-argv, or persistence of output or diagnostics. The real command is a read-only network observation.
-
-The identity is observable only when status is numeric zero, stderr has exactly zero bytes, and stdout
-is exactly one ASCII login followed by exactly one LF byte. The login grammar is
-`^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$`. Every other status or byte sequence is unobservable;
-do not trim, decode-and-normalize, retry, or recover a partial value. Remove only the required final LF
-from an observable value, then compare the raw declared and observed strings exactly and
-case-sensitively before rendering either one.
-
-Render a value for the reason with the deterministic ASCII-only JSON-string renderer. Surround it with
-double quotes. Emit printable ASCII U+0020 through U+007E literally except quote and backslash, which
-use `\"` and `\\`. Use the fixed JSON short escapes `\b`, `\t`, `\n`, `\f`, and `\r` for U+0008,
-U+0009, U+000A, U+000C, and U+000D. Render every other UTF-16 code unit outside U+0020 through U+007E
-as lowercase `\uXXXX`. A non-BMP code point therefore renders as its two surrogate units, and an
-unpaired surrogate renders as its one unit. Leave slash unescaped. This covers C0, C1, DEL, U+0085,
-U+2028, U+2029, and non-BMP input without a literal non-ASCII or control byte.
+The CLI owns the observation, so the verdict does not depend on what the host's shell tool reports. It
+refuses without invoking `gh` when inherited `GH_TOKEN` is missing or empty. Otherwise it runs the
+read-only network observation `gh api --method GET /user --jq .login` with separate stdout and stderr pipes,
+accepts only numeric status zero, zero-byte stderr, and exactly one ASCII login matching
+`^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$` followed by one LF, and compares it exactly and
+case-sensitively with the recorded `publishing_identity`. A host whose shell tool combines stdout and
+stderr can run this guard; it could never run the probe itself.
 
-An observable unequal value uses exactly:
+Require exit zero and one JSON object. `reason: null` passes the guard. A non-null `reason` is the
+complete already-rendered ASCII park reason, rendered with deterministic ASCII-only JSON strings, and is
+exactly one of:
 
 ```text
 publishing identity mismatch: declared <declared-ascii-json>, observed <observed-ascii-json>; authenticate as <declared-ascii-json> and retry.
 ```
 
-An unobservable result uses exactly:
-
 ```text
 publishing identity unobservable: declared <declared-ascii-json>; launch with inherited GH_TOKEN for <declared-ascii-json> as documented in OPERATING.md and retry.
 ```
 
+Use the returned `reason` exactly; do not re-render, trim, or edit it. Never run `gh` yourself for this
+guard, retry, fall back to stored authentication, or put a token in argv. A nonzero exit or output that is
+not that JSON object is a failed guard: perform no further operation and report only
+`Outcome: retained-lock-error`.
+
 Never expose the token, raw stdout or stderr, diagnostics, status, command text, target, helper output,
 or environment. On either reason, quiesce every builder, tool, background task, and heartbeat call.
-Bind `PRE_QUOTING_REASON` to the complete already-rendered ASCII reason. Encode it as one deterministic
+Bind `PRE_QUOTING_REASON` to the complete already-rendered ASCII reason the CLI returned. Encode it as one deterministic
 POSIX shell token by surrounding the complete reason with single quotes and replacing every literal
 `'` inside it with the exact shell sequence `'\''`. Use that encoded token as the sole `--reason`
 argument in the host shell command string:
@@ -2168,12 +2157,12 @@ this is not a claim that a target is unobservable. Use the same three exact reda
 from Step 0.
 
 With `DECLARED_PUBLISHING_IDENTITY`, immediately after exact target equality and before the unchanged
-push, run the same ordinary host observation under its exact cwd, environment, no-stdin, direct-result,
-validation, rendering, redaction, and parking rules. No operation may intervene between equality, this
+push, run the same identity guard command under its exact cwd, environment, no-stdin, verdict,
+redaction, and parking rules. No operation may intervene between equality, this
 guard, and the push:
 
 ```sh
-gh api --method GET /user --jq .login
+factory identity "$R" --json --repo "$RUN_REPO"
 ```
 
 Publish the fully qualified recorded feature ref from `RUN_REPO`, run `gh` from `O` with that exact head
@@ -2183,7 +2172,7 @@ legacy local runs use `O` through the selection already made in Step 0:
 
 ```sh
 git -C "$RUN_REPO" push origin "refs/heads/$FEATURE_BRANCH:refs/heads/$FEATURE_BRANCH"
-gh api --method GET /user --jq .login
+factory identity "$R" --json --repo "$RUN_REPO"
 (
   cd "$O"
   if [ "$PR_DRAFT" = true ]; then

package/bin/factory.js

@@ -14,6 +14,7 @@ import { nextAction, nextActionRecord, readRun, readRunUnchecked } from "../stat
 import { transition } from "../state/transition.js";
 import { RUN_JSON_LOCK_DIR, withRunJsonLock } from "../core/run-lock.js";
 import { buildEvidence, deriveReviewReady, EVIDENCE_KEYS, evidenceRef, git, observeAncestry, observeCleanliness, observeTrackedCleanliness, observeWorktree, privilegedPaths, proveInitContainment, resolveWorktree, runBootstrap, unownedPaths } from "../observe/index.js";
+import { identityReason, observeIdentity } from "../observe/identity.js";
 import { assertPublicationReady, assertReviewBinding, isApproving, observeMergeProof, readEvidence, readReview, readValidatorReview } from "../observe/review.js";
 import { readRepositoryConfig, RepositoryConfigError } from "../observe/repository-config.js";
 import { reverifyRepair } from "../observe/repair-reverification.js";
@@ -60,6 +61,7 @@ export const COMMANDS = Object.freeze({
   pr: Object.freeze(["--repo", "--url", "--now", "--json"]),
   "reverify-repair": Object.freeze(["--repo", "--now", "--json"]),
   "effective-push": Object.freeze([]),
+  identity: Object.freeze(["--repo", "--json"]),
 });
 
 const BOOLEAN_FLAGS = new Set(["--json", "--repository-verify"]);
@@ -82,7 +84,7 @@ export async function run(argv) {
   if (!Object.hasOwn(COMMANDS, command)) throw new CliError(`unknown command '${command}' (try --help)`);
   const { positional, flags } = parse(command, rest);
   const handler = HANDLERS[command];
-  if (["init", "status", "snapshot", "lock", "heartbeat", "effective-push"].includes(command)) return handler(positional, flags);
+  if (["init", "status", "snapshot", "lock", "heartbeat", "effective-push", "identity"].includes(command)) return handler(positional, flags);
   const repo = resolve(flags.repo ?? process.cwd()), runId = positional[0];
   if (command === "restore") {
     const live = [join(repo, CONTROL_PLANE, runId), join(repo, ".factory-sandboxes", runId, CONTROL_PLANE, runId)]
@@ -1281,6 +1283,16 @@ const HANDLERS = {
     throw new CliError("factory lock requires <claim|steal|release>");
   },
 
+  // Read-only: no lock, no state write. The driver parks with `reason` when it is non-null.
+  async identity(positional, flags) {
+    if (positional.length !== 1) throw new CliError("factory identity requires exactly <run-id>");
+    const [runId] = positional, run = readRun(runDirFor(flags, runId)), declared = run.publishing_identity ?? null;
+    if (declared === null) return emit(flags, { run_id: runId, publishing_identity: null, checked: false, reason: null });
+    const observed = observeIdentity(resolve(flags.repo ?? process.cwd()));
+    return emit(flags, { run_id: runId, publishing_identity: declared, checked: true, observable: observed !== null,
+      reason: identityReason(declared, observed) });
+  },
+
   async heartbeat([runId], flags) {
     const runDir = runDirFor(flags, runId);
     const owner = await refreshSessionLock(runDir, {
@@ -1727,7 +1739,9 @@ export async function dispatchInit(positional, flags, operations = INIT_OPERATIO
   proveContainedBranch();
   let run;
   try {
-    run = validateRun({ ...candidate, pr_base: prBase, pr_draft: config?.prDraft ?? true, ...bootstrapEvidence });
+    // An explicit `--max-retries` outranks the committed `.factory.json` default, which outranks 3.
+    const configuredRetries = flags.maxRetries === undefined && config?.maxRetries ? { max_retries: config.maxRetries } : {};
+    run = validateRun({ ...candidate, ...configuredRetries, pr_base: prBase, pr_draft: config?.prDraft ?? true, ...bootstrapEvidence });
   } catch (error) {
     throw new CliError(`final manifest validation failed for sandbox '${S}'; sandbox was retained`, { cause: error });
   }
@@ -1873,6 +1887,7 @@ function usage() {
   factory resume <run-id> --session ID [--now ISO]
   factory restore <run-id> --repo OPERATOR --from refs/remotes/REMOTE/BRANCH [--now ISO]
   factory snapshot <run-id> --repo OPERATOR
+  factory identity <run-id> [--repo PATH] [--json]
   factory reverify-repair <run-id> <repair-record-id> [--repo PATH] [--now ISO] [--json]
   factory lock <run-id> <claim|steal|release> --session ID [--ttl-ms N]
   factory heartbeat <run-id> --session ID

package/observe/identity.js

@@ -0,0 +1,44 @@
+import { spawnSync } from "node:child_process";
+
+// Enforcement (false green): publishing under an account other than the run's recorded identity. This
+// was driver prose that required the host to return stdout, stderr and status separately; Prime's bash
+// returns them combined, so a compliant Prime driver could never observe the identity (#365). The CLI
+// owns the pipes now, so the verdict no longer depends on what the host's shell tool can report.
+export const IDENTITY_ARGV = Object.freeze(["api", "--method", "GET", "/user", "--jq", ".login"]);
+const LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/u;
+const SHORT = new Map([[8, "\\b"], [9, "\\t"], [10, "\\n"], [12, "\\f"], [13, "\\r"]]);
+
+// Deterministic ASCII-only JSON string: printable ASCII literal except quote and backslash, the fixed
+// short escapes, and every other UTF-16 code unit as lowercase \uXXXX. Slash stays unescaped.
+export function asciiJson(value) {
+  let rendered = "\"";
+  for (let index = 0; index < value.length; index += 1) {
+    const unit = value.charCodeAt(index);
+    if (SHORT.has(unit)) rendered += SHORT.get(unit);
+    else if (unit === 34 || unit === 92) rendered += `\\${value[index]}`;
+    else if (unit >= 0x20 && unit <= 0x7e) rendered += value[index];
+    else rendered += `\\u${unit.toString(16).padStart(4, "0")}`;
+  }
+  return `${rendered}"`;
+}
+
+// Observable only as numeric zero, zero-byte stderr, and exactly one login plus one LF. Nothing is
+// trimmed, retried, or recovered from a partial value.
+export function classifyIdentity({ status, stdout, stderr }) {
+  if (status !== 0 || !Buffer.isBuffer(stdout) || !Buffer.isBuffer(stderr) || stderr.length !== 0) return null;
+  if (stdout.length < 2 || stdout[stdout.length - 1] !== 10 || stdout.subarray(0, -1).some((byte) => byte > 0x7f)) return null;
+  const login = stdout.subarray(0, -1).toString("ascii");
+  return LOGIN.test(login) ? login : null;
+}
+
+export function identityReason(declared, observed) {
+  const name = asciiJson(declared);
+  if (observed === null) return `publishing identity unobservable: declared ${name}; launch with inherited GH_TOKEN for ${name} as documented in OPERATING.md and retry.`;
+  return observed === declared ? null : `publishing identity mismatch: declared ${name}, observed ${asciiJson(observed)}; authenticate as ${name} and retry.`;
+}
+
+// A missing or empty GH_TOKEN never reaches gh, the network, or stored authentication.
+export function observeIdentity(cwd, env = process.env, timeout = 60000) {
+  if (typeof env.GH_TOKEN !== "string" || env.GH_TOKEN.length === 0) return null;
+  return classifyIdentity(spawnSync("gh", IDENTITY_ARGV, { cwd, env, stdio: ["ignore", "pipe", "pipe"], timeout }));
+}

package/observe/repository-config.js

@@ -21,7 +21,7 @@ export function parseRepositoryConfig(bytes) {
   // not. It is optional now and consumed when present, so the key means what it says either way.
   const requiredKeys = ["resolve", "verify"];
   const optionalCommandKeys = ["publish"];
-  const allowedKeys = [...requiredKeys, ...optionalCommandKeys, "pr_draft", "verify_timeout_ms", "bootstrap", "bootstrap_timeout_ms"];
+  const allowedKeys = [...requiredKeys, ...optionalCommandKeys, "pr_draft", "verify_timeout_ms", "bootstrap", "bootstrap_timeout_ms", "max_retries"];
   if (!config || typeof config !== "object" || Array.isArray(config)
     || Object.keys(config).some((keyName) => !allowedKeys.includes(keyName))) {
     throw new RepositoryConfigError("invalid .factory.json");
@@ -53,8 +53,14 @@ export function parseRepositoryConfig(bytes) {
     && (typeof config[keyName] !== "string" || !config[keyName].trim()))) {
     throw new RepositoryConfigError("invalid .factory.json: entry 'publish' must be a non-empty string");
   }
+  // A project default for `init --max-retries`, so it need not ride on every invocation. Instruction, not
+  // enforcement: more attempts are more reviewed work, never an unearned merge. A present value is still
+  // checked, because a key that is silently ignored reads as a budget that took effect.
+  if (Object.hasOwn(config, "max_retries") && (!Number.isSafeInteger(config.max_retries) || config.max_retries <= 0)) {
+    throw new RepositoryConfigError("invalid .factory.json: entry 'max_retries' must be a positive integer");
+  }
   const parsed = { command: config.verify, timeoutMs: config.verify_timeout_ms ?? DEFAULT_REPOSITORY_VERIFY_TIMEOUT_MS,
-    prDraft: config.pr_draft ?? true };
+    prDraft: config.pr_draft ?? true, ...(Object.hasOwn(config, "max_retries") ? { maxRetries: config.max_retries } : {}) };
   return hasBootstrap ? { ...parsed, bootstrapCommand: config.bootstrap,
     bootstrapTimeoutMs: config.bootstrap_timeout_ms ?? DEFAULT_BOOTSTRAP_TIMEOUT_MS } : parsed;
 }

package/package.json

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