fix(runtime): recover retained native pools and graph owners

.ai/skills/hack-repo-verify/SKILL.md

@@ -53,7 +53,7 @@ untracked candidate additions. Keep private artifacts excluded from the index.
 | Rust state/recovery | `packages/runtime-core/tests/` plus module tests; malformed/stale ownership, crash window, resume and data preservation |
 | TLA models | `test:models`, [model mappings](../../../tests/models/tla/README.md), [runner](../../../scripts/check-tla-models.ts) and expected positive/negative controls |
 | Consumer instructions | [ownership](../../../docs/agent-guidance.md), `bun run generate:agent-plugins`, affected examples and source/render tests |
-| Native VM/routing/reclamation | candidate guide (local `_docs/docs/plans/v5/development.md`), relevant ledger gate and isolated host fixture; Linux checks cannot qualify macOS effects |
+| Native VM/routing/reclamation | [candidate guide](../../../docs/guides/native-candidate.md), relevant acceptance gate and isolated host fixture; Linux checks cannot qualify macOS effects |
 | Resource/performance claims | [performance skill](../hack-repo-performance/SKILL.md), matched workload and measured boundaries |
 
 Read [CI](../../../.github/workflows/ci.yml) for current hosted gates. A local pass
@@ -63,6 +63,14 @@ not default local-product requirements; use them only for explicitly scoped work
 ## Verify the verifier
 
 Treat unavailable prerequisites, ignored tests, cached results and timeouts explicitly.
+Before an ignored native graph fixture, read its prerequisites in the
+[runtime README](../../../packages/runtime-core/README.md). Some fixtures require
+a caller-prepared pool: use the managed provider, engine and network-tool setup,
+start the required socket capacity, load the pinned image, and verify runtime
+status before invoking the test. Record the current-source test executable and
+candidate bundle separately. An unprepared-pool failure does not exercise the
+scenario; preserve its evidence and fix setup before rerunning.
+
 TLC must explore the intended states; its negative control must fail the named
 invariant with the expected trace, not merely return nonzero. A small abstract model
 needs source mapping and implementation regression evidence; use

docs/reference/cli.md

@@ -1263,6 +1263,10 @@ hack doctor [options]
 | `--json` | Output JSON (machine-readable) |
 | `--browser-url https://app.hack` | HTTPS origin manually tested in the browser (no path or credentials) |
 | `--browser-result unknown|works|fails|permission-denied` | Your manual browser observation for --browser-url (default: unknown) |
+| `--branch <name>` | Run against a branch-specific instance (compose name + hostnames) |
+| `--native-run-mapping inspect|repair` | Inspect or explicitly repair a native run mapping after filesystem device renumbering |
+| `--expect-selection <64-hex>` | Require the exact run-mapping recovery inspection selection |
+| `--accept-legacy-device-rebind` | Explicitly accept legacy migration without proof of original filesystem volume continuity |
 | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
 | `--help, -h` | Show help |
 | `--version, -v` | Show version |

packages/runtime-core/src/graph_cli.rs

@@ -25,6 +25,310 @@ pub fn command(candidate: &Candidate, args: &[&str]) -> Result<Value, CandidateE
     let Some((action, args)) = args.split_first() else {
         return Err(invalid());
     };
+    if *action == "inspect-interrupted-start-cleanup" {
+        let run = match *args {
+            ["--run-id", run] | ["--run-id", run, "--json"] => run,
+            _ => return Err(invalid()),
+        };
+        #[cfg(target_os = "macos")]
+        {
+            return graph::inspect_interrupted_start_cleanup(candidate, run);
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = run;
+            return Err(invalid());
+        }
+    }
+    if *action == "recover-interrupted-start-cleanup" {
+        let (run, expected) = match *args {
+            [
+                "--run-id",
+                run,
+                "--expect-selection",
+                expected,
+                "--retain-data",
+            ]
+            | [
+                "--run-id",
+                run,
+                "--expect-selection",
+                expected,
+                "--retain-data",
+                "--json",
+            ] => (run, expected),
+            _ => return Err(invalid()),
+        };
+        #[cfg(target_os = "macos")]
+        {
+            return graph::recover_interrupted_start_cleanup(candidate, run, expected);
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = (run, expected);
+            return Err(invalid());
+        }
+    }
+    if *action == "release-acknowledged-dependencies" {
+        let (run, owner, receipt, publisher, reservation) = match *args {
+            [
+                "--run-id",
+                run,
+                "--expect-owner",
+                owner,
+                "--expect-receipt",
+                receipt,
+                "--expect-publisher",
+                publisher,
+                "--expect-reservation",
+                reservation,
+            ]
+            | [
+                "--run-id",
+                run,
+                "--expect-owner",
+                owner,
+                "--expect-receipt",
+                receipt,
+                "--expect-publisher",
+                publisher,
+                "--expect-reservation",
+                reservation,
+                "--json",
+            ] => (run, owner, receipt, publisher, reservation),
+            _ => return Err(invalid()),
+        };
+        #[cfg(target_os = "macos")]
+        {
+            return graph::release_acknowledged_dependencies(
+                candidate,
+                graph::AcknowledgedPublisherSelection {
+                    run,
+                    owner,
+                    receipt_sha256: receipt,
+                    publisher_sha256: publisher,
+                },
+                reservation,
+            );
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = (run, owner, receipt, publisher, reservation);
+            return Err(invalid());
+        }
+    }
+    if *action == "retire-acknowledged-publisher" {
+        let (run, owner, receipt, publisher) = match *args {
+            [
+                "--run-id",
+                run,
+                "--expect-owner",
+                owner,
+                "--expect-receipt",
+                receipt,
+                "--expect-publisher",
+                publisher,
+            ]
+            | [
+                "--run-id",
+                run,
+                "--expect-owner",
+                owner,
+                "--expect-receipt",
+                receipt,
+                "--expect-publisher",
+                publisher,
+                "--json",
+            ] => (run, owner, receipt, publisher),
+            _ => return Err(invalid()),
+        };
+        #[cfg(target_os = "macos")]
+        {
+            return graph::retire_acknowledged_publisher(
+                candidate,
+                graph::AcknowledgedPublisherSelection {
+                    run,
+                    owner,
+                    receipt_sha256: receipt,
+                    publisher_sha256: publisher,
+                },
+            );
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = (run, owner, receipt, publisher);
+            return Err(invalid());
+        }
+    }
+    if *action == "inspect-host-pin-recovery" {
+        let run = match *args {
+            ["--run-id", run] | ["--run-id", run, "--json"] => run,
+            _ => return Err(invalid()),
+        };
+        #[cfg(target_os = "macos")]
+        {
+            return graph::inspect_host_pin_recovery(candidate, run);
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = run;
+            return Err(invalid());
+        }
+    }
+    if *action == "recover-host-pins" {
+        let (run, expected) = match *args {
+            [
+                "--run-id",
+                run,
+                "--expect-selection",
+                expected,
+                "--accept-legacy-device-rebind",
+            ]
+            | [
+                "--run-id",
+                run,
+                "--expect-selection",
+                expected,
+                "--accept-legacy-device-rebind",
+                "--json",
+            ] => (run, expected),
+            _ => return Err(invalid()),
+        };
+        #[cfg(target_os = "macos")]
+        {
+            return graph::recover_host_pins(candidate, run, expected);
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = (run, expected);
+            return Err(invalid());
+        }
+    }
+    if *action == "inspect-absent-publication-cleanup" {
+        let (run, original, inspection) = match *args {
+            [
+                "--run-id",
+                run,
+                "--original-owner-file",
+                original,
+                "--host-inspection-file",
+                inspection,
+            ]
+            | [
+                "--run-id",
+                run,
+                "--original-owner-file",
+                original,
+                "--host-inspection-file",
+                inspection,
+                "--json",
+            ] => (run, original, inspection),
+            _ => return Err(invalid()),
+        };
+        #[cfg(target_os = "macos")]
+        {
+            return graph::inspect_absent_publication_cleanup(
+                candidate,
+                run,
+                Path::new(original),
+                Path::new(inspection),
+            );
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = (run, original, inspection);
+            return Err(invalid());
+        }
+    }
+    if *action == "recover-absent-publication-cleanup" {
+        let (run, original, inspection, expected) = match *args {
+            [
+                "--run-id",
+                run,
+                "--original-owner-file",
+                original,
+                "--host-inspection-file",
+                inspection,
+                "--expect-selection",
+                expected,
+                "--retain-data",
+                "--accept-unpinned-post-reboot",
+            ]
+            | [
+                "--run-id",
+                run,
+                "--original-owner-file",
+                original,
+                "--host-inspection-file",
+                inspection,
+                "--expect-selection",
+                expected,
+                "--retain-data",
+                "--accept-unpinned-post-reboot",
+                "--json",
+            ] => (run, original, inspection, expected),
+            _ => return Err(invalid()),
+        };
+        #[cfg(target_os = "macos")]
+        {
+            return graph::recover_absent_publication_cleanup(
+                candidate,
+                run,
+                expected,
+                Path::new(original),
+                Path::new(inspection),
+            );
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = (run, original, inspection, expected);
+            return Err(invalid());
+        }
+    }
+    if *action == "inspect-source-device-rebind" {
+        let run = match *args {
+            ["--run-id", run] | ["--run-id", run, "--json"] => run,
+            _ => return Err(invalid()),
+        };
+        #[cfg(target_os = "macos")]
+        {
+            return graph::inspect_source_device_rebind(candidate, run);
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = run;
+            return Err(invalid());
+        }
+    }
+    if *action == "recover-source-device-rebind" {
+        let (run, expected) = match *args {
+            [
+                "--run-id",
+                run,
+                "--expect-selection",
+                expected,
+                "--accept-legacy-device-rebind",
+            ]
+            | [
+                "--run-id",
+                run,
+                "--expect-selection",
+                expected,
+                "--accept-legacy-device-rebind",
+                "--json",
+            ] => (run, expected),
+            _ => return Err(invalid()),
+        };
+        #[cfg(target_os = "macos")]
+        {
+            return graph::recover_source_device_rebind(candidate, run, expected);
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = (run, expected);
+            return Err(invalid());
+        }
+    }
     if ["run-selection", "run-service"].contains(action) {
         return one_off::command(candidate, action, args);
     }