Serialize restore recovery and rebase manifest paths

docs/internal/command-restore.md

@@ -8,8 +8,8 @@ reporting flow in `internal/app`. User invocation belongs in
 physical restore scope belong in
 [Operations](../operations.md#restore-workflow).
 
-Restore is split into explicit phases so remote authority, local conflict
-policy, and filesystem mutation can be tested independently.
+Restore separates remote authority, local conflict policy, and filesystem
+mutation so each remains testable independently.
 
 ## Discovery Contract
 
@@ -40,6 +40,9 @@ Planner behavior:
 - force converts differing eligible regular files from conflicts to downloads;
   directories and other non-regular targets remain conflicts.
 
+For a non-dry-run restore, planning/classification happens only after acquiring
+the session lock. Runner manifest/reuse checks acquire that same lock first.
+
 Previous-cache files are planned separately through `previouscache.BuildPlan`
 when configured previous-session requirements exist.
 
@@ -54,6 +57,13 @@ Execution order and safety:
 - each committed object is verified against its declared checksum, size, and
   generation before installation;
 - failed installs do not roll back files already written in the same execution.
+- a durable `.restore-incomplete.json` marker is written before installation.
+  It blocks runners until a restore retry completes all verified installs and
+  the local manifest replacement, at which point it is removed.
+- restored manifest local references are rebased beneath the selected local
+  session root. Unsafe relative references and producer-machine absolute paths
+  outside the manifest's producer session root are rejected; producer-local
+  spool/cache and cleanup locations are not restored as authority.
 
 Audio restore path:
 

docs/operations.md

@@ -283,6 +283,12 @@ Optional:
 
 Restore writes an execution report at `reports/restore-latest.json`.
 
+If restore fails after beginning installation, it leaves a durable
+`.restore-incomplete.json` marker in the session root. Pipeline runs will stop
+until you rerun the same restore command and it completes. Restore intentionally
+does not try to roll back files already installed; retrying the selected remote
+snapshot is the recovery procedure.
+
 ## Local State Layout
 
 Session root:

docs/policy/architecture.md

@@ -119,6 +119,12 @@ install the validated session manifest after other restored durable files. The
 physical workflow and recovery procedures belong in
 [Operations](../operations.md).
 
+Restore and runner transitions for one session use the same local lock. A
+durable incomplete-restore marker blocks runner reuse after a partial restore;
+safe retry, rather than rollback of arbitrary local effects, is the recovery
+mechanism. Restored manifest-local references must be confined to the selected
+local session root, never trusted as producer-machine absolute paths.
+
 For the immutable remote-commit protocol, a restore or status operation binds
 to one pointer-selected commit and only its declared object identities. A force
 flag may replace an eligible regular managed file, but never turns a directory

docs/roadmap/implementation.md

@@ -33,7 +33,7 @@ All stages are pending when this plan is created.
 | 15 | Make remote locks generation-safe and harden pagination | RSK-005, RSK-014 | Completed |
 | 16 | Persist retryable post-commit cleanup state | COR-006, COR-007 | Completed |
 | 17 | Bind restore/status to a committed snapshot and reject conflicts | COR-008, COR-009, TST-005 | Completed |
-| 18 | Serialize restore transitions and make restored paths portable | RSK-006, RSK-008 | Pending |
+| 18 | Serialize restore transitions and make restored paths portable | RSK-006, RSK-008 | Completed |
 | 19 | Bind audio cache reuse to remote object identity | RSK-007 | Pending |
 | 20 | Unify previous-source readiness and eliminate duplicate transfers | COR-010, EFF-001 | Pending |
 | 21 | Tighten configuration parsing, values, and expectations | COR-012–COR-015, TST-011, TST-014 | Pending |