feature-factory 0.9.1 → 0.10.0

package/README.md

@@ -20,6 +20,16 @@ host binding and copies this workflow beside that skill at build/pack time. Inst
 `opencode-feature-factory` or `prime-agent-feature-factory` for a supported host, or build an adapter
 that loads the complete workflow and drives all durable state changes through the CLI.
 
+## Infrastructure failures and attempts
+
+A confirmed host-origin availability or transport failure does not spend a specialist attempt. The active
+driver permits one same-attempt recovery for the canonical role and subject only when the host proves
+execution never started or can recover the same child/session. Unbudgeted research and design create no
+attempt. A second consecutive failure parks the run. The count is memory-only and resets with the driver,
+but resume and reset never prove that prior work did not start: the next driver must recover or prove the
+same prior invocation safe before dispatch. Child text, unknown errors, and excluded auth, quota,
+rate-limit, and configuration failures never trigger a free retry or duplicate possibly-started work.
+
 ## Repository command configuration
 
 A repository operator may provide optional `$O/.factory.json`, where `O` is the physically
@@ -37,9 +47,9 @@ resolved Git top level:
 }
 ```
 
-The root has three required properties and four optional properties: `pr_draft`, `verify_timeout_ms`,
-`bootstrap`, and `bootstrap_timeout_ms`. `resolve`, `verify`, `publish`, and a present `bootstrap` are non-empty command
-strings. There is no `publishing_identity` key, and a file carrying one is malformed because the
+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
+`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`.
 Each omitted timeout independently defaults to `900000`; neither shares the other's budget. The file is
@@ -56,7 +66,7 @@ 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`; then missing or invalid required entries.
+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`.
 
 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`.
 
@@ -113,10 +123,14 @@ removed the sandbox destroyed the manifest and every accepted gate with it. `.pa
 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.
+and `partial` are not snapshotted. A retained sandbox resumes directly; when that sandbox is lost,
+`factory restore <R> --repo <O> --from refs/remotes/<remote>/<feature-branch>` rebuilds a parked,
+lockless sandbox from the snapshot and the exact pushed feature ref. It reports every active slice reset
+to `pending` rather than claiming branch-local work survived.
+
+Qualified status reports `park_snapshot` for an unchanged live park: the published path, or `null` when no
+matching snapshot exists. A restored generation deliberately reports `null` because its manifest and path
+bindings changed; `status.restore` carries its source digest, feature commit, resets, and invalidations.
 Malformed config, malformed payload, a non-zero exit, or unavailable exit status refuses before any
 run effect and never falls back:
 
@@ -144,7 +158,7 @@ A failed, timed-out, dirty, or unobservable fresh init emits no JSON stdout, ret
 
 When both bootstrap keys are absent, init and resume are exact no-ops for bootstrap: no execution, manifest fields, output, or response-shape change.
 
-Bootstrap never runs during resolver intake, merge verification or replay, direct repository verification, slice observation, Gate 3, effective push, configured publication, push, or PR creation. Existing resolver, verify, configured-publish, effective-push, push, PR, and Gate 3 behavior is unchanged.
+Bootstrap never runs during resolver intake, merge verification or replay, direct repository verification, slice observation, Gate 3, effective push, configured publication, push, or PR creation. Bootstrap does not mediate configured publication, effective-push, push, PR, or Gate 3 behavior.
 
 After a slice merge is successfully and atomically recorded, `verify` starts in the exact recorded
 integration worktree. Its configured string is submitted unchanged as one ordinary shell command with
@@ -190,6 +204,30 @@ Gate 3 always runs a separate fresh integrated `test-verifier` observation at th
 overwrites canonical evidence through the existing command mode and never shares, substitutes, or
 optimizes from post-merge evidence, even when the head is unchanged.
 
+## Restoring a lost parked sandbox
+
+Run restore from the canonical operator repository, not from a replacement checkout:
+
+```sh
+factory restore <run-id> --repo <operator-repository> \
+  --from refs/remotes/<remote>/<recorded-feature-branch> --json
+```
+
+The source must be the canonical `$O/.factory/.parked/<run-id>` snapshot. The feature ref must be a full
+remote-tracking ref whose branch suffix exactly matches the manifest and whose commit is still advertised
+by that remote's push endpoint, exactly equal to the operator effective push endpoint. Restore validates
+that snapshot, refuses symlinks that escape its control plane, clones the exact derived sandbox, aligns and
+rechecks the operator's effective push target, and proves every preserved merged-slice Git and evidence
+binding against the pushed head. It omits the old root session lock and publishes the transformed manifest
+last. The run stays parked and no repository-configured bootstrap runs. Nonmerged slices with physical
+branch or worktree state reset to `pending`, and the command reports them. Stale HEAD-bound validator
+approval is invalidated. Gate 3 and test-verifier approval are always invalidated because canonical
+publication evidence names the prior physical generation; canonical verifier records are omitted from the
+copy. The staged slice projection must still match the Brief-bound plan digest and recorded amendments.
+The durable `status.restore` record identifies the source inventory and restored commit. Because the new
+generation has different paths and provenance, `status.park_snapshot` is `null` after a successful restore.
+Claim the new lock and use the ordinary resume sequence only after reviewing those losses.
+
 ## Resuming a parked run
 
 A top-level `needs-human` status is a parked stop, not a final result. `completed`, `partial`, and
@@ -220,7 +258,7 @@ 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.
 
-`resolve` and `verify` are consumed now, and the run's recorded `publishing_identity` is compared at the publication guards. Configured `publish` remains unconsumed and is not invoked.
+`resolve` and `verify` are consumed now, and the run's recorded `publishing_identity` is compared at the publication guards. Step 6 resolves one selection: a nonblank inherited `FACTORY_PUBLISHING_COMMAND` selects its exact string; that variable set blank or whitespace selects the default; when it is unset, configured `publish` wins if present; otherwise the default wins. Only a selected nondefault command replaces `gh pr create`, after the factory-owned exact push and post-push identity guard. It receives exact `PR_BASE`, `FEATURE_BRANCH`, `PR_DRAFT`, `PR_TITLE`, and absolute `PR_BODY_FILE` environment values. Only exit zero with an absolute HTTPS URL on the last nonempty stdout line is recordable; every other result parks with exact reason `selected publishing command outcome indeterminate; re-observe whether the pull request exists before retry` and no fallback.
 Effective push-target capture and comparison are active through the package-owned `factory effective-push` command; they are not deferred to configured `publish`.
 The recorded `publishing_identity` is read from `status` exactly as reported, without trimming,
 normalization, case-folding, or reserialization. `init` refuses when neither the flag nor the environment
@@ -230,8 +268,8 @@ can report `null`. `publishing_identity` is a recorded run field reported by `st
 With a recorded identity, every mode checks it at exactly three boundaries: immediately
 after verified post-lock ownership, or immediately after an explicit resume is verified running with
 the same fresh owner and before reconciliation or other work; immediately before `git push`, after
-effective push-target equality; and immediately before `gh pr create`, after the push is known
-successful. No operation intervenes across a guard boundary. Only a manifest written before 0.8.0, which can
+effective push-target equality; and immediately before the selected PR-creation command, after the
+factory-owned exact push is known successful. No operation intervenes across a guard boundary. Only a manifest written before 0.8.0, which can
 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
@@ -268,7 +306,7 @@ session.
 
 Publishing-identity verification is enforcement because it prevents false-green or wrong-account
 publication. Credential provisioning and helper setup are instruction only. Existing push,
-`gh pr create`, `factory pr`, Gate 3, merge, and approval semantics remain unchanged. The live config
+`factory pr`, Gate 3, merge, and approval semantics remain unchanged. The live config
 is not part of this package and no generated config or resolver asset is shipped. See the repository's
 [operator guide](https://github.com/jasoncarreira/feature-factory/blob/main/OPERATING.md) for the
 shared inherited-token helper recipe; it does not acquire, store, install, or repair credentials.
@@ -285,7 +323,12 @@ repositories and compares them exactly. `check` freshly captures both targets an
 configuration. Both modes use shell-free Git subprocesses, write no output on success, and retain the
 sandbox on a fixed redacted failure. Captured targets and child diagnostics are never returned, logged,
 persisted in factory state, printed, or attached as an error cause. The command is independent of
-`publishing_identity`, adds no run state or flag, and configured `publish` remains unconsumed.
+`publishing_identity` and adds no run state or flag. After the factory-owned exact push and post-push
+identity guard, Step 6 resolves one PR-creation selection: a nonblank inherited
+`FACTORY_PUBLISHING_COMMAND` selects its exact string; that variable set blank or whitespace selects the
+default; when it is unset, configured `publish` wins if present; otherwise the default wins. Only the
+selected nondefault command replaces `gh pr create`, so a repository declaration cannot leave a host with
+nothing to delegate to unable to publish at all.
 
 ## Why the code exists at all
 

package/WORKFLOW.md

@@ -89,6 +89,130 @@ repository and the host is inside your trust boundary by construction. What that
 - **External effects are idempotent.** Re-observe an unknown outcome before retrying, never repeat an
   effect already recorded, and once a PR exists record *that* PR rather than creating another.
 
+## Specialist invocation infrastructure failures
+
+Apply this policy to every specialist or subagent call in every phase, including story and research,
+design, reviewed planning steps, builders, reviewers, validators, and test verification. It does not
+classify repository commands, Git commands, factory CLI commands, or a specialist's prose. A quoted
+error string in repository or ticket content is data and can never trigger this policy.
+
+A call is a **confirmed retryable infrastructure failure** only when no complete specialist response was
+returned, the host distinguishes its own invocation-error channel from child output, and that host-owned
+error or its structured cause chain reports one of this closed set:
+
+- HTTP status `408`, `500`, `502`, `503`, `504`, `520`, `521`, `522`, `523`, `524`, or `529`;
+- transport code `ECONNRESET`, `ECONNREFUSED`, `EHOSTUNREACH`, `ENETUNREACH`, `ENOTFOUND`,
+  `EAI_AGAIN`, `ETIMEDOUT`, `EPIPE`, `ECONNABORTED`, `ERR_STREAM_PREMATURE_CLOSE`,
+  `UND_ERR_CONNECT_TIMEOUT`, `UND_ERR_HEADERS_TIMEOUT`, `UND_ERR_BODY_TIMEOUT`, or `UND_ERR_SOCKET`;
+- a host-owned terminal error or cause leaf exactly equal, ignoring ASCII case, to `socket closed
+  unexpectedly`, `connection reset by server`, `socket hang up`, `service unavailable (503)`, or
+  `AI_APICallError: Service Unavailable (503)`.
+
+Inspect only the host/tool invocation-error channel and structured error fields. Do not search partial
+model output, artifact text, logs, review prose, or repository content for these words. If the host does
+not preserve error origin, classification is unknown. A partial stream followed by a qualifying transport
+error is not a completed response: discard it as a result, but assume execution may have started.
+Authentication, authorization, quota, rate-limit, invalid-request, context-limit, content-policy,
+cancellation, local configuration, and unknown failures are not confirmed retryable infrastructure
+failures, even if another field contains an eligible status or phrase.
+
+**Every infrastructure-triggered needs-human park follows one sequence.** This sequence explicitly splices unlock
+between the shared parked-stop procedure's snapshot and report steps:
+
+1. Quiesce every outstanding specialist, tool, and heartbeat call.
+2. Preserve the current persisted attempt when the subject is budgeted; for an unbudgeted subject, create
+   no durable attempt or progress record.
+3. Execute shared parked-stop step 1 with the exact reason token selected below.
+4. Execute shared parked-stop step 2. Attempt the parked snapshot and retain its verified path or its
+   publication failure for the report.
+5. Whether or not step 2 published a snapshot, release this driver's verified owning session and require
+   qualified status to show an absent lock and a null owner.
+6. Only after unlock verification succeeds, execute shared parked-stop step 3 and report the retained
+   sandbox with the snapshot path or failure.
+
+If release or unlock verification fails, do not execute shared step 3 and do not issue the normal
+parked-success report. Report only `Outcome: retained-lock-error` with actual status, terminal result,
+lock state, and error.
+
+Each branch selects exactly one reason token and no other text. Never put the provider error, response
+fragment, URL, credential, token, diagnostics, or any host-supplied string into it. Bind the selected
+reason as `PRE_QUOTING_REASON` and transport it as the sole `--reason` argument with the deterministic
+POSIX single-quote encoding defined under Publishing identity enforcement; the encoded token is never
+persisted.
+
+| branch token | exact persisted reason template |
+|---|---|
+| `NON_RETRYABLE_REASON` | `specialist invocation failed with a non-retryable error for <role> on <subject>; inspect the host invocation log, then prove execution never started or recover the same invocation before continuing` |
+| `UNKNOWN_OUTCOME_REASON` | `specialist infrastructure outcome unknown for <role> on <subject>; prove execution never started or recover the same invocation before continuing` |
+| `SECOND_FAILURE_REASON` | `specialist infrastructure failed twice consecutively for <role> on <subject>; after provider or network recovery, prove execution never started or recover the same invocation before continuing` |
+
+`<role>` is the exact canonical dispatch target, never agent frontmatter or host/provider text. Select
+`<subject>` from this closed map:
+
+| role | canonical subject |
+|---|---|
+| `story-reader`, `story-writer` | `stage:story` |
+| `codebase-researcher` | `stage:research` |
+| `design-interpreter` | `stage:design` |
+| `spec-writer` | `step:spec-writer` |
+| `work-decomposer` | `step:work-decomposer` |
+| `backend-builder`, `frontend-builder` | `slice:<slice-id>` |
+| `test-verifier` | `step:test-verifier` |
+| `implementation-validator` | `stage:implementation-validator` |
+| `work-reviewer` | the exact reviewed subject: `step:spec-writer`, `step:work-decomposer`, `slice:<slice-id>`, or `step:test-verifier` |
+
+For a reason template, render `<slice-id>` from at most the first 80 ASCII characters of the schema-valid
+persisted slice ID and append `~` when truncated. The in-memory invocation key still uses the exact full
+role, subject, and persisted attempt when one exists. Constants come only from the table and slice IDs
+come only from `run.json`; neither field comes from host or provider diagnostics.
+
+If an excluded or non-transport failure returns no complete response, preserve the persisted attempt when
+one exists, create no attempt for unbudgeted work, and take the common infrastructure-park sequence with
+`NON_RETRYABLE_REASON`. Do not retry it or treat it as rejected work.
+
+For each active invocation key — exact specialist role, exact workflow subject or slice, and the current
+persisted attempt number when that subject is budgeted — hold an in-memory consecutive-infrastructure-
+failure count. Start it at zero in every new driver invocation, including after resume; never write it to
+`run.json` or any artifact. A complete specialist response or a non-infrastructure outcome for that same
+key resets it to zero. Activity for another key neither combines with nor resets it.
+
+On the first confirmed failure for a key, increment only that in-memory count. Keep the control plane
+unchanged: do not issue any step or slice transition with `--attempts N+1`, do not observe or review
+partial output, and do not record `accepted`, `rejected`, or `blocked`. Continue automatically only
+through one of these two safe paths:
+
+1. When trusted host metadata proves execution never started, re-dispatch the exact same role, subject,
+   inputs and, when budgeted, the persisted attempt number.
+2. When execution started or may have started, recover and continue the same host dispatch or child
+   session by its existing host-owned identity. First inspect that same child and its expected artifact or
+   worktree; never create a second child for the logical attempt and never repeat successful siblings in a
+   parallel wave.
+
+If neither path is available, preserve the persisted attempt when one exists, create none for unbudgeted
+work, and take the common infrastructure-park sequence with `UNKNOWN_OUTCOME_REASON`. An unbudgeted
+research or design call still permits at most one safe same-invocation recovery and creates no durable
+progress record.
+
+On the second consecutive confirmed failure for the same key during that safe re-dispatch or recovery,
+do not invoke it again. Take the common infrastructure-park sequence with `SECOND_FAILURE_REASON`.
+
+The failure count remains invocation-local: every new driver, including one entered after explicit resume,
+starts it at zero. That reset is not proof that prior execution did not start. When the preserved historical
+terminal reason matches any infrastructure reason template, it guards the first later dispatch of the
+named canonical role and subject at the retained attempt, or the named unbudgeted stage. Before that
+dispatch, trusted host metadata must prove the prior invocation never started, or the driver must recover
+and inspect that same host dispatch or child identity and its expected artifact or worktree. Explicit
+resume, `status.next`, provider recovery, the reset count, and an operator assertion alone establish
+neither fact. If neither safe path is available, do not dispatch; re-enter the common infrastructure-park
+sequence with `UNKNOWN_OUTCOME_REASON`. Never repeat successful siblings.
+
+A budgeted attempt advances only after a complete specialist response reaches the ordinary workflow and
+that response is rejected on its merits or violates the specialist's required output contract. A complete
+unbudgeted result returns to its ordinary workflow without creating an attempt. Infrastructure recovery is
+the same attempt, not another use of `max_retries`. This rule is instruction rather than CLI enforcement:
+the host owns specialist invocation errors, while the CLI continues to enforce every durable attempt
+transition the driver actually records.
+
 ## The chain
 
 ```
@@ -304,9 +428,16 @@ Three properties make this safe to do at a park rather than only at completion:
    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.
+A snapshot is a restore input, not a live run: resume still operates only on a sandbox manifest. While `S`
+exists, never restore over it or treat the snapshot as authority over the live plane. If `S` is lost, fetch
+the feature branch still advertised by the operator effective push endpoint into a full remote-tracking ref whose suffix is the recorded branch, then run
+`factory restore "$R" --repo "$O" --from "$RESTORE_REF" --json`. Restore creates only the exact derived
+sandbox, remains parked and lockless, aligns and rechecks the operator's effective push target, omits the
+old plane-root lock, proves every preserved merged-slice Git and evidence binding, resets unrecoverable nonmerged slices to `pending`, and reports `reset_slices` and `invalidated`. It omits prior-generation
+canonical verifier records and always invalidates Gate 3 and test-verifier state. It records its source inventory and restored commit at `status.restore`; `park_snapshot` becomes `null` because the new
+generation is intentionally not byte-identical to its source. Review those losses, bind `RUN_REPO` to the
+returned sandbox, and only then enter the ordinary claim-and-resume order. Do not publish snapshots for
+`blocked` or `partial`, which are not resumable.
 
 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
@@ -376,10 +507,13 @@ The optional repository-owned file is `$O/.factory.json`:
 }
 ```
 
-The root must be a JSON object with the three required own properties `resolve`, `verify`, and `publish`,
-plus only the optional own properties `pr_draft`, `verify_timeout_ms`, `bootstrap`, and
+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
-command must be non-empty. There is no `publishing_identity` key: the account a run publishes as is a
+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
+presence alone never executes this entry. There is no `publishing_identity` key: the account a run publishes as is a
 property of the environment it runs in, not of the repository, and a tracked file cannot hold two values
 for one repository published from both a maintainer's checkout and an automated host. A file carrying that
 key is malformed, because the optional set above is closed. `pr_draft` must be a JSON boolean
@@ -388,7 +522,7 @@ safe integers when present, and `bootstrap_timeout_ms` is valid only with a decl
 `verify_timeout_ms` and `bootstrap_timeout_ms` each independently default to `900000` milliseconds;
 neither timeout shares or consumes the other's budget.
 
-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`; then missing or invalid required entries.
+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`.
 
 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.
 
@@ -516,7 +650,7 @@ Do not create, write, merge, archive, or package `.factory.json`. It remains ope
 committed, so every clone and sandbox carries it, and refused by the privileged-path policy, so a run
 cannot widen its own configuration. It lived under the gitignored `.factory/` run directory until that proved unusable —
 `.factory/` is gitignored, so the file could not be committed and never reached a sandbox clone, which
-made the `verify` and unconsumed `publish` entries impossible and left this repository unable to resolve
+made the `verify` and `publish` entries unavailable and left this repository unable to resolve
 a reference from a fresh checkout. For configured resolver execution, add no helper module,
 command runner, parser service, plugin bridge, transport, protocol, or CLI command. Add no resolver
 cache, payload handoff, manifest or session
@@ -534,11 +668,14 @@ separate capture policy, output channel, buffering, truncation, redaction, outpu
 retry, or fallback after any configured resolver result or failure. The verify timeout and bounded retry
 below apply only to repository `verify` shell attempts; the bootstrap timeout applies only to CLI-owned
 init and explicit resume. Neither applies to `resolve`, slice observation, or Gate 3 commands. Do not
-change platform placement, background-tool, title-association, host-session, or publication behavior.
+change platform placement, background-tool, title-association, or host-session behavior. Publication changes only through the optional Step 6 command below.
 `story-reader` remains lookup-free and capability-free beyond its existing generic read tools.
 
 `resolve` and `verify` are consumed now, and the run's recorded `publishing_identity` is compared at the
-guards below. Configured `publish` remains unconsumed and is not invoked.
+guards below. Step 6 resolves exactly one publishing selection from inherited
+`FACTORY_PUBLISHING_COMMAND`, the optional `publish` entry, or the default, in the precedence defined
+below. Only a selected nondefault command replaces the driver's `gh pr create`; the factory-owned exact
+push and post-push identity guard remain unchanged.
 
 Configured `bootstrap` is consumed only by CLI-owned fresh init and explicit resume; the workflow consumer validates it but never executes it itself.
 
@@ -548,7 +685,7 @@ Effective push-target capture and comparison are active through the package-owne
 |---|---|---|---|---|
 | `bootstrap` | Exact configured string as one shell command with `shell: true`, inherited environment and stdin, cwd exactly the selected sandbox, and child stdout and stderr both routed to CLI stderr. Each execution receives its own `bootstrap_timeout_ms`, independently `900000` when omitted. | Numeric exit status or unavailable `null`; output is visible on CLI stderr and never parsed | Clean zero succeeds; dirty or unobservable tracked state outranks unavailable or nonzero exit | Invoked by the CLI once during configured fresh init and again on every explicit configured resume; never invoked by resolver, merge verification or replay, direct repository verification, slice or Gate 3 observation, effective push, or publication. |
 | `verify` | Ordinary shell step in the exact integration-worktree cwd with inherited environment; no structured stdin or factory-specific payload is defined. Each attempt receives the full configured `verify_timeout_ms`, silently `900000` when omitted. | Exit status is authoritative; stdout and stderr are inherited, informational, and unparsed | Zero means success; non-zero means repository verification failed; no numeric child status means unavailable | Invoked after each newly recorded merge through `observe --repository-verify`, with at most two executions in that merge invocation. The timeout and retry never apply to resolver, slice, or Gate 3 commands. |
-| `publish` | Future ordinary shell step in repository-root cwd with inherited environment; no structured stdin or factory-specific payload is defined | Exit status is authoritative; stdout is informational and unparsed | Zero means the command reported success; non-zero means it reported failure | Not invoked. Existing `git push`, `gh pr create`, and `factory pr` behavior remains unchanged; effective push-target equality is enforced separately by <code>factory effective-push</code>. |
+| `publish` | Optional file candidate for the one Step 6 publishing selection. A nonblank inherited `FACTORY_PUBLISHING_COMMAND` selects its exact string; the same variable set empty or to whitespace selects the default; when the variable is unset this entry is selected if present, otherwise the default. A selected nondefault command runs as one shell step in `RUN_REPO` cwd, with no stdin or positional arguments and inherited environment plus exact `PR_BASE`, `FEATURE_BRANCH`, `PR_DRAFT`, `PR_TITLE`, and absolute `PR_BODY_FILE`. | Exit status is authoritative; the last nonempty stdout line must be an absolute HTTPS URL and becomes `PR_URL` | Zero plus that URL is recordable; any other result is indeterminate and parks before `factory pr` | The resolved selection replaces only `gh pr create`, after the factory-owned exact push and post-push identity guard. `factory pr` is unchanged and still records the URL. |
 | `publishing_identity` | No runtime input; read the value `status` reports for the run, recorded at init from `--publishing-identity` or the inherited `FACTORY_PUBLISHING_IDENTITY` | Exact case-sensitive string compared with the observed login | Absent at init refuses before any sandbox exists; mismatch or unobservable identity parks the run | Active at the three mandatory guards below; only a manifest written before 0.8.0 can report `null` and skip them. |
 
 When both bootstrap keys are absent, init and resume are exact no-ops for bootstrap: no execution, manifest fields, output, or response-shape change.
@@ -656,7 +793,7 @@ intervene between the verified running/same-owner result and that guard, or betw
 and reconciliation. A pre-0.8.0 manifest reporting `null` preserves the nine orders without adding an operation.
 The refreshed workflow read belongs to order 7 verification, before this boundary.
 
-For order 1 require the intended run ID, a valid manifest, recorded branch and mode, current parked status, and the original terminal result. Order 2 stays after selection and containment and before effective-push proof. Order 3 never absorbs containment, binding, or the post-selection exact-ref guard. During order 4 preserve every existing exact-ref recheck and the stated provenance sequence. No unrelated observation or effect occurs between order 5 and claim or justified steal. Order 6 requires `lock_session === SESSION_ID`, a fresh lock, unchanged parked status, and a terminal result deeply equal to the one first observed. Invoke `factory resume "$R" --session "$SESSION_ID" --repo "$RUN_REPO"` for order 7 — the same session order 6 just verified as the fresh owner — then require that owner unchanged. Resume refuses without it, and refuses a lock that is absent, stale, or held by anyone else. Order 8 may replay only the existing recorded-merge reconciliation path and must not move pre-lock proofs across the lock boundary. Order 9 never uses the pre-resume observation or the stop reason.
+For order 1 require the intended run ID, a valid manifest, recorded branch and mode, current parked status, and the original terminal result. Order 2 stays after selection and containment and before effective-push proof. Order 3 never absorbs containment, binding, or the post-selection exact-ref guard. During order 4 preserve every existing exact-ref recheck and the stated provenance sequence. No unrelated observation or effect occurs between order 5 and claim or justified steal. Order 6 requires `lock_session === SESSION_ID`, a fresh lock, unchanged parked status, and a terminal result deeply equal to the one first observed. Invoke `factory resume "$R" --session "$SESSION_ID" --repo "$RUN_REPO"` for order 7 — the same session order 6 just verified as the fresh owner — then require that owner unchanged. Resume refuses without it, and refuses a lock that is absent, stale, or held by anyone else. Order 8 may replay only the existing recorded-merge reconciliation path and must not move pre-lock proofs across the lock boundary. Order 9 uses only the newly qualified next action for workflow progress, but before its first matching specialist dispatch it must apply the preserved infrastructure-reason guard above; it never treats explicit resume or the count reset as no-start proof.
 
 If resume refuses after claim or the run later reparks, quiesce builders, tools, specialist tasks, and
 heartbeat loops. Qualify the intended retained run again before reporting the stop. If it is still parked
@@ -1393,9 +1530,14 @@ Per slice:
      $ factory slice "$R" "$SLICE_ID" review --evidence-ref "evidence/$SLICE_ID.json" \
        --review-ref "reviews/$SLICE_ID.json" --repo "$RUN_REPO"
      ```
-   - On REJECT, before spending an attempt, identify the design-level root cause. If the fix would
+   - On REJECT, before spending an attempt, identify the cause of the remaining failures. If the fix would
      violate an approved story or brief constraint, or repeated findings trace to the same unresolved
      design choice, stop and escalate the smallest decision needed rather than burning attempts.
+     When repeated reviews leave substantial acceptance gaps, review prior verified progress and identify
+     a bounded, achievable remediation target for the next attempt, even when the design is fully decided.
+     If no such target can be identified, park through the existing parked-stop procedure for replanning
+     or operator clarification; preserve the work and do not silently change approved acceptance criteria.
+     Unchanged finding counts alone are not a stall: progress can occur within a category that remains open.
      Otherwise route the fixes back to that builder and re-observe. After `max_retries`, mark the slice
      `blocked` and stop dispatching its dependents.
 5. **Merge (you, serially)** — on APPROVE, merge the slice branch into the feature branch one at a
@@ -1752,16 +1894,27 @@ HEAD, a branch name, or an unpersisted variable.
    is not a slice and has no slice `test_plan`, so it continues to supply its integration command. There
    is no waiver: the stage exists to run the tests, so the evidence must record an observed run that
    exited zero, against the integration head as it stands. Then `work-reviewer` confirms each criterion
-   maps to a real assertion.
+   maps to a real assertion, judging the whole integrated diff rather than any one slice's.
+   On a single-slice run this is the last review before publication, and its production findings have no
+   in-band repair: post-merge repair is test-only and a merged slice is never dispatched again, so a
+   production defect parks the run for an operator instead of returning to a builder. Review it as the
+   final reading it is.
    This Gate 3 observation is always fresh and independent in the ordinary path. It uses the existing
    argv-tokenized `--test-cmd` path and overwrites canonical evidence at the current head. The sole
    substitution is a qualifying explicit repair re-verification pass at current HEAD under Gate 3's
    complete inventory rules below; failed ordinary evidence remains preserved rather than overwritten.
 2. `implementation-validator` — the holistic pass across the whole diff, complementing per-slice
    reviews. **Skip it when the run has exactly one slice**: its subject is the interaction *between*
-   slices, and with one there is none, so it re-reads the diff the slice reviewer just approved —
-   a serialized pass on the critical path for no new information. Gate 3 does not require a verdict
-   for a single-slice run. Run it for every multi-slice run; the gate refuses without it.
+   slices, and with one there is none, so it has no question of its own to answer. Gate 3 does not
+   require a verdict for a single-slice run. Run it for every multi-slice run; the gate refuses
+   without it.
+
+   **Skipping it does not mean the integrated diff goes unread**, and nothing here should be read as
+   saying a second reading is worthless. Step 1's `work-reviewer` pass over `test-verifier` judges that
+   diff whole, and on a single-slice run it is the only review after the slice's own: mimir's
+   chainlink-1304 merged its one slice clean at zero findings, and that pass then found two production
+   defects in it, both real and both confirmed. What the skip removes is a duplicate *verdict* on a
+   subject that does not exist, not the reading.
 
    When you do run it, it returns GO / GO-WITH-NITS / NO-GO **and writes `reviews/implementation-validator.json`
    naming the commit it judged**, exactly like any other reviewer. Then:
@@ -1973,17 +2126,60 @@ gh api --method GET /user --jq .login
 factory pr "$R" --url "$PR_URL" --repo "$RUN_REPO"
 ```
 
-The second observation runs only after that push is known successful and immediately before unchanged
-`gh pr create`, with no intervening operation. Both Step 6 guards are skipped when `.factory.json` is
-absent. A mismatch or unobservable result follows the common quiesce, park, durable-reason, owning
-release, unlock-verification, retention, reporting, and later-driver procedure above. There is no
-separate identity guard before `factory pr`; preserve that command and every existing publication mode,
-status, and gate exactly.
-
-The `gh` call is the orchestrator's external effect; the package makes no forge call and `factory pr`
-does not verify the forge's base. For a legacy manifest where `pr_base` is absent or null, stop and
-require a human/operator to choose or confirm the exact target, then pass that value through
-`gh pr create --base`. Never infer it from HEAD, the feature branch, repository or forge defaults, and
+The fully qualified `git push` above is factory-owned and unchanged for every resolved publishing
+selection. It is the only push in this procedure. The second identity observation always runs after that
+push is known successful and immediately before the selected pull-request operation, with no intervening
+operation.
+
+**Resolve one publishing selection before running anything, and execute that selection rather than
+either source.** In order: inherited `FACTORY_PUBLISHING_COMMAND` holding at least one non-whitespace
+character selects that string; the same variable set empty or to whitespace selects the default, even
+when `$O/.factory.json` declares `publish`; an unset variable selects the configured `publish` when the
+file declares one; and with neither, the default. The resolution runs whether or not `$O/.factory.json`
+exists, so an environment-only override selects a command in a repository that declares none, and a
+declared `publish` is never executed while that variable holds a different value. Nothing downstream
+reads either source again.
+
+The environment overrides the file because how a run publishes is a property of the environment as much
+as of the repository -- the same reason there is no `publishing_identity` key in that file, and one
+repository is published from both a maintainer's checkout and an automated host. Empty selecting the
+default is what keeps a repository from declaring its way into a run that cannot publish at all from a
+host with nothing to delegate to, and it makes empty and absent behave alike rather than needing two
+rules. The override removes no guard: every run with a non-null recorded `publishing_identity` runs all
+three identity guards whether or not `$O/.factory.json` exists. Only a legacy manifest reporting `null`
+skips them. Report which source the selection came from, since the sources are indistinguishable afterwards and
+an operator debugging a publication needs to know which one ran.
+
+**When the resolution selects a command rather than the default, run that exact selected string instead
+of only `gh pr create` above**,
+as one shell command in `RUN_REPO` cwd with no stdin or positional arguments. Add exactly five values to
+the inherited environment: exact `PR_BASE`, exact `FEATURE_BRANCH`, `PR_DRAFT` as `true` or `false`, exact
+decorated `TITLE` as `PR_TITLE`, and an absolute `PR_BODY_FILE` naming the exact decorated body bytes.
+Read the last nonempty stdout line as `PR_URL` and require it to be an absolute HTTPS URL. The selected
+nondefault command owns PR creation, but these inputs preserve the recorded base, head, mode, title, and body intent;
+do not claim the factory verified that the command honored them. `factory pr` still records the returned
+URL. Exit zero **with** that absolute HTTPS URL is the only recordable result. A non-zero exit, or a zero
+exit whose last line is not a URL, is indeterminate: do not claim that no external effect occurred,
+do not run `factory pr`, and do not fall back to `gh pr create`. Bind `PRE_QUOTING_REASON` exactly to
+`selected publishing command outcome indeterminate; re-observe whether the pull request exists before retry`;
+persist no other reason text. Never append or interpolate stdout, stderr, exit status or status text, URLs,
+credentials, tokens, provider diagnostics, or any other command-supplied text. Follow the common quiesce,
+park, durable-reason transport, owning release, unlock-verification, retention, reporting, and later-driver
+procedure. Before any retry, re-observe whether the pull request exists and record an existing one rather
+than creating another.
+
+When the recorded identity is non-null, both Step 6 identity guards run for every resolved selection and
+whether or not `.factory.json` exists; only a legacy recorded `null` skips them. A mismatch or unobservable
+result follows the common quiesce, park, durable-reason, owning release, unlock-verification, retention,
+reporting, and later-driver procedure above. There is no separate identity guard before `factory pr`;
+preserve that command and every existing publication mode, status, and gate exactly.
+
+The selected PR-creation operation is the orchestrator's external effect; the package makes no forge call
+and `factory pr` does not verify the forge's base. For a legacy manifest where
+`pr_base` is absent or null, stop and require a human/operator to choose or confirm the exact target,
+then pass that value through `gh pr create --base` or the selected nondefault command's exact `PR_BASE`.
+Never
+infer it from HEAD, the feature branch, repository or forge defaults, and
 never backfill the legacy manifest.
 
 `pr_url` is immutable once recorded — a run has one PR, and overwriting the URL would hide a second
@@ -2154,6 +2350,12 @@ accepted NO-GO findings, recorded overrides, retained or residual sandboxes, or
 
 ## Resuming
 
+If the intended sandbox is absent but qualified operator inspection finds the canonical parked snapshot,
+restore it first using the exact procedure above. Restore is not resume: it leaves the new generation
+parked with no owner and may reset or invalidate state. Never substitute a local branch, a bare commit, a
+new run, or a hand-copied manifest for the full remote-tracking ref and CLI command. After restore, use its
+returned sandbox as `RUN_REPO`, inspect `status.restore`, and start the same ownership sequence below.
+
 On invocation, if the run directory exists and you hold or steal the lock, the preserved compatibility
 claim reads “run `factory status <run-id> --json` and resume; never restart.” It names a non-runnable
 command stem. Execute only `factory status "$R" --json --repo "$RUN_REPO"`, then continue from `next`:

package/agents/story-writer.md

@@ -26,6 +26,14 @@ A feature idea in the engineer's words, plus (optionally) a research map from co
 - Acceptance criteria are **testable**: each one is something test-verifier could later assert. "Works well" is not a criterion; "Auditor sees a disabled Save button until all required fields are filled" is.
 - State what's **out of scope** explicitly — it's the cheapest way to prevent scope creep downstream.
 - Keep it product-level. No file paths, no class names — that's the spec-writer's job.
+- Each acceptance criterion must support the requested outcome or a necessary correctness/safety condition.
+  Label additional capabilities and broad architectural requirements as proposed scope additions,
+  explain why they are needed, and obtain explicit approval at the existing story gate before
+  incorporating them into accepted scope. Do not silently turn implementation preferences into requirements.
+  This is not a criterion-count limit or a reason to omit necessary reliability or safety behavior.
+- Scope correctness and safety criteria to the requested behavior. When addressing known defects,
+  name the failure scenarios to prevent rather than silently generalizing them into a subsystem-wide guarantee.
+  If a broader guarantee is necessary, explain its scope and proof obligations before approval.
 
 ## Output contract
 

package/agents/work-reviewer.md

@@ -101,6 +101,11 @@ When the subject is a **class-wide** requirement — one that **cannot be establ
   catch any of this; the two slices share no path. It is decidable from the plan alone, so check it here
   rather than discovering it at the slice that fails.
 - **Doc steps (`spec-writer`, `work-decomposer`):** every required field of the output contract is filled; the artifact is consistent with its inputs (does the brief cover every AC and match the research map's real paths? does the slice DAG obey file-disjoint + hotspot-serialization rules, and does every AC map to a slice?). For `work-decomposer`, do not approve unless the supplied `plan/slices.json` is a top-level object with array-valued `slices` (the exact seedable shape `{ "slices": [...] }`); inspect only the supplied artifact, not a broader plan schema. Coverage is not enough: where more than one slice exists, a slice claiming the entire acceptance set, or claiming paths spanning every module in its lane, is a BLOCKER — that plan reviews clean and fails later as "N categories missing", which is a scope report rather than a defect report. Apply the same reviewability test to **every** slice with no condition on the plan's size, including the only slice of a one-slice plan: if your own likely rejection of it would say whole categories of required behaviour remain unimplemented, it is too large and the plan is a BLOCKER. **A one-slice plan whose `### Single-slice justification` is absent, or which justifies itself only by the brief presenting one closed inventory, is a BLOCKER** — the justification must name the semantic boundaries considered and why splitting them would create proof-only work, illegal path/test ownership, or inseparable implementation. Do not demand a split from a genuinely small change whose justification does that; the requirement is a stated reason, not a minimum slice count. For class-wide subjects, the brief must include the finite implementation matrix (per §"Class-wide completeness") — a class-wide spec that lacks it is a BLOCKER. Whether each slice can make its own `test_plan` green is the satisfiability bullet's check, stated once there rather than repeated here.
+  Check that criteria and proposed requirements support the requested outcome or necessary correctness/safety.
+  Additional capabilities and broad architectural requirements need an explicit scope rationale and approval;
+  reject unapproved scope expansion rather than silently accepting it as an implementation requirement.
+  Check the supplied request and approval record; do not reopen explicitly approved scope merely because
+  a smaller feature is possible. Do not impose a criterion-count limit or reject necessary reliability behavior.
 - **Build slices (`backend-builder` / `frontend-builder`):** apply the repo's own rubric — its agent instructions (`AGENTS.md` or `CLAUDE.md` and any review or rules files it points at — against the **observed diff**:
   - Backend: the repo's layering, its projection/read path, its API boundary.
   - Frontend: the repo's component conventions, binding forms, state approach and design tokens.
@@ -116,7 +121,7 @@ When the subject is a **class-wide** requirement — one that **cannot be establ
     docs-only slice reviewed against tests it was ratified not to have is rejected forever; that
     exemption is a plan decision, not yours to re-open here. It waives **test execution only**: the
     acceptance must still be implemented and the diff must still be observed.
-- **Test step (`test-verifier`):** each AC maps to a real assertion that would fail if the behavior broke; no test weakened to pass; the observed command is the suite the plan named and was not narrowed to exclude failures, which is a separate finding from weakening a test; observed test run is green. **There is no WRITTEN-NOT-RUN waiver for this subject:** the stage exists to run the tests, so the evidence must record an observed run that exited zero. Reporting WRITTEN-NOT-RUN honestly is valid; approving on it is not.
+- **Test step (`test-verifier`):** each AC maps to a real assertion that would fail if the behavior broke; no test weakened to pass; the observed command is the suite the plan named and was not narrowed to exclude failures, which is a separate finding from weakening a test; observed test run is green. **There is no WRITTEN-NOT-RUN waiver for this subject:** the stage exists to run the tests, so the evidence must record an observed run that exited zero. Reporting WRITTEN-NOT-RUN honestly is valid; approving on it is not. Because this is the last reading of the integrated diff before publication, make its findings exhaustive in one pass: a production defect recorded here parks the run for an operator rather than returning to a builder, since post-merge repair is test-only and a merged slice is never dispatched again, so there is no later round to carry a withheld finding into.
 
 ## Security proportionality
 

package/bin/factory.js

@@ -21,6 +21,7 @@ import { writeProtectedFileAtomic, writeProtectedJsonAtomic } from "../core/atom
 import { enforceEffectivePushTarget } from "../core/effective-push.js";
 import { resolveSpawnExecutable } from "../core/executable.js";
 import { dispatchInitPublication } from "./init-publication.js";
+import { dispatchRestore, readRestoreRecord } from "./restore.js";
 import { CONTROL_PLANE, SCHEMA_VERSION, GATE_NAMES, GATE_STATUSES, MODES, SLICE_STATUSES, STEP_STATUSES, TERMINAL_STATUSES, repositoryRelativePath, validateRun } from "../state/schema.js";
 import {
   claimSessionLock, inspectSessionLock, refreshSessionLock, releaseSessionLock, SESSION_LOCK_FILE, SessionLockHeldError,
@@ -35,6 +36,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"]),
+  restore: Object.freeze(["--repo", "--from", "--now", "--json"]),
   decide: Object.freeze(["--repo", "--text", "--session", "--now", "--json"]),
   // No --force: `lock <id> steal` is the same operation with a name that says what it
   // does, and two spellings of "take someone else's lock" is one too many.
@@ -331,6 +333,7 @@ function bootstrapOutcome(worktree, config, phase) {
   return { exit, refusal };
 }
 
+
 function branchPoint(run) {
   const base = run.slices.find((slice) => Array.isArray(slice.depends_on) && slice.depends_on.length === 0)?.base_ref;
   if (!/^[0-9a-f]{40}$/u.test(base ?? "")) throw new CliError("first seeded root slice has no immutable 40-character base_ref");
@@ -351,6 +354,7 @@ async function writeObservedEvidence({ runDir, runId, subject, attempt, branch,
   return { evidence, ancestry };
 }
 
+
 function canonicalRepositoryVerifyEvidence(evidence, { runId, run, integration, verifyCommand }) {
   const baseRef = branchPoint(run);
   const keys = Object.keys(evidence).sort();
@@ -497,6 +501,8 @@ async function verifyRecordedMerge({ repo, runDir, runId, mergeCommit }) {
 }
 
 const HANDLERS = {
+  restore: dispatchRestore,
+
   async ["reverify-repair"](positional, flags) {
     if (positional.length !== 2) throw new CliError("factory reverify-repair requires exactly <run-id> <repair-record-id>");
     const [runId, recordId] = positional;
@@ -1015,6 +1021,7 @@ const HANDLERS = {
       max_retries: run.max_retries,
       publishing_identity: run.publishing_identity ?? null,
       park_snapshot: run.status === "needs-human" ? observedParkSnapshot(resolve(flags.repo ?? process.cwd()), runId, runDir) : null,
+      restore: readRestoreRecord(runDir, run),
       pr_draft: run.pr_draft ?? true,
       lock: lock.state, dead_lock: run.status === "running" && lock.state === "stale",
       lock_session: lock.owner?.session ?? null,
@@ -1657,6 +1664,7 @@ function usage() {
   factory amend-paths <run-id> <slice-id> --add PATH [--add PATH ...] --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 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/bin/restore.js

@@ -0,0 +1,301 @@
+// False-green enforcement throughout: restore publishes preserved approvals and merged claims only after
+// the snapshot, pushed ref, Git bindings, copy, destination, and final manifest commit are re-observed.
+// Active work without those proofs is reset and reported instead of being presented as recovered.
+import { constants, chmodSync, copyFileSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, symlinkSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { basename, dirname, isAbsolute, join, relative as relativePath, resolve, sep } from "node:path";
+import { CONTROL_PLANE, validateRun } from "../state/schema.js";
+import { git, observeWorktree, privilegedPaths, proveInitContainment, unownedPaths } from "../observe/index.js";
+import { isApproving, observeMergeProof, readEvidence, readReview } from "../observe/review.js";
+import { capturePushTarget, enforceEffectivePushTarget } from "../core/effective-push.js";
+import { writeProtectedJsonAtomic } from "../core/atomic-write.js";
+
+const ID = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u;
+const SHA = /^[0-9a-f]{40}$/u;
+const RESTORE_REF = "restore.json";
+const REVIEWED_STEPS = new Set(["spec-writer", "work-decomposer"]);
+const SKIPPED_ENTRIES = new Set(["factory.lock", "run.json", "evidence/test-verifier.json", "reviews/test-verifier.json"]);
+
+class RestoreError extends Error { constructor(message, options) { super(message, options); this.name = "RestoreError"; } }
+
+function exactDirectory(path, description) {
+  let stat;
+  try { stat = lstatSync(path); } catch (error) { throw new RestoreError(`${description} '${path}' is not observable`, { cause: error }); }
+  if (stat.isSymbolicLink() || !stat.isDirectory() || realpathSync(path) !== path) throw new RestoreError(`${description} '${path}' is not an exact canonical directory`);
+}
+
+function entryState(path) { try { return lstatSync(path); } catch (error) { if (error?.code === "ENOENT") return null; throw error; } }
+
+function inventoryEntries(root, skipped = new Set()) {
+  const entries = [];
+  const visit = (relative, full) => {
+    if (skipped.has(relative)) return;
+    const stat = lstatSync(full), mode = (stat.mode & 0o7777).toString(8);
+    if (stat.isSymbolicLink()) entries.push(`${relative} l ${mode} ${readlinkSync(full)}`);
+    else if (stat.isDirectory()) {
+      entries.push(`${relative} d ${mode}`);
+      for (const name of readdirSync(full)) visit(relative === "." ? name : `${relative}/${name}`, join(full, name));
+    } else if (stat.isFile()) entries.push(`${relative} f ${mode} ${createHash("sha256").update(readFileSync(full)).digest("hex")}`);
+    else throw new RestoreError(`park snapshot contains unsupported entry type at '${full}'`);
+  };
+  visit(".", root);
+  return entries.sort();
+}
+const inventory = (root, skipped = new Set()) => JSON.stringify(inventoryEntries(root, skipped));
+
+function copySnapshot(source, target) {
+  const copy = (relative, from, to) => {
+    if (SKIPPED_ENTRIES.has(relative)) return;
+    const stat = lstatSync(from), mode = stat.mode & 0o7777, present = entryState(to);
+    if (stat.isDirectory()) {
+      if (present && (present.isSymbolicLink() || !present.isDirectory())) throw new RestoreError(`restore target '${to}' has an unsafe type`);
+      if (!present) mkdirSync(to);
+      for (const name of readdirSync(from)) copy(relative === "." ? name : `${relative}/${name}`, join(from, name), join(to, name));
+      chmodSync(to, mode);
+    } else if (present) throw new RestoreError(`restore target '${to}' already exists`);
+    else if (stat.isSymbolicLink()) {
+      const link = readlinkSync(from), lexical = relativePath(source, resolve(dirname(from), link));
+      let referent;
+      try { referent = relativePath(source, realpathSync(from)); } catch { throw new RestoreError(`park snapshot symlink '${from}' has an unprovable referent`); }
+      if (isAbsolute(link) || [lexical, referent].some((path) => path === ".." || path.startsWith(`..${sep}`) || path.startsWith(sep))) throw new RestoreError(`park snapshot symlink '${from}' escapes the control plane`);
+      symlinkSync(link, to);
+    } else if (stat.isFile()) { copyFileSync(from, to, constants.COPYFILE_EXCL); chmodSync(to, mode); }
+    else throw new RestoreError(`park snapshot contains unsupported entry type at '${from}'`);
+  };
+  copy(".", source, target);
+}
+
+function exactOid(repository, ref) {
+  const result = git(repository, ["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`]);
+  return result.status === 0 && /^[0-9a-f]{40}\n$/u.test(result.stdout) ? result.stdout.slice(0, -1) : null;
+}
+
+function assertCommit(repository, sha, description, head) {
+  if (!SHA.test(String(sha)) || exactOid(repository, sha) !== sha) throw new RestoreError(`${description} '${sha}' does not resolve in the restored repository`);
+  const ancestry = git(repository, ["merge-base", "--is-ancestor", sha, head]);
+  if (ancestry.status !== 0) throw new RestoreError(`${description} '${sha}' is not an ancestor of restored feature head '${head}'`);
+}
+
+function assertRegularRecord(runDir, ref, description) {
+  const path = resolve(runDir, ref), rel = relativePath(runDir, path), stat = entryState(path);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || rel.startsWith(sep)
+    || !stat?.isFile() || stat.isSymbolicLink() || realpathSync(path) !== path) {
+    throw new RestoreError(`${description} '${ref}' must be a contained regular file in the park snapshot`);
+  }
+}
+
+function jsonAt(runDir, ref, description) {
+  assertRegularRecord(runDir, ref, description);
+  try { return JSON.parse(readFileSync(join(runDir, ref), "utf8")); } catch (error) { throw new RestoreError(`${description} '${ref}' could not be read`, { cause: error }); }
+}
+
+function safeReview(runDir, ref) { assertRegularRecord(runDir, ref, "review"); return readReview(runDir, ref); }
+function safeEvidence(runDir, ref, runId) { assertRegularRecord(runDir, ref, "evidence"); return readEvidence(runDir, ref, { runId }); }
+
+function transformRun(source, at, head, worktree, sourceRunDir) {
+  const resetSlices = [];
+  const slices = source.slices.map((slice) => {
+    if (slice.status === "merged") return { ...slice, worktree: null };
+    if (slice.status !== "pending" || [slice.worktree, slice.branch, slice.base_ref, slice.evidence_ref, slice.review_ref, slice.merge_commit].some((value) => value !== null)) resetSlices.push(slice.id);
+    return { ...slice, status: "pending", worktree: null, branch: null, base_ref: null, evidence_ref: null, review_ref: null, merge_commit: null };
+  });
+  const invalidated = [];
+  const verifierState = source.steps.some((step) => step.agent === "test-verifier" && (step.status === "accepted" || step.review_ref || step.evidence_ref))
+    || ["evidence/test-verifier.json", "reviews/test-verifier.json"].some((ref) => entryState(join(sourceRunDir, ref)));
+  const gates = structuredClone(source.gates);
+  if (gates.pre_pr?.status === "approved") {
+    gates.pre_pr = { ...gates.pre_pr, status: "pending", at: null, reviewed_head: null };
+    invalidated.push("gate:pre_pr");
+  }
+  let validator = source.validator;
+  if (validator && validator.reviewed_head !== head) { validator = null; invalidated.push("validator"); }
+  if (verifierState) invalidated.push("step:test-verifier");
+  const steps = source.steps.map((step) => step.agent !== "test-verifier" ? step : {
+    ...step, status: step.status === "accepted" ? "running" : step.status, review_ref: null, evidence_ref: null,
+  });
+  return { run: validateRun({ ...source, worktree, updated_at: at, slices, gates, steps, validator }), resetSlices, invalidated };
+}
+
+function assertPlanBinding(runDir, run) {
+  if (run.slices.length === 0 && !run.plan_digest) return; assertRegularRecord(runDir, "plan/slices.json", "ratified slice plan");
+  const bytes = readFileSync(join(runDir, "plan/slices.json")), plan = JSON.parse(bytes);
+  if (`sha256:${createHash("sha256").update(bytes).digest("hex")}` !== run.plan_digest) throw new RestoreError("restored slice plan does not match the Brief-approved digest"); if (run.slices.length === 0) return;
+  const project = (slice) => ({ id: slice.id, stack: slice.stack, depends_on: slice.depends_on ?? [], paths: slice.paths, test_plan: slice.test_plan });
+  const ratified = Array.isArray(plan.slices) && plan.slices.length === run.slices.length && plan.slices.map((slice, index) => project({ ...slice, paths: [...slice.paths, ...(run.slices[index].path_amendments ?? []).flatMap((item) => item.added_paths)] }));
+  if (!ratified || JSON.stringify(ratified) !== JSON.stringify(run.slices.map(project))) throw new RestoreError("restored slices do not match the Brief-ratified plan and amendments");
+}
+
+function assertPreservedBindings(sourceRunDir, run, repository, head) {
+  for (const slice of run.slices.filter((entry) => entry.status === "merged")) {
+    assertCommit(repository, slice.base_ref, `slice '${slice.id}' base_ref`, head);
+    assertCommit(repository, slice.merge_commit, `slice '${slice.id}' merge_commit`, head);
+    const review = safeReview(sourceRunDir, slice.review_ref);
+    const evidence = safeEvidence(sourceRunDir, slice.evidence_ref, run.run_id);
+    if (review.subject !== slice.id || review.attempt !== slice.attempts || !isApproving(review.verdict)) throw new RestoreError(`slice '${slice.id}' review does not approve its restored attempt`);
+    if (evidence.subject !== slice.id || evidence.attempt !== slice.attempts || evidence.review_ready !== true
+      || evidence.base_ref !== slice.base_ref || evidence.commit !== review.reviewed_commit) {
+      throw new RestoreError(`slice '${slice.id}' evidence does not bind its restored base, attempt, and approved commit`);
+    }
+    for (const [name, sha] of [["reviewed_commit", review.reviewed_commit], ["evidence base_ref", evidence.base_ref], ["evidence commit", evidence.commit]]) assertCommit(repository, sha, `slice '${slice.id}' ${name}`, head);
+    if (git(repository, ["merge-base", "--is-ancestor", slice.base_ref, review.reviewed_commit]).status !== 0) throw new RestoreError(`slice '${slice.id}' base is not an ancestor of its reviewed commit`);
+    const observed = observeWorktree(repository, slice.base_ref, { ref: review.reviewed_commit }), files = [...observed.files_changed].sort();
+    if (!observed.diff_observed || files.length === 0 || JSON.stringify(files) !== JSON.stringify([...evidence.files_changed].sort()) || unownedPaths(files, slice.paths).length || privilegedPaths(files).length) throw new RestoreError(`slice '${slice.id}' restored diff violates its evidence or ratified path ownership`);
+    const tests = evidence.tests, skip = `test_plan for '${slice.id}' was approved empty at slices-seed`;
+    if (slice.test_plan.length ? !(tests?.observed === true && tests.exit === 0 && slice.test_plan.includes(tests.cmd))
+      : !(tests?.observed === false && tests.exit === null && tests.skipped_reason === skip)) throw new RestoreError(`slice '${slice.id}' evidence does not satisfy its ratified test_plan`);
+    const proof = observeMergeProof(repository, { baseRef: slice.base_ref, reviewedCommit: review.reviewed_commit, mergeCommit: slice.merge_commit });
+    if (!proof.proven) throw new RestoreError(`slice '${slice.id}' merge proof failed after restore: ${proof.reason}`);
+  }
+  for (const step of run.steps.filter((entry) => entry.status === "accepted" && REVIEWED_STEPS.has(entry.agent))) {
+    if (!step.review_ref) throw new RestoreError(`accepted step '${step.agent}' has no review binding`);
+    const review = safeReview(sourceRunDir, step.review_ref);
+    if (review.subject !== step.agent || review.attempt !== step.attempts || !isApproving(review.verdict)) throw new RestoreError(`step '${step.agent}' review does not approve its restored attempt`);
+  }
+  for (const [name, gate] of Object.entries(run.gates)) if (gate.reviewed_head) assertCommit(repository, gate.reviewed_head, `gate '${name}' reviewed_head`, head);
+  if (run.validator) {
+    assertCommit(repository, run.validator.reviewed_head, "validator reviewed_head", head);
+    const review = safeReview(sourceRunDir, "reviews/implementation-validator.json");
+    if (review.subject !== "implementation-validator" || review.reviewed_commit !== head || review.verdict !== run.validator.verdict) throw new RestoreError("validator review does not bind the restored verdict and feature head");
+  }
+}
+
+function restoredWorktree(recorded, runId) {
+  if (!isAbsolute(recorded)) return recorded;
+  const marker = `${sep}.factory-sandboxes${sep}${runId}`, at = resolve(recorded).lastIndexOf(marker);
+  if (at < 0) throw new RestoreError(`snapshot integration worktree '${recorded}' does not identify run '${runId}'`);
+  const suffix = resolve(recorded).slice(at + marker.length);
+  if (suffix !== "" && !suffix.startsWith(sep)) throw new RestoreError(`snapshot integration worktree '${recorded}' cannot be rebound`);
+  return suffix === "" ? "." : suffix.slice(1);
+}
+
+function qualifySource(operatorRoot, runId) {
+  const factory = join(operatorRoot, CONTROL_PLANE), parked = join(factory, ".parked"), source = join(parked, runId);
+  for (const [path, description] of [[factory, "operator control plane"], [parked, "park snapshot container"], [source, "park snapshot"]]) exactDirectory(path, description);
+  const manifest = join(source, "run.json"), stat = entryState(manifest);
+  if (!stat?.isFile() || stat.isSymbolicLink()) throw new RestoreError(`park snapshot manifest '${manifest}' is not a regular file`);
+  const bytes = readFileSync(manifest), run = validateRun(JSON.parse(bytes.toString("utf8")));
+  if (run.run_id !== runId) throw new RestoreError(`park snapshot run_id '${run.run_id}' does not match requested '${runId}'`);
+  if (run.status !== "needs-human") throw new RestoreError(`factory restore requires a needs-human snapshot; found '${run.status}'`);
+  const entries = inventoryEntries(source), skipped = [...SKIPPED_ENTRIES];
+  return { source, bytes, run, inventory: JSON.stringify(entries),
+    copied: JSON.stringify(entries.filter((entry) => !skipped.some((name) => entry.startsWith(`${name} `) || entry.startsWith(`${name}/`)))) };
+}
+
+function validateFeatureRef(repository, ref, branch) {
+  const listed = git(repository, ["remote"]);
+  const remotes = listed.status === 0 ? listed.stdout.split("\n").filter((name) => ref === `refs/remotes/${name}/${branch}`) : [];
+  const remote = remotes.length === 1 ? remotes[0] : null;
+  if (!remote) throw new RestoreError(`--from must name exact branch '${branch}' under one configured remote`);
+  const state = git(repository, ["show-ref", "--verify", "--quiet", ref]);
+  if (state.status !== 0) throw new RestoreError(`restore feature ref '${ref}' is absent or unobservable in operator repository '${repository}'`);
+  const head = exactOid(repository, ref);
+  if (!head) throw new RestoreError(`restore feature ref '${ref}' does not peel to one commit`);
+  const sourcePush = capturePushTarget(repository, remote), effectivePush = capturePushTarget(repository);
+  if (!sourcePush || !effectivePush || !sourcePush.equals(effectivePush) || !Buffer.from(sourcePush.toString("utf8"), "utf8").equals(sourcePush)) throw new RestoreError(`restore remote '${remote}' is not the operator's effective push endpoint`);
+  const endpoint = sourcePush.toString("utf8");
+  const remoteRef = `refs/heads/${branch}`, advertised = git(repository, ["ls-remote", "--exit-code", "--refs", endpoint, remoteRef]);
+  if (advertised.status !== 0 || advertised.stdout !== `${head}\t${remoteRef}\n`) throw new RestoreError(`restore feature ref '${ref}' does not match branch '${branch}' as advertised by remote '${remote}'`);
+  return head;
+}
+
+// False-green enforcement: local excludes do not survive the clone, so only the tracked root policy may
+// prove that restored control-plane state stays outside the repository diff and cleanliness checks.
+function assertIgnored(repository, runId, probes = [`.factory-sandboxes/${runId}/.factory/${runId}/run.json`, `${CONTROL_PLANE}/${runId}/run.json`]) {
+  const rootIgnore = join(repository, ".gitignore");
+  const tracked = git(repository, ["ls-files", "--error-unmatch", "--", ".gitignore"]);
+  for (const probe of probes) {
+    const observed = git(repository, ["check-ignore", "-v", "--no-index", "--", probe]);
+    const match = /^(.+):([1-9][0-9]*):(.+)\t(.+)\n$/u.exec(observed.status === 0 ? observed.stdout : "");
+    if (tracked.status !== 0 || tracked.stdout !== ".gitignore\n" || match?.[3].startsWith("!") || match?.[4] !== probe || resolve(repository, match?.[1] ?? "") !== rootIgnore) {
+      throw new RestoreError(`factory restore requires '${probe}' to be ignored by tracked root '.gitignore'`);
+    }
+  }
+}
+
+function assertRestoreBinding({ operatorRoot, sandbox, runId, branch, worktree, featureRef, head, source }) {
+  for (const [path, description] of [[join(operatorRoot, CONTROL_PLANE), "operator control plane"], [join(operatorRoot, CONTROL_PLANE, ".parked"), "park snapshot container"], [source, "park snapshot"], [join(operatorRoot, ".factory-sandboxes"), "sandbox container"], [sandbox, "restore sandbox"]]) exactDirectory(path, description);
+  if (validateFeatureRef(operatorRoot, featureRef, branch) !== head) throw new RestoreError(`restore feature ref '${featureRef}' moved while restore was running`);
+  const symbolic = git(sandbox, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  if (symbolic.status !== 0 || symbolic.stdout !== `${branch}\n` || exactOid(sandbox, "HEAD") !== head) throw new RestoreError(`restored feature branch '${branch}' moved while restore was running`);
+  const cleanliness = git(sandbox, ["status", "--porcelain", "--untracked-files=normal"]);
+  if (cleanliness.status !== 0 || cleanliness.stdout !== "") throw new RestoreError("restored feature worktree changed while restore was running");
+  enforceEffectivePushTarget(["check", operatorRoot, sandbox]);
+  assertIgnored(operatorRoot, runId);
+  assertIgnored(sandbox, runId, [`${CONTROL_PLANE}/${runId}/run.json`]);
+  proveInitContainment({ operatorRoot, sandboxPath: sandbox, runId, worktree });
+}
+
+export async function dispatchRestore(positional, flags, operations = {}) {
+  if (positional.length !== 1 || !ID.test(positional[0])) throw new RestoreError("factory restore requires exactly one valid <run-id>");
+  if (flags.repo !== undefined && (typeof flags.repo !== "string" || !flags.repo.trim())) throw new RestoreError("--repo must be a non-empty string");
+  if (!flags.from) throw new RestoreError("factory restore requires --from <full-remote-tracking-ref>");
+  const runId = positional[0], operatorInput = resolve(flags.repo ?? process.cwd()), operatorRoot = realpathSync(operatorInput);
+  exactDirectory(operatorRoot, "operator repository");
+  const top = git(operatorRoot, ["rev-parse", "--show-toplevel"]);
+  if (!top.ok || resolve(operatorRoot, top.stdout.trim()) !== operatorRoot) throw new RestoreError("--repo must name the canonical operator repository root");
+  const qualified = qualifySource(operatorRoot, runId);
+  const worktree = restoredWorktree(qualified.run.worktree, runId);
+  const atMs = flags.now === undefined ? Date.now() : Date.parse(flags.now), at = Number.isFinite(atMs) ? new Date(atMs).toISOString() : null;
+  if (!at) throw new RestoreError("--now must be an ISO timestamp");
+  if (atMs <= Date.parse(qualified.run.updated_at)) throw new RestoreError("restore must move updated_at forwards");
+  if (git(operatorRoot, ["check-ref-format", "--branch", qualified.run.branch]).status !== 0) throw new RestoreError(`snapshot branch '${qualified.run.branch}' is not a valid branch name`);
+  const head = validateFeatureRef(operatorRoot, flags.from, qualified.run.branch);
+  assertIgnored(operatorRoot, runId);
+  const legacyManifest = join(operatorRoot, CONTROL_PLANE, runId, "run.json");
+  if (entryState(legacyManifest)) throw new RestoreError(`live run manifest already exists at '${legacyManifest}'`);
+  const container = join(operatorRoot, ".factory-sandboxes"), sandbox = join(container, runId);
+  const containerState = entryState(container);
+  if (containerState) exactDirectory(container, "sandbox container"); else mkdirSync(container);
+  if (entryState(sandbox)) throw new RestoreError(`restore sandbox destination '${sandbox}' already exists`);
+  mkdirSync(sandbox);
+  const cloned = git(operatorRoot, ["clone", "--local", "--no-checkout", "--", operatorRoot, sandbox]);
+  if (!cloned.ok) throw new RestoreError(`git clone failed for restore sandbox '${sandbox}'; sandbox was retained; run.json is absent`);
+  const switched = git(sandbox, ["switch", "--no-track", "-C", qualified.run.branch, head]);
+  if (!switched.ok) throw new RestoreError(`could not restore feature branch '${qualified.run.branch}' at '${head}'; sandbox was retained; run.json is absent`);
+  enforceEffectivePushTarget(["bootstrap", operatorRoot, sandbox]);
+  proveInitContainment({ operatorRoot, sandboxPath: sandbox, runId, worktree });
+  const runDir = join(sandbox, CONTROL_PLANE, runId), transformed = transformRun(qualified.run, at, head, worktree, qualified.source);
+  copySnapshot(qualified.source, runDir);
+  const copiedInventory = inventory(runDir);
+  if (copiedInventory !== qualified.copied) throw new RestoreError(`restored control-plane copy does not match the qualified snapshot; sandbox was retained; run.json is absent`);
+  assertPlanBinding(runDir, transformed.run);
+  assertPreservedBindings(runDir, transformed.run, sandbox, head);
+  const previousRestore = entryState(join(runDir, RESTORE_REF)) ? readRestoreRecord(runDir, qualified.run) : null;
+  const record = { version: 1, run_id: runId, restored_at: at, source_snapshot: qualified.source, source_inventory: `sha256:${createHash("sha256").update(qualified.inventory).digest("hex")}`, feature_ref: flags.from, feature_commit: head, reset_slices: transformed.resetSlices, invalidated: transformed.invalidated, previous_restore: previousRestore };
+  await writeProtectedJsonAtomic(runDir, RESTORE_REF, record);
+  const preparedInventory = inventory(runDir);
+  // Test seam only: production supplies no hook. The final guard below must catch any intervening writer.
+  if (operations.beforeManifest) await operations.beforeManifest({ runDir, sandbox });
+  const finalGuard = () => {
+    if (!readFileSync(join(qualified.source, "run.json")).equals(qualified.bytes) || inventory(qualified.source) !== qualified.inventory) throw new RestoreError("park snapshot changed while restore was running; run.json was not published");
+    if (inventory(runDir) !== preparedInventory) throw new RestoreError("restored control plane changed before manifest publication; run.json was not published");
+    if (entryState(legacyManifest)) throw new RestoreError(`live run manifest appeared at '${legacyManifest}' while restore was running`);
+    assertRestoreBinding({ operatorRoot, sandbox, runId, branch: qualified.run.branch, worktree, featureRef: flags.from, head, source: qualified.source });
+  };
+  await writeProtectedJsonAtomic(runDir, "run.json", transformed.run, { createOnly: true, hooks: { beforeCommit: finalGuard } });
+  const payload = { run_id: runId, status: transformed.run.status, sandbox_path: sandbox, run_dir: runDir, source_snapshot: qualified.source, feature_ref: flags.from, feature_commit: head, reset_slices: transformed.resetSlices, invalidated: transformed.invalidated, restore_record: join(runDir, RESTORE_REF) };
+  if (flags.json) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`); else for (const [key, value] of Object.entries(payload)) process.stdout.write(`${key}: ${typeof value === "object" ? JSON.stringify(value) : value}\n`);
+  return payload;
+}
+
+const RESTORE_KEYS = ["version", "run_id", "restored_at", "source_snapshot", "source_inventory", "feature_ref", "feature_commit", "reset_slices", "invalidated", "previous_restore"];
+const INVALIDATIONS = new Set(["gate:pre_pr", "validator", "step:test-verifier"]);
+function validRestoreRecord(record, runId, slices) {
+  const timestamp = typeof record?.restored_at === "string" ? Date.parse(record.restored_at) : NaN;
+  return record && !Array.isArray(record) && JSON.stringify(Object.keys(record).sort()) === JSON.stringify([...RESTORE_KEYS].sort())
+    && record.version === 1 && record.run_id === runId && ID.test(runId) && Number.isFinite(timestamp) && new Date(timestamp).toISOString() === record.restored_at
+    && typeof record.source_snapshot === "string" && isAbsolute(record.source_snapshot) && /^sha256:[0-9a-f]{64}$/u.test(record.source_inventory)
+    && /^refs\/remotes\/.+\/.+$/u.test(record.feature_ref) && SHA.test(record.feature_commit)
+    && Array.isArray(record.reset_slices) && new Set(record.reset_slices).size === record.reset_slices.length && record.reset_slices.every((id) => ID.test(id) && (!slices || slices.has(id)))
+    && Array.isArray(record.invalidated) && new Set(record.invalidated).size === record.invalidated.length && record.invalidated.every((item) => INVALIDATIONS.has(item))
+    && (record.previous_restore === null || validRestoreRecord(record.previous_restore, runId, slices));
+}
+
+export function readRestoreRecord(runDir, run = null) {
+  const path = join(runDir, RESTORE_REF), stat = entryState(path);
+  if (!stat) return null;
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new RestoreError(`restore record '${path}' is not a regular file`);
+  const record = jsonAt(runDir, RESTORE_REF, "restore record");
+  if (!validRestoreRecord(record, basename(runDir), run && new Set(run.slices.map((slice) => slice.id)))) throw new RestoreError(`restore record '${path}' is malformed`);
+  return record;
+}

package/core/atomic-write.js

@@ -1,10 +1,11 @@
-// Exclusive same-directory temp, then fsync of the file and of the directory. The directory fsync is
+// Ordinary writes use an exclusive same-directory temp; every write fsyncs its file and directory. Directory fsync is
 // what makes a completed publication survive power loss, and attack 9 (crash-recovery replay) rests
 // on it. Ordinary writes recheck the target immediately before the rename, not only up front: this
 // writes into a working tree, so a local process swapping run.json for a symlink inside that window
 // is a real failure mode and an up-front-only check is a TOCTOU hole. Create-only writes preflight
-// absence and publish by link. beforeCommit is the last race seam, used by CAS and create-only tests.
-import { link as fsLink, lstat, open, rename as fsRename, unlink } from "node:fs/promises";
+// absence, then write through the protected target's held mode-000 inode; only verified, fsynced bytes
+// become readable. beforeCommit is the last race seam used by CAS and create-only tests.
+import { lstat, open, realpath, rename as fsRename, unlink } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { isAbsolute, join, resolve, sep } from "node:path";
 
@@ -20,72 +21,83 @@ export function writeProtectedJsonAtomic(rootDir, relativePath, value, options =
 }
 
 export async function writeProtectedFileAtomic(rootDir, relativePath, data, options = {}) {
-  const targetPath = resolveProtectedPath(rootDir, relativePath);
-  const parentDir = resolve(targetPath, "..");
-  const createOnly = options.createOnly === true;
-  const rename = options.fsOps?.rename ?? fsRename;
-  const link = options.fsOps?.link ?? fsLink;
-  const beforeCommit = options.hooks?.beforeCommit;
-  const bytes = Buffer.isBuffer(data) ? data : Buffer.from(String(data), "utf8");
-
+  const targetPath = resolveProtectedPath(rootDir, relativePath), parentDir = resolve(targetPath, "..");
+  const createOnly = options.createOnly === true, beforeCommit = options.hooks?.beforeCommit;
+  const openFile = options.fsOps?.open ?? open;
+  const bytes = Buffer.isBuffer(data) ? Buffer.from(data) : Buffer.from(String(data), "utf8");
+  await assertSafeParent(rootDir, parentDir);
   await assertSafeTarget(targetPath, createOnly);
+  if (createOnly) return writeProtectedCreate(rootDir, parentDir, targetPath, bytes, beforeCommit, openFile);
 
-  const tempPath = join(parentDir, `.${randomUUID()}.tmp`);
-  let handle = null;
-  let published = false;
+  const tempPath = join(parentDir, `.${randomUUID()}.tmp`), rename = options.fsOps?.rename ?? fsRename;
+  let handle = null, published = false, targetLinked = false;
   try {
-    // "wx" is O_CREAT|O_EXCL|O_WRONLY: if the name exists, fail rather than adopt
-    // a file somebody else created.
-    handle = await open(tempPath, "wx", 0o600);
+    handle = await openFile(tempPath, "wx+", 0o600);
     await handle.writeFile(bytes);
     await handle.sync();
+    if (typeof beforeCommit === "function") await beforeCommit();
+    await assertSafeParent(rootDir, parentDir);
+    await assertSafeTarget(targetPath, false);
+    await assertPublishedInode(handle, tempPath, bytes);
+    await rename(tempPath, targetPath);
+    targetLinked = true;
+    await assertPublishedInode(handle, targetPath, bytes);
     await handle.close();
     handle = null;
-
-    if (createOnly) {
-      await assertSafeTarget(targetPath, true);
-      if (typeof beforeCommit === "function") await beforeCommit();
-      try { await link(tempPath, targetPath); } catch (error) {
-        if (error?.code === "EEXIST") throw new ProtectedWriteError("protected create target already exists", error);
-        throw error;
-      }
-      published = true;
-      try { await unlink(tempPath); } catch (cleanupError) {
-        try { await unlink(tempPath); } catch (retryError) {
-          if (retryError?.code !== "ENOENT") {
-            throw new ProtectedWriteError("protected create published target but temporary cleanup is indeterminate", retryError);
-          }
-        }
-        throw new ProtectedWriteError("protected create published target but initial temporary cleanup failed", cleanupError);
-      }
-    } else {
-      if (typeof beforeCommit === "function") await beforeCommit();
-      await assertSafeTarget(targetPath, false);
-      await rename(tempPath, targetPath);
-      published = true;
-    }
+    published = true;
   } catch (error) {
-    if (handle) {
-      try { await handle.close(); } catch { /* the original error is the one that matters */ }
-    }
-    if (!published) {
-      try {
-        await unlink(tempPath);
-      } catch (cleanupError) {
-        if (cleanupError?.code !== "ENOENT") {
-          throw new ProtectedWriteError("protected temporary file cleanup is indeterminate", cleanupError);
-        }
-      }
+    if (handle) try { await handle.close(); } catch { /* the original error is primary */ }
+    if (targetLinked && !published) try { await unlink(targetPath); } catch { /* integrity failure is primary */ }
+    if (!published) try { await unlink(tempPath); } catch (cleanupError) {
+      if (cleanupError?.code !== "ENOENT") throw new ProtectedWriteError("protected temporary file cleanup is indeterminate", cleanupError);
     }
-    throw error instanceof ProtectedWriteError
-      ? error
-      : new ProtectedWriteError("protected file commit failed", error);
+    throw error instanceof ProtectedWriteError ? error : new ProtectedWriteError("protected file commit failed", error);
   }
+  await syncDirectory(parentDir);
+  return { path: targetPath };
+}
 
+async function writeProtectedCreate(rootDir, parentDir, targetPath, bytes, beforeCommit, openFile) {
+  let handle = null;
+  try {
+    if (typeof beforeCommit === "function") await beforeCommit();
+    await assertSafeParent(rootDir, parentDir);
+    await assertSafeTarget(targetPath, true);
+    try { handle = await openFile(targetPath, "wx+", 0o000); } catch (error) {
+      if (error?.code === "EEXIST") throw new ProtectedWriteError("protected create target already exists", error);
+      throw error;
+    }
+    await handle.writeFile(bytes);
+    await handle.sync();
+    await assertPublishedInode(handle, targetPath, bytes);
+    await handle.chmod(0o600);
+    await handle.sync();
+    await assertPublishedInode(handle, targetPath, bytes);
+    await handle.close();
+    handle = null;
+  } catch (error) {
+    if (handle) try { await handle.close(); } catch { /* the original error is primary */ }
+    // Never unlink by pathname after claiming it: a competitor could have replaced that name.
+    // A failed direct create remains mode 000 and blocks reuse instead of exposing uncertain state.
+    throw error instanceof ProtectedWriteError ? error : new ProtectedWriteError("protected file commit failed", error);
+  }
   await syncDirectory(parentDir);
   return { path: targetPath };
 }
 
+async function assertPublishedInode(handle, targetPath, bytes) {
+  const [held, named] = await Promise.all([handle.stat(), lstat(targetPath)]);
+  const observed = Buffer.alloc(bytes.length + 1), read = await handle.read(observed, 0, observed.length, 0);
+  if (!named.isFile() || held.dev !== named.dev || held.ino !== named.ino || read.bytesRead !== bytes.length
+    || !observed.subarray(0, bytes.length).equals(bytes)) throw new ProtectedWriteError("protected publication inode or bytes changed before commit");
+}
+
+async function assertSafeParent(rootDir, parentDir) {
+  const root = resolve(rootDir), rel = resolve(parentDir).slice(root.length + 1);
+  let observed; try { observed = await realpath(parentDir); } catch (error) { throw new ProtectedWriteError("protected file parent could not be inspected", error); }
+  if (observed !== resolve(await realpath(root), rel)) throw new ProtectedWriteError("protected file parent has an unsafe symlink");
+}
+
 function resolveProtectedPath(rootDir, relativePath) {
   if (typeof rootDir !== "string" || !rootDir.trim() || !isAbsolute(rootDir)) {
     throw new ProtectedWriteError("protected file root is invalid");

package/core/effective-push.js

@@ -20,10 +20,10 @@ function execute(run, args) {
   });
 }
 
-function capture(run, repository) {
+export function capturePushTarget(repository, remote = "origin", run = spawnSync) {
   let result;
   try {
-    result = execute(run, ["-C", repository, "remote", "get-url", "--push", "origin"]);
+    result = execute(run, ["-C", repository, "remote", "get-url", "--push", remote]);
   } catch {
     return null;
   }
@@ -62,7 +62,7 @@ export function enforceEffectivePushTarget(positionals, { spawnSync: run = spawn
   const [operation, operatorRepository, sandboxRepository] = positionals;
   if (operation !== "bootstrap" && operation !== "check") throw failure(OPERATION_ERROR);
 
-  let operatorTarget = capture(run, operatorRepository);
+  let operatorTarget = capturePushTarget(operatorRepository, "origin", run);
   if (operatorTarget === null) {
     throw failure(`factory sandbox: operator effective push target unavailable; sandbox retained at ${sandboxRepository}`);
   }
@@ -73,12 +73,12 @@ export function enforceEffectivePushTarget(positionals, { spawnSync: run = spawn
     if (!configure(run, sandboxRepository, operatorTarget.toString("utf8"))) {
       throw failure(`factory sandbox: sandbox effective push target unavailable at ${sandboxRepository}`);
     }
-    operatorTarget = capture(run, operatorRepository);
+    operatorTarget = capturePushTarget(operatorRepository, "origin", run);
     if (operatorTarget === null) {
       throw failure(`factory sandbox: operator effective push target unavailable; sandbox retained at ${sandboxRepository}`);
     }
   }
-  const sandboxTarget = capture(run, sandboxRepository);
+  const sandboxTarget = capturePushTarget(sandboxRepository, "origin", run);
   if (sandboxTarget === null) {
     throw failure(`factory sandbox: sandbox effective push target unavailable at ${sandboxRepository}`);
   }

package/observe/repository-config.js

@@ -16,8 +16,12 @@ export function parseRepositoryConfig(bytes) {
   // resolved by `init` from a flag or the environment and recorded in `run.json`. The allowed set below is
   // closed, so a file still carrying the key is malformed rather than silently ignored -- which is what
   // makes the removal visible to whoever has to edit it.
-  const requiredKeys = ["publish", "resolve", "verify"];
-  const allowedKeys = [...requiredKeys, "pr_draft", "verify_timeout_ms", "bootstrap", "bootstrap_timeout_ms"];
+  // `publish` was required from #308 and invoked nowhere, so every consumer wrote a command that could
+  // not run -- and a reader who saw it reasonably concluded the factory owned publication, which it does
+  // 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"];
   if (!config || typeof config !== "object" || Array.isArray(config)
     || Object.keys(config).some((keyName) => !allowedKeys.includes(keyName))) {
     throw new RepositoryConfigError("invalid .factory.json");
@@ -43,6 +47,12 @@ export function parseRepositoryConfig(bytes) {
   if (requiredKeys.some((keyName) => typeof config[keyName] !== "string" || !config[keyName].trim())) {
     throw new RepositoryConfigError("invalid .factory.json");
   }
+  // Optional does not mean unchecked: an empty or non-string `publish` is a declared command that cannot
+  // run, which is the state this key was already in and the one worth refusing loudly.
+  if (optionalCommandKeys.some((keyName) => Object.hasOwn(config, keyName)
+    && (typeof config[keyName] !== "string" || !config[keyName].trim()))) {
+    throw new RepositoryConfigError("invalid .factory.json: entry 'publish' must be a non-empty string");
+  }
   const parsed = { command: config.verify, timeoutMs: config.verify_timeout_ms ?? DEFAULT_REPOSITORY_VERIFY_TIMEOUT_MS,
     prDraft: config.pr_draft ?? true };
   return hasBootstrap ? { ...parsed, bootstrapCommand: config.bootstrap,

package/package.json

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