fix(native): preserve live source recovery boundaries

Author: hack-cli-tests

docs/reference/native-authored-commands.md

@@ -33,7 +33,7 @@ routing, endpoints and host effects remain outside this bounded frontend. Unsupp
 refuse before managed value resolution and provider work. Early typed input
 capability refusals retain `E_NATIVE_PROJECT_UNSUPPORTED` without exposing
 compiler diagnostics or creating native source/start/run authority. `--detach`,
-`--json`, service subsets, recovery and other lifecycle operations refuse before input
+`--json`, service subsets and other lifecycle operations refuse before input
 acquisition. `--branch` supplies an explicit native namespace; its omission uses
 the canonical project namespace without inferring a Git branch. Profile and env
 selection keep their compiler contracts. `--env base` bypasses inherited overlays
@@ -47,11 +47,41 @@ Ctrl-C requests that shutdown. Exact durable Removed evidence retires the tagged
 native run and startup intent. Unknown, changed or live cleanup retains the attempt
 and refuses replay; a missing ready mapping does not authorize a fresh start.
 
+`down --recover` explicitly retires a complete stored native generation whose
+foreground publisher and frontend admission owner are both dead on the same host
+boot. It requires the current version 3 native publication, the exact stored Ready,
+startup intent and private source envelope, and the original guest incarnation.
+Live owners, older version 2 dead publications, partial startup, pending writes,
+changed files and rebooted guests refuse. Env/profile changes, service subsets and
+`--json` are unsupported for this operation. It neither recompiles authored input
+nor acquires managed values or starts a provider.
+Omit `--profile` to recover the stored generation; explicit empty or named profile
+overrides both refuse.
+
+Recovery commits a distinct private intent before calling the Rust cleanup owner.
+The original raw selectors and resource inventory remain fixed through retries;
+current cleanup phases may advance. Before retiring each frontend file, the owner
+inspects the exact native receipt and requires all resources Removed with null
+observations. A committed retirement phase alone permits the corresponding file's
+expected absence. Pending writes and replacements remain retained refusals. The
+recovery lease blocks ordinary startup throughout this work. Completed frontend
+history is archived under fresh startup admission before a later generation can
+start; incomplete history never permits automatic takeover. Persistent data stays
+retained, and no recovery operation reboots the guest or allocates new resources.
+
+Dead recovery lease takeover retains its private directory and commits the exact
+next owner file before replacing the old owner. A recorded candidate may be pending
+or already published after interruption; both forms must match the saved inode and
+bytes before a fresh lease is issued. Separate committed release flags authorize
+only the corresponding owner/directory absence. An unrecorded pending candidate
+and an interrupted completed-history hardlink archive remain retained refusals;
+this operation does not repair arbitrary partial lock or file publications.
+
 The native receipt and source paths are distinct from strict Compose v1 artifacts.
 Image-only graph receipts remain v2; source-bearing graph receipts use a closed v3
 binding, distinct from the existing foreground publication-owner v3. Ready/control
 envelopes remain v2. Dead-owner recovery of source-bearing receipts is not admitted
 by the separately qualified image-only recovery path. No native hash substitutes
 for a normalized Compose hash. Source and fake-driver
 checks do not qualify an installed frontend, a live provider, the full authored
-corpus, interrupted recovery or resource overhead; those remain separate gates.
+corpus, actual version 3 dead-owner recovery or resource overhead; those remain separate gates.

docs/reference/native-compose-adoption.md

@@ -117,8 +117,44 @@ the engine atomically. Public output remains field/count/status metadata;
 capabilities and authored probe arguments are private. Prior versions 1–4 keep
 their existing execution behavior, and older upgraded owners refuse version 5
 before engine/key reads. Unmodified older launchers still require the previously
