feature-factory 0.10.3 → 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.
 
@@ -258,8 +260,9 @@ own the same path. Duplicate, target-already-owned, malformed, privileged, repla
 requests refuse atomically. Resume never amends or reseeds. A merge continues to refuse every unamended
 or privileged changed path.
 
-A parked slice that exhausted its effective limit can receive exactly one audited extension through
-`factory grant-retry <run-id> <slice-id> --scope slice|all --reason <text> --session <id> --repo <sandbox>`.
+A parked slice that exhausted its effective limit can be reopened for one more attempt through
+`factory grant-retry <run-id> <slice-id> --scope slice|all [--max-retries N] --reason <text> --session <id> --repo <sandbox>`;
+`--max-retries` (with `all` only) sets the new run-wide limit in one call instead of raising it by one.
 Slice scope raises only the target's additive allowance. All scope raises `max_retries` for pending later
 waves too, but refuses when another slice is blocked or an exhausted post-merge repair record exists. Both
 scopes reopen only the named slice after exact owner, snapshot, REJECT, evidence, base, current clean head,
@@ -286,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

@@ -224,12 +224,14 @@ scope deliberately:
 
 ```sh
 factory grant-retry "$R" "$SLICE_ID" --scope slice --reason "$EXTENSION_REASON" --session "$SESSION_ID" --repo "$RUN_REPO"
-factory grant-retry "$R" "$SLICE_ID" --scope all --reason "$EXTENSION_REASON" --session "$SESSION_ID" --repo "$RUN_REPO"
+factory grant-retry "$R" "$SLICE_ID" --scope all [--max-retries "$N"] --reason "$EXTENSION_REASON" --session "$SESSION_ID" --repo "$RUN_REPO"
 ```
 
-`slice` raises only that slice's additive allowance. `all` raises the run-wide default, including every
-pending later wave, but still reopens only `SLICE_ID`; it refuses while another slice is blocked or an
-exhausted post-merge repair exists. Both scopes require `blocked@N` exactly at the current effective limit;
+`slice` raises only that slice's additive allowance by one. `all` raises the run-wide default, including
+every pending later wave, but still reopens only `SLICE_ID`; it refuses while another slice is blocked or an
+exhausted post-merge repair exists. `all` raises by one unless `--max-retries N` sets the new run-wide limit
+directly; `N` must exceed the current limit. Choose `N` for the whole remaining plan: once granted, later
+rejections below it retry without another operator grant. Both scopes require `blocked@N` exactly at the current effective limit;
 a matching REJECT, evidence, immutable base and live clean branch head; the exact fresh lock owner; a
 complete current park snapshot; and immutable attempt-N review and evidence archives. A legacy run missing
 an archive gets a preparation-only refusal: publish the changed plane and invoke the grant again. They
@@ -545,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
@@ -557,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.
 
@@ -1071,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:
@@ -2166,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
@@ -2181,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";
@@ -40,7 +41,7 @@ export const COMMANDS = Object.freeze({
   status: Object.freeze(["--repo", "--json"]),
   "amend-paths": Object.freeze(["--repo", "--add", "--reason", "--session", "--now", "--json"]),
   resume: Object.freeze(["--repo", "--session", "--now", "--json"]),
-  "grant-retry": Object.freeze(["--repo", "--scope", "--reason", "--session", "--now", "--json"]),
+  "grant-retry": Object.freeze(["--repo", "--scope", "--max-retries", "--reason", "--session", "--now", "--json"]),
   restore: Object.freeze(["--repo", "--from", "--now", "--json"]),
   snapshot: Object.freeze(["--repo", "--json"]),
   decide: Object.freeze(["--repo", "--text", "--session", "--now", "--json"]),
@@ -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)]
@@ -799,11 +801,16 @@ const HANDLERS = {
     if (positional.length !== 2) throw new CliError("factory grant-retry requires exactly <run-id> <slice-id>");
     const [runId, sliceId] = positional;
     if (!RETRY_EXTENSION_SCOPES.includes(flags.scope)) throw new CliError(`factory grant-retry requires --scope ${RETRY_EXTENSION_SCOPES.join("|")}`);
+    if (flags.maxRetries !== undefined && flags.scope !== "all") throw new CliError("factory grant-retry --max-retries requires --scope all");
     if (typeof flags.reason !== "string" || !flags.reason.trim()) throw new CliError("factory grant-retry requires nonblank --reason <text>");
     if (typeof flags.session !== "string" || !flags.session.trim()) throw new CliError("factory grant-retry requires nonblank --session <id>");
     const runDir = runDirFor(flags, runId), repo = resolve(flags.repo ?? process.cwd());
     const boundBytes = readFileSync(join(runDir, "run.json")), current = validateRun(JSON.parse(boundBytes.toString("utf8")));
     if (current.status !== "needs-human") throw new CliError(`factory grant-retry requires current status needs-human; found '${current.status}'`);
+    // Instruction, not enforcement, on the size: a higher run-wide limit buys more reviewed attempts, never an
+    // unearned merge. Enforced only that it rises, since the grant must reopen the exhausted slice at N+1.
+    const grantedMax = flags.scope === "all" ? integer(flags.maxRetries, current.max_retries + 1, "--max-retries") : current.max_retries;
+    if (flags.scope === "all" && grantedMax <= current.max_retries) throw new CliError(`grant-retry --max-retries must exceed the current run-wide limit ${current.max_retries}`);
     const owner = assertFreshSessionOwner(runDir, runId, flags.session, "grant-retry"), at = stamp(flags);
     if (Date.parse(at) <= Date.parse(current.updated_at)) throw new CliError("grant-retry must move updated_at forwards");
     const qualified = qualifyRetryGrant(repo, runDir, runId, current, sliceId);
@@ -864,7 +871,7 @@ const HANDLERS = {
         const row = { ...existing, status: "running", attempts: existing.attempts + 1,
           ...(flags.scope === "slice" ? { extra_attempts: (existing.extra_attempts ?? 0) + 1 } : {}),
           evidence_ref: null, review_ref: null };
-        const maxRetries = state.max_retries + (flags.scope === "all" ? 1 : 0), newLimit = maxRetries + (row.extra_attempts ?? 0);
+        const maxRetries = grantedMax, newLimit = maxRetries + (row.extra_attempts ?? 0);
         const audit = { scope: flags.scope, slice_id: sliceId, base_ref: existing.base_ref, attempt: row.attempts, previous_limit: previousLimit,
           new_limit: newLimit, previous_max_retries: state.max_retries, max_retries: maxRetries,
           session: flags.session, reason: flags.reason.trim(), at, snapshot_digest: qualified.snapshotDigest,
@@ -1276,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, {
@@ -1722,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 });
   }
@@ -1863,11 +1882,12 @@ function usage() {
   factory init <run-id> [--branch B=feature/<run-id>] [--worktree W=.] [--pr-base TARGET] [--issue KEY] [--mode interactive|headless|autonomous]
   factory status <run-id> [--json]
   factory amend-paths <run-id> <slice-id> --add PATH [--add PATH ...] --reason TEXT --session ID [--now ISO]
-  factory grant-retry <run-id> <slice-id> --scope slice|all --reason TEXT --session ID [--now ISO]
+  factory grant-retry <run-id> <slice-id> --scope slice|all [--max-retries N] --reason TEXT --session ID [--now ISO]
   factory decide <run-id> --text TEXT --session ID [--now ISO]
   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/core/contracts.js

@@ -66,7 +66,7 @@ const envelope = contract({
         const scope = mode === "grant-retry-all" ? "all" : "slice";
         if (after.status !== "needs-human" || !isDeepStrictEqual(after.terminal_result, before.terminal_result)) throw new Error("grant-retry must preserve the parked envelope and terminal_result");
         if (Date.parse(after.updated_at) <= Date.parse(before.updated_at)) throw new Error("grant-retry must move updated_at forwards");
-        if (scope === "all" ? after.max_retries !== before.max_retries + 1 : after.max_retries !== before.max_retries) throw new Error(`grant-retry ${scope} has an invalid run-wide retry limit`);
+        if (scope === "all" ? !(after.max_retries > before.max_retries) : after.max_retries !== before.max_retries) throw new Error(`grant-retry ${scope} has an invalid run-wide retry limit`);
         if (after.retry_extensions.length !== before.retry_extensions.length + 1 || !isDeepStrictEqual(after.retry_extensions.slice(0, -1), before.retry_extensions) || after.retry_extensions.at(-1)?.scope !== scope) throw new Error("grant-retry must append one matching audit record");
         for (const key of Object.keys(before).filter((key) => !["updated_at", "max_retries", "retry_extensions"].includes(key))) if (!isDeepStrictEqual(before[key], after[key])) throw new Error(`grant-retry cannot change envelope.${key}`);
         for (const key of Object.keys(current).filter((key) => !Object.hasOwn(before, key) && key !== "slices")) if (!isDeepStrictEqual(current[key], candidate[key])) throw new Error(`grant-retry cannot change run.${key}`);
@@ -340,7 +340,8 @@ const slices = contract({
       if (scope === "all" && before.some((entry, entryIndex) => entryIndex !== index && entry.status === "blocked")) throw new Error("grant-retry all cannot strand another blocked slice below the raised limit");
       if (prior.id !== slice.id || prior.status !== "blocked" || slice.status !== "running") throw new Error("grant-retry requires one blocked slice to become running");
       const previousLimit = effectiveRetryLimit(current, prior), nextLimit = effectiveRetryLimit(candidate, slice);
-      if (prior.attempts !== previousLimit || slice.attempts !== prior.attempts + 1 || nextLimit !== previousLimit + 1) throw new Error("grant-retry must open exactly N+1 from the exhausted effective limit");
+      const raise = scope === "all" ? candidate.max_retries - current.max_retries : 1;
+      if (prior.attempts !== previousLimit || slice.attempts !== prior.attempts + 1 || nextLimit !== previousLimit + raise) throw new Error("grant-retry must open exactly N+1 from the exhausted effective limit");
       const previousExtra = prior.extra_attempts ?? 0, nextExtra = slice.extra_attempts ?? 0;
       if (scope === "slice" ? nextExtra !== previousExtra + 1 : nextExtra !== previousExtra) throw new Error(`grant-retry ${scope} has an invalid slice-specific extension`);
       for (const key of new Set([...Object.keys(prior), ...Object.keys(slice)])) if (!["status", "attempts", "extra_attempts", "evidence_ref", "review_ref"].includes(key) && !isDeepStrictEqual(prior[key], slice[key])) throw new Error(`grant-retry cannot change slice '${slice.id}' ${key}`);

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

package/state/schema.js

@@ -181,9 +181,10 @@ function retryExtensions(errors, run) {
     for (const key of ["attempt", "previous_limit", "new_limit", "previous_max_retries", "max_retries"]) positiveInt(errors, entry, key, path);
     if (!RETRY_EXTENSION_SCOPES.includes(entry.scope) || !ID.test(entry.slice_id)
       || ["attempt", "previous_limit", "new_limit", "previous_max_retries", "max_retries"].some((key) => !Number.isSafeInteger(entry[key]) || entry[key] < 1)) crossCheck = false;
-    if (Number.isSafeInteger(entry.previous_limit) && entry.new_limit !== entry.previous_limit + 1) errors.push({ path: `${path}.new_limit`, message: "must advance exactly one" });
+    const raise = entry.scope === "all" ? entry.max_retries - entry.previous_max_retries : 1;
+    if (Number.isSafeInteger(entry.previous_limit) && entry.new_limit !== entry.previous_limit + raise) errors.push({ path: `${path}.new_limit`, message: "must advance by the granted raise" });
     if (entry.scope === "slice" && entry.max_retries !== entry.previous_max_retries) errors.push({ path: `${path}.max_retries`, message: "must stay unchanged for slice scope" });
-    if (entry.scope === "all" && entry.max_retries !== entry.previous_max_retries + 1) errors.push({ path: `${path}.max_retries`, message: "must advance exactly one for all scope" });
+    if (entry.scope === "all" && !(raise >= 1)) errors.push({ path: `${path}.max_retries`, message: "must rise for all scope" });
     for (const key of ["session", "reason"]) required(errors, entry, key, path);
     pattern(errors, entry, "at", ISO, path);
     pattern(errors, entry, "snapshot_digest", DIGEST, path);
@@ -196,7 +197,7 @@ function retryExtensions(errors, run) {
     }
   });
   if (!crossCheck) return;
-  let maxRetries = run.max_retries - value.filter((entry) => entry.scope === "all").length;
+  let maxRetries = run.max_retries - value.reduce((sum, entry) => sum + (entry.scope === "all" ? entry.max_retries - entry.previous_max_retries : 0), 0);
   if (maxRetries < 1) return void errors.push({ path: "run.retry_extensions", message: "contains more run-wide grants than the final max_retries permits" });
   const extras = new Map(), latestGrant = new Map(), grantBases = new Map(), archiveRefs = new Set();
   let previousAt = null;
@@ -212,10 +213,10 @@ function retryExtensions(errors, run) {
     previousAt = Date.parse(entry.at);
     const previousLimit = maxRetries + previousExtra;
     if (entry.previous_max_retries !== maxRetries || entry.previous_limit !== previousLimit) errors.push({ path, message: "does not continue the recorded retry limits" });
-    if (entry.scope === "all") maxRetries += 1;
+    if (entry.scope === "all") maxRetries = entry.max_retries;
     else extras.set(entry.slice_id, previousExtra + 1);
     const newLimit = maxRetries + (extras.get(entry.slice_id) ?? 0);
-    if (entry.max_retries !== maxRetries || entry.new_limit !== newLimit || entry.attempt !== newLimit) errors.push({ path, message: "does not bind the granted attempt and resulting limits" });
+    if (entry.max_retries !== maxRetries || entry.new_limit !== newLimit || entry.attempt !== previousLimit + 1) errors.push({ path, message: "does not bind the granted attempt and resulting limits" });
     if (grantBases.has(entry.slice_id) && grantBases.get(entry.slice_id) !== entry.base_ref) errors.push({ path: `${path}.base_ref`, message: "changes the slice's immutable retry base" });
     grantBases.set(entry.slice_id, entry.base_ref); latestGrant.set(entry.slice_id, entry.attempt);
   }