-documented upgrade boundary. Completed-job dependencies and container recreation
-remain unsupported required follow-up work.
+documented upgrade boundary. Version 5 does not authorize completed jobs;
+container recreation remains unsupported.
+
+The distinct version 7 receipt and manifest support explicitly mapped completion
+jobs in a static authored pair with the original default bridge and binding version
+1. Names, full container IDs, source/configuration hashes and volume witnesses stay
+unchanged. Generated/managed inputs, typed locals, profiles, custom networks, routes
+and host hooks remain refused for this family before resource effects or value
+acquisition. Jobs require no health check and a disabled observed restart policy
+(`no` or the daemon's empty spelling), with zero retries; authored restart omission
+stays omitted. Version 6 is reserved for its
+separate static-network work and grants no job authority.
+
+Start and restart capture each job's prior daemon `StartedAt` immediately before
+an admitted exact-ID start. The successful child and a fresh nonzero UTC timestamp
+at nanosecond precision, followed by exited status and exit zero, are required
+before starting dependents. Fast jobs need not be observed running. Old exit zero,
+equivalent timestamp spellings, unknown facts or a fresh nonzero exit cannot satisfy
+completion. The real ordered adapter alone can issue a private one-use completion
+bound to this invocation's candidate, resource binding, source capability and
+deadline. Injected schedulers, numeric zero, cloned or replayed completions cannot
+clear the pending journal. Final publication reacquires all exact workload facts
+and rechecks source, receipt, original ownership and the same deadline.
+
+Stop and `down --recover` stop only the original IDs in reverse dependency order;
+they never replay jobs. A failed start, cancellation, changed inputs or uncertain
+postcondition preserves pending. Restart is an explicit new forward attempt on the
+same IDs. Stopped rollback retains data and restores the held legacy pair. These
+cooperative daemon observations do not prove hostile-engine resistance, clock
+authentication or exactly-once business effects. The finite offline job model and
+synthetic owner tests are separate from the required maintained two-worktree SQL,
+interruption and cleanup acceptance.
+
+An ordered observer or scheduler refusal can add a fixed
+`legacy_adoption_refusal: {stage, reason}` to the JSON error detail. The category
+identifies the rejecting boundary without exposing daemon output, resource IDs,
+SQL or environment values. It does not assert which effect occurred; other
+ownership failures keep the existing fixed generic error.
 
 The maintained `native-compose-adoption-dependency-worktrees` selector exercises
 an explicit exec-healthy edge and a short started edge whose target has no health

docs/reference/native-compose-ownership.md

@@ -78,6 +78,15 @@ the in-flight probe's owned subprocess group once, including descendants retaini
 its pipes. A completed child with closed streams is never signalled by cleanup;
 its former process-group ID is no longer an owned target.
 
+The probe owner also issues private, closed failure metadata for admission or
+spawn, nonzero child exit, timeout, cancellation, I/O budget, capture and UTF-8
+decoding. Only the exact issued error carries this observation; copied errors,
+prototypes and arbitrary error properties cannot supply it. Defined probe error
+codes, budgets and cleanup obligations remain unchanged; internal capture and
+UTF-8 errors now normalize to the fixed `E_NATIVE_COMPOSE_PROBE` refusal. Ordered retained-job
+commands translate this metadata and their separate JSON/object boundaries into
+fixed redacted reasons; no argv, daemon output, IDs or exit values are retained.
+
 The closest regression suite is `tests/native-compose-ownership.test.ts`. Its
 isolated executable checks accepted resources, collisions, stale generations,
 inventory changes, redaction, and actual subprocess overflow/timeout/cancellation.

docs/reference/native-config-import.md

@@ -88,16 +88,15 @@ one-shot labels, job health checks and non-`no` job restart policies refuse. Omi
 job restart stays omitted; no native default is invented. Supported profile fields
 remain authored selection, and unsupported fields in inactive jobs still refuse.
 
-This is pure conversion, not retained-job adoption. Existing retained adoption
-owners still refuse job candidates: their receipt versions do not qualify job
-ordering, completion, recovery or replay. A job import preview does not upgrade a
+This is pure conversion, not retained-job adoption. Versions 1–5 do not qualify job
+ordering, completion, recovery or replay. The distinct [version-7 retained owner](native-compose-adoption.md)
+qualifies only its closed static/default-network family. A job import preview does not upgrade a
 receipt, launch or recreate a container, transfer ownership, or qualify application
-migration. Job-aware retained lifecycle and two-worktree data acceptance remain
-separate work.
+migration. Two-worktree data acceptance remains a separate live gate.
 
-Retained resource planning uses its own closed adoption baseline and refuses jobs
-before acquiring existing engine resource bindings, even when pure conversion
-can preserve a job's named mounts. Symbolic conversion is not an ownership grant.
+The service-only adoption baseline continues to refuse jobs. Only the version-7
+owner selects its distinct completed-job baseline after verifying the closed
+static family. Symbolic conversion is not an ownership grant.
 
 Pure preview can preserve a completed job's explicit attachment and aliases on
 these owned bridges. Retained storage/adoption still refuses custom-network
@@ -111,7 +110,7 @@ that fit the compiler's positive u32 milliseconds. Missing or zero timings,
 and the native contract cannot express all of those options. Explicit `disable:
 false` is the default enabled setting. Optional edges and restart propagation
 refuse. Completed-job conversion is supported as described above; retained-job
-execution remains a separate slice. Unknown HTTP/TCP fields also refuse.
+execution has its own version and family boundary. Unknown HTTP/TCP fields also refuse.
 The compiler rejects missing, cyclic or inactive dependency targets and ready
 edges whose target has no explicit readiness. Refusals include inactive profiles.
 

packages/runtime-core/README.md

@@ -174,6 +174,50 @@ it. Native runtime receipts are v2 for image-only graphs and v3 for source-beari
 graphs; the authenticated control/ready wire remains v2;
 Compose receipt and owner formats remain unchanged. This provenance alone grants
 no dead-owner recovery authority.
+The inactive read-only recovery selector admits only a complete Ready journal and
+a dead version3 publication on the same native host boot. It captures the current
+private owner bytes and inode; its raw SHA is a selector for later independent
+admission, not an external identity anchor from before that capture. After a
+durable intent, the saved inode and digest refuse replacement. Cleanup progress
+retains the original Ready selectors and exact inventory. Pending writes refuse;
+retired paths require the intent's preceding phase and unchanged archived inode.
+`graph native recovery-selection --run-id ID --json` exposes only the closed
+selection: run, original value-free Ready receipt, raw receipt/owner hashes and
+native host boot time. The receipt contains review hashes, workload readiness,
+resource IDs/images/networks and terminal observations; it contains no environment
+keys/values, command argv, source bytes or publication process/path metadata. The
+selector creates no intent and connects no provider. It grants no cleanup or
+frontend recovery authority.
+
+The separate explicit library recovery entrypoint re-admits both raw selectors
+and commits a bounded 64 KiB recovery intent before cleanup. It retains the
+publication gate, original operation lock and cleanup provider lease through
+matching Removed resources, private-environment absence and publication
+retirement. A metadata-only current slot inventory is bound into the intent;
+changed or missing records refuse. Bounded read-only guest slot enumeration
+cross-checks the validated native and Compose host records before cleanup and
+again before publication retirement. Unknown guest slots refuse even when host
+records are empty; no payload contents are read or inferred from missing records.
+Durable phases precede each exclusive archive move; original Ready
+hashes and inventory remain fixed while cleanup phases advance. Completed retry
+checks absence rather than repeating retirement. Pending writes, unexpected
+replacements or missing original and archive paths retain a refusal. Public
+frontend recovery and actual dead-owner acceptance remain separate gates.
+The distinct macOS command `graph native recover-live-owner --run-id ID
+--expect-receipt SHA --expect-owner SHA --json` exposes only this explicit
+cleanup entrypoint. Both hashes select the original read-only recovery envelope;
+source, private stdin, review, action and timeout options refuse. Existing live
+control and direct-cleanup ownership gates remain strict. This command does not
+retire frontend start/ready/source artifacts or enable ordinary `up` takeover.
+
+Guarded native cleanup checks its retained authority before and after every
+engine observation, removal request and admitted stop batch, including failed
+calls. The existing stop batch retains its concurrent HTTP-stop semantics. Cleanup
+checks authority before each journal publication. It also
+checks each private-environment absence and retirement call. A lost guard refuses
+before the next request or journal transition; an already attempted effect remains
+durable evidence for an explicitly admitted retry. This prerequisite introduces
+no dead-publisher cleanup entrypoint.
 Cancellation fences startup before admission and subsequent effects. Cleanup
 retains stop failures by admitted workload name, and retires the publication only
 after exact cleanup succeeds. Replies bind their requested action and immutable

packages/runtime-core/src/graph_cli/native.rs

@@ -9,7 +9,7 @@ use std::{
 fn refused() -> CandidateError {
     CandidateError::new(
         "native_graph_arguments",
-        "Use graph native plan --source-file FILE, run|serve --source-file FILE --expect-review SHA [--environment-stdin] [--timeout-seconds 1..300], inspect|cleanup --run-id ID, or control --run-id ID --action status|cleanup; optional --json. Foreground serve/control require macOS. Native source and private envelopes require their exact kind/version; values omitted.",
+        "Use graph native plan --source-file FILE, run|serve --source-file FILE --expect-review SHA [--environment-stdin] [--timeout-seconds 1..300], inspect|cleanup|recovery-selection --run-id ID, recover-live-owner --run-id ID --expect-receipt SHA --expect-owner SHA, or control --run-id ID --action status|cleanup; optional --json. Foreground ownership and its recovery require macOS. Native source and private envelopes require their exact kind/version; values omitted.",
     )
 }
 fn hex(value: &str, len: usize) -> bool {
@@ -35,7 +35,7 @@ pub(super) fn command(candidate: &Candidate, args: &[&str]) -> Result<Value, Can
                 index += 1;
             }
             key @ ("--source-file" | "--expect-review" | "--timeout-seconds" | "--run-id"
-            | "--action") => {
+            | "--action" | "--expect-receipt" | "--expect-owner") => {
                 let value = *args
                     .get(index + 1)
                     .filter(|value| !value.starts_with("--"))
@@ -48,6 +48,59 @@ pub(super) fn command(candidate: &Candidate, args: &[&str]) -> Result<Value, Can
             _ => return Err(refused()),
         }
     }
+    if *action == "recover-live-owner" {
+        if private || singles.len() != 3 {
+            return Err(refused());
+        }
+        let run = *singles
+            .get("--run-id")
+            .filter(|run| hex(run, 32))
+            .ok_or_else(refused)?;
+        let receipt = *singles
+            .get("--expect-receipt")
+            .filter(|receipt| hex(receipt, 64))
+            .ok_or_else(refused)?;
+        let owner = *singles
+            .get("--expect-owner")
+            .filter(|owner| hex(owner, 64))
+            .ok_or_else(refused)?;
+        #[cfg(target_os = "macos")]
+        {
+            return serde_json::to_value(native::foreground::recovery::recover(
+                candidate,
+                native::foreground::recovery::Options {
+                    run,
+                    expect_receipt: receipt,
+                    expect_owner: owner,
+                },
+            )?)
+            .map_err(|_| refused());
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = (run, receipt, owner);
+            return Err(foreground_unavailable());
+        }
+    }
+    if *action == "recovery-selection" {
+        if private || singles.len() != 1 {
+            return Err(refused());
+        }
+        let run = *singles
+            .get("--run-id")
+            .filter(|run| hex(run, 32))
+            .ok_or_else(refused)?;
+        #[cfg(target_os = "macos")]
+        {
+            return serde_json::to_value(native::foreground::recovery::select(candidate, run)?)
+                .map_err(|_| refused());
+        }
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = run;
+            return Err(foreground_unavailable());
+        }
+    }
     if *action == "control" {
         if private || singles.len() != 2 {
             return Err(refused());
@@ -99,6 +152,8 @@ pub(super) fn command(candidate: &Candidate, args: &[&str]) -> Result<Value, Can
     if !["plan", "run", "serve"].contains(action)
         || singles.contains_key("--run-id")
         || singles.contains_key("--action")
+        || singles.contains_key("--expect-receipt")
+        || singles.contains_key("--expect-owner")
     {
         return Err(refused());
     }

packages/runtime-core/src/provider/environment_recovery.rs

@@ -259,6 +259,28 @@ pub fn recorded_slots(candidate: &Candidate) -> Result<Vec<String>, CandidateErr
     }
     Ok(slots.into_iter().collect())
 }
+/// Read-only current-guest metadata for native recovery completeness. Pending
+/// records refuse rather than being promoted or used as missing-slot authority.
+#[cfg(all(target_os = "macos", feature = "native-config-plan"))]
+pub(super) fn known_current_slots(
+    candidate: &Candidate,
+    incarnation: &str,
+    boot: &str,
+) -> Result<std::collections::BTreeSet<String>, CandidateError> {
+    let mut known = std::collections::BTreeSet::new();
+    for slot in recorded_slots(candidate)? {
+        let path = root(candidate).join(format!("{slot}.pending"));
+        match fs::symlink_metadata(path) {
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
+            _ => return Err(error()),
+        }
+        let intent = read_mode(candidate, &slot, incarnation, None, false)?;
+        if intent.boot == boot {
+            known.insert(slot);
+        }
+    }
+    Ok(known)
+}
 /// Validates immutable records before associating them with graph cleanup.
 pub(super) fn graph_slots(
     candidate: &Candidate,

packages/runtime-core/src/provider/graph/foreground/transport.rs

@@ -191,7 +191,7 @@ fn metadata(path: &Path) -> Result<Option<fs::Metadata>, CandidateError> {
 
 /// A dead PID alone cannot prove that another process did not inherit the
 /// listener. A single nonblocking connect must report a refused socket.
-fn no_listener(path: &Path) -> Result<(), CandidateError> {
+pub(in crate::provider::graph) fn no_listener(path: &Path) -> Result<(), CandidateError> {
     let bytes = path.as_os_str().as_encoded_bytes();
     // SAFETY: sockaddr_un is plain C storage, populated before connect.
     let mut address: libc::sockaddr_un = unsafe { std::mem::zeroed() };

packages/runtime-core/src/provider/graph/native/foreground.rs

@@ -4,6 +4,7 @@ use crate::provider::graph::foreground::{signals, transport};
 use serde::{Deserialize, Serialize};
 use std::{cell::Cell, io::Write};
 mod owner;
+pub mod recovery;
 pub(super) use owner::DirectGuard;
 #[cfg(test)]
 mod tests;