@opengsd/gsd-path 1.6.2 → 1.7.0

package/scripts/lean_verification.py

@@ -231,8 +231,14 @@ def _retire_execution(repo, head, execution):
     isolation.retire(repo, worktree, execution["branch"], force=False)
 
 
-def verify_project(repo, expected_head):
-    """Execute project Verify in isolation, retaining output for retry reuse."""
+def verify_project(repo, expected_head, *, rerun: bool = False):
+    """Execute project Verify in isolation, retaining output for retry reuse.
+
+    With ``rerun`` (the owner's explicit ``prepare-final --rerun`` after a
+    host-caused failure diagnosed through the forensics contract), a recorded
+    execution at the same command and commit is retired and the command runs
+    again, appending a second ledger entry; the failed entry stays as history.
+    """
     repo = Path(repo).resolve()
     _require_ship_inputs(repo, expected_head)
     plan = contracts._read(repo, ".project/plan/PLAN.md")
@@ -247,7 +253,6 @@ def verify_project(repo, expected_head):
     destination = repo / relative
     if destination.is_symlink():
         raise contracts.HandoffError("project verification evidence must be a real file")
-    expected_destination = hashlib.sha256(destination.read_bytes()).hexdigest() if destination.exists() else None
     execution = entry.get("execution") if entry else None
     if entry and execution is None:
         raise contracts.HandoffError("recorded verification lacks output; preserve and reconcile its evidence")
@@ -263,11 +268,16 @@ def verify_project(repo, expected_head):
                     relative, relative, journal["expected_destination"],
                 )
         _retire_execution(repo, expected_head, execution)
-        view = _gap_view(command, expected_head, execution, waves)
-        if not destination.exists() or destination.read_text(encoding="utf-8") != view:
-            _common.atomic_write(destination, view)
-        return {"passed": entry["result"] == "pass", "reused": True,
-                "path": str(destination), "execution": execution}
+        if not rerun:
+            view = _gap_view(command, expected_head, execution, waves)
+            if not destination.exists() or destination.read_text(encoding="utf-8") != view:
+                _common.atomic_write(destination, view)
+            return {"passed": entry["result"] == "pass", "reused": True,
+                    "path": str(destination), "execution": execution}
+    # Hash after any prior execution's recovery: a rerun's old-collection
+    # recovery can rewrite the gap view, and the fresh collection must expect
+    # the file as it stands now, not before the recovery (#454).
+    expected_destination = hashlib.sha256(destination.read_bytes()).hexdigest() if destination.exists() else None
     sidecar = isolation.isolate_verify(repo, expected_head, "project-verify")
     worktree = Path(sidecar["worktree"])
     try:
@@ -295,18 +305,20 @@ def verify_project(repo, expected_head):
         execution["members"] = {name: record["tip"] for name, record in sidecars.items()}
     else:
         build_state.verify_record(str(repo), command, expected_head,
-                                  "pass" if passed else "fail", execution=execution)
+                                  "pass" if passed else "fail", execution=execution,
+                                  rerun=rerun)
     isolation.clean_verify(repo, worktree, expected_head, sidecar["branch"])
     _common.atomic_write(worktree / relative, _gap_view(command, expected_head, execution, waves))
     collection = isolation.collect_artifact(repo, worktree, expected_head, sidecar["branch"],
                                             relative, relative, expected_destination)
     isolation.retire(repo, worktree, sidecar["branch"], force=False)
     return {"passed": passed, "reused": False, "path": str(destination),
-            "execution": execution, "collection": collection}
+            "execution": execution, "collection": collection,
+            **({"rerun": True} if rerun else {})}
 
 
-def prepare_final(repo, expected_head):
-    verification = verify_project(repo, expected_head)
+def prepare_final(repo, expected_head, *, rerun: bool = False):
+    verification = verify_project(repo, expected_head, rerun=rerun)
     if not verification["passed"]:
         return {"status": "blocked", "verification": verification,
                 "reason": "project Verify failed; use its recorded output"}
@@ -327,9 +339,12 @@ def main(argv=None):
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--repo", type=Path, required=True)
     parser.add_argument("--expected-head", required=True)
+    parser.add_argument("--rerun", action="store_true",
+                        help="re-execute project Verify at the same head after a host-caused "
+                             "failure, appending a new ledger entry")
     args = parser.parse_args(argv)
     try:
-        result = prepare_final(args.repo.resolve(), args.expected_head)
+        result = prepare_final(args.repo.resolve(), args.expected_head, rerun=args.rerun)
     except (contracts.HandoffError, isolation.IsolationError, build_state.BuildStateError,
             OSError, subprocess.CalledProcessError) as error:
         print(str(error), file=sys.stderr)

package/scripts/loop_run.py

@@ -530,10 +530,15 @@ def run_shell(command: str, timeout: float) -> tuple[Optional[int], str]:
         except subprocess.TimeoutExpired as drained:
             stdout = drained.stdout or expired.stdout or b""
             stderr = drained.stderr or expired.stderr or b""
-            if process.stdout:
-                process.stdout.close()
-            if process.stderr:
-                process.stderr.close()
+            # Windows communicate() reads in threads that hold each pipe's lock,
+            # so close() would block until an orphaned grandchild (bash forks
+            # commands it runs from a script file) exits; leave them to the
+            # daemon reader threads there.
+            if os.name != "nt":
+                if process.stdout:
+                    process.stdout.close()
+                if process.stderr:
+                    process.stderr.close()
             process.kill()
             process.wait(timeout=5)
         output = stdout.decode("utf-8", errors="replace") + stderr.decode("utf-8", errors="replace")

package/scripts/members.py

@@ -34,9 +34,17 @@ MEMBERS_FILE = "MEMBERS.md"
 MARKER_SCHEMA = "gsd-path/member/v1"
 MARKER_KEYS = {"schema", "coordinator", "project", "name"}
 NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
-FIELDS = ("Checkout", "Remote", "Integration")
+FIELDS = ("Checkout", "Remote", "Integration", "Prepare")
+# The first three are required; Prepare (isolate provisioning, #463) and
+# Default branch are optional.
+REQUIRED_FIELDS = ("Checkout", "Remote", "Integration")
 # Optional: `add` records it one time; a row without it means main.
 DEFAULT_BRANCH_FIELD = "Default branch"
+# Optional: a shell command run inside each fresh member isolate before any
+# Verify (#463). It provisions what a bare worktree lacks — submodules from
+# the primary checkout's object store, gitignored build inputs — and must
+# copy, never link, outside the isolate (#462).
+PREPARE_FIELD = "Prepare"
 INTEGRATIONS = ("default", "direct", "pull-request")
 GITHUB_REMOTE_RE = re.compile(
     r"(?:https://github\.com/|git@github\.com:|ssh://git@github\.com/)([^/\s]+)/([^/\s]+)"
@@ -206,10 +214,15 @@ def read_members(coordinator: Path) -> list[dict[str, str]]:
         return []
     if path.is_symlink() or not path.is_file():
         raise MembersError("MEMBERS.md must be a regular file")
+    return parse_members(path.read_text(encoding="utf-8"))
+
+
+def parse_members(text: str) -> list[dict[str, str]]:
+    """Parse MEMBERS.md text."""
     members: list[dict[str, str]] = []
     current: Optional[dict[str, str]] = None
     preamble: list[str] = []
-    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+    for number, line in enumerate(text.splitlines(), 1):
         if line.startswith("## "):
             name = line[3:].strip()
             if not NAME_RE.fullmatch(name):
@@ -241,7 +254,7 @@ def read_members(coordinator: Path) -> list[dict[str, str]]:
     if len(set(names)) != len(names):
         raise MembersError("MEMBERS.md repeats a member name")
     for member in members:
-        missing = [field for field in FIELDS if not member.get(field.lower())]
+        missing = [field for field in REQUIRED_FIELDS if not member.get(field.lower())]
         if missing:
             raise MembersError(f"MEMBERS.md member {member['name']} lacks {', '.join(missing)}")
         if member["integration"] not in INTEGRATIONS:
@@ -510,6 +523,7 @@ def render(members: Sequence[dict[str, str]]) -> str:
         f"Checkout: {member['checkout']}\n"
         f"Remote: {member['remote']}\n"
         f"Integration: {member['integration']}\n"
+        + (f"{PREPARE_FIELD}: {member['prepare']}\n" if "prepare" in member else "")
         # A row that never had the field keeps none, so old rows are not rewritten.
         + (f"{DEFAULT_BRANCH_FIELD}: {member['default_branch']}\n" if "default_branch" in member else "")
         for member in members

package/scripts/pipeline_diagnose.py

@@ -24,16 +24,20 @@ from typing import Callable, Optional, Sequence
 def _load_diagnose_modules():
     if __package__:
         from . import archive_milestone
+        from . import build_state
         from . import detect_project
         from . import discussion_records
+        from . import discussion_validate
         from . import integration
         from . import isolation
         from . import pipeline_git
         from . import pipeline_state
         return (
             archive_milestone,
+            build_state,
             detect_project,
             discussion_records,
+            discussion_validate,
             integration,
             isolation,
             pipeline_git,
@@ -42,16 +46,20 @@ def _load_diagnose_modules():
     else:
         try:
             import archive_milestone
+            import build_state
             import detect_project
             import discussion_records
+            import discussion_validate
             import integration
             import isolation
             import pipeline_git
             import pipeline_state
             return (
                 archive_milestone,
+                build_state,
                 detect_project,
                 discussion_records,
+                discussion_validate,
                 integration,
                 isolation,
                 pipeline_git,
@@ -60,8 +68,10 @@ def _load_diagnose_modules():
         except ModuleNotFoundError as error:
             if error.name not in {
                 "archive_milestone",
+                "build_state",
                 "detect_project",
                 "discussion_records",
+                "discussion_validate",
                 "integration",
                 "isolation",
                 "pipeline_git",
@@ -71,8 +81,10 @@ def _load_diagnose_modules():
     try:
         from scripts import (
             archive_milestone,
+            build_state,
             detect_project,
             discussion_records,
+            discussion_validate,
             integration,
             isolation,
             pipeline_git,
@@ -80,8 +92,10 @@ def _load_diagnose_modules():
         )
         return (
             archive_milestone,
+            build_state,
             detect_project,
             discussion_records,
+            discussion_validate,
             integration,
             isolation,
             pipeline_git,
@@ -91,8 +105,10 @@ def _load_diagnose_modules():
         if error.name not in {
             "scripts",
             "scripts.archive_milestone",
+            "scripts.build_state",
             "scripts.detect_project",
             "scripts.discussion_records",
+            "scripts.discussion_validate",
             "scripts.integration",
             "scripts.isolation",
             "scripts.pipeline_git",
@@ -109,16 +125,20 @@ def _load_diagnose_modules():
         shared = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
         sys.path.insert(0, str(shared))
         import archive_milestone
+        import build_state
         import detect_project
         import discussion_records
+        import discussion_validate
         import integration
         import isolation
         import pipeline_git
         import pipeline_state
         return (
             archive_milestone,
+            build_state,
             detect_project,
             discussion_records,
+            discussion_validate,
             integration,
             isolation,
             pipeline_git,
@@ -128,8 +148,10 @@ def _load_diagnose_modules():
 
 (
     archive_milestone,
+    build_state,
     detect_project,
     discussion_records,
+    discussion_validate,
     integration,
     isolation,
     pipeline_git,
@@ -137,6 +159,9 @@ def _load_diagnose_modules():
 ) = _load_diagnose_modules()
 DetectError = detect_project.DetectError
 classify = detect_project.classify
+BuildStateError = build_state.BuildStateError
+build_ready = build_state.ready
+review_cycle_counts = discussion_validate.review_cycle_counts
 IsolationError = isolation.IsolationError
 _registered_worktrees = isolation._registered_worktrees
 _worktree_report = isolation._worktree_report
@@ -231,7 +256,15 @@ def _state_template() -> Path:
 
 
 def _command(module: object, *arguments: object) -> str:
-    script = Path(str(getattr(module, "__file__"))).resolve()
+    return _script_command(Path(str(getattr(module, "__file__"))), *arguments)
+
+
+def _dispatch_command(*arguments: object) -> str:
+    return _script_command(Path(str(build_state.__file__)).with_name("dispatch_driver.py"), *arguments)
+
+
+def _script_command(path: Path, *arguments: object) -> str:
+    script = path.resolve()
     def text(value: object) -> str:
         # Agents paste this into Git Bash on Windows, where unquoted
         # backslashes are escapes; forward slashes need no quoting.
@@ -354,6 +387,74 @@ def _leftover_worktrees(repo: Path) -> list[dict[str, object]]:
     return leftovers
 
 
+def _build_completion_findings(repo: Path) -> list[dict[str, str]]:
+    """Mirror dispatch complete's build gates so a completion refusal is diagnosable.
+
+    Runs the same checks `dispatch_driver.py complete` runs, under the same
+    precondition (every wave's tasks done, no blocked review holding them), and
+    names the review set or typed build state that complete would refuse on.
+    """
+    try:
+        ready_result = build_ready(str(repo), allow_done=True)
+    except BuildStateError as error:
+        return [
+            _finding(
+                "review-cycles",
+                "stuck",
+                f"{error.code}: {error}",
+                _dispatch_command("complete", "--repo", repo)
+                + "  # reports the same typed blocker; follow its recovery (reconcile "
+                "failed or blocked tasks, resolve a dependency deadlock before new dispatch)",
+            )
+        ]
+    blocked = ready_result.get("blocked_review")
+    if blocked:
+        wave, cycle = blocked["wave"], blocked["cycle"]
+        waiting = ", ".join(
+            str(item) for item in blocked.get("waiting_waves") or []
+        )
+        if any((repo / ".project" / "tasks").glob(f"*-fix-wave-{wave}-cycle-{cycle}.md")):
+            retry = (
+                _dispatch_command("review", "--repo", repo, "--wave", wave, "--cycle", cycle + 1)
+                + "  # add the owner's --child-command; the source wave's next review cycle "
+                "in full at the current HEAD; "
+                "pass --repair-evidence when review_findings.py repair-evidence accepts a landed repair"
+            )
+        else:
+            retry = (
+                _dispatch_command("fix-tasks", "--repo", repo, "--wave", wave, "--cycle", cycle)
+                + "  # then land the repair wave; the source wave's next review cycle judges it"
+            )
+        return [
+            _finding(
+                "review-cycles",
+                "stuck",
+                f"wave {wave} review cycle {cycle} is blocked "
+                + (f"and holds waiting waves {waiting}" if waiting else "and holds completion"),
+                retry,
+            )
+        ]
+    if ready_result.get("current_wave") is not None:
+        return []
+    try:
+        review_cycle_counts(repo / ".project")
+    except archive_milestone.ArchiveError as error:
+        return [
+            _finding(
+                "review-cycles",
+                "stuck",
+                str(error),
+                "compare each PLAN.md wave with the .project/review/wave-N.cycleC.md "
+                "files, then run the missing cycle's review: "
+                + _dispatch_command("review", "--repo", repo)
+                + " with that wave's --wave and --cycle and the owner's --child-command; "
+                "a repair wave is judged by "
+                "its source wave's next cycle",
+            )
+        ]
+    return []
+
+
 def diagnose(repo: Path) -> dict[str, object]:
     resolved = repo.resolve()
     if not resolved.is_dir():
@@ -567,6 +668,8 @@ def diagnose(repo: Path) -> dict[str, object]:
                                 "$gsd-path-ship",
                             )
                         )
+        elif state.get("phase") == "build" and state.get("status") in {"active", "done"}:
+            findings.extend(_build_completion_findings(resolved))
 
     undo_transaction = by_name["undo-transaction"]
     route_action = (

package/scripts/pipeline_state.py

@@ -1407,6 +1407,12 @@ def _route_state(repo: Path, project_dir: str = ".project") -> dict[str, object]
             mode="milestone" if status == "done" else "normal",
             reason=f"state is {phase}/{status}",
         )
+    if phase == "plan" and status == "blocked":
+        return _route_result(
+            state,
+            "block",
+            reason="plan is blocked; resolve the correction or user decision named by the plan gate before resuming",
+        )
     if phase == "plan" and status != "done":
         return _route_result(state, "run-phase", phase="plan", reason=f"state is {phase}/{status}")
     if phase == "plan":
@@ -2373,9 +2379,9 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 args.project_dir,
             )
         elif args.command == "approve" and (args.defer_checkpoint or args.patch):
-            if args.expected_head is not None:
+            if args.defer_checkpoint and args.expected_head is not None:
                 raise PipelineStateError(
-                    "--expected-head is not accepted with --defer-checkpoint or --patch"
+                    "--expected-head is not accepted with --defer-checkpoint"
                 )
             result = state_checkpoint.defer_approval(
                 args.repo,
@@ -2384,6 +2390,8 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 args.milestone,
                 args.patch,
             )
+            if args.expected_head is not None:
+                result["expected_head_accepted"] = args.expected_head
         elif args.command == "approve":
             if args.expected_head is None:
                 raise PipelineStateError(

package/scripts/runtime_store.py

@@ -7,6 +7,7 @@ import os
 from pathlib import Path
 import shutil
 import shlex
+import sys
 import tempfile
 import time
 from contextlib import contextmanager
@@ -74,7 +75,7 @@ def guard_launcher(name):
             f"    raise SystemExit({2 if name == 'guard_hook.py' else 1})\n")
 
 
-def source_manifest(source):
+def source_manifest(source, successors=()):
     version = json.loads((source / "package.json").read_text(encoding="utf-8"))["version"]
     files = {}
     for name in (*RUNTIME_FILES, *GUARDS, "status_runtime.py"):
@@ -83,6 +84,13 @@ def source_manifest(source):
             raise ValueError(f"symlinked runtime source: {path}")
         files[name] = hashlib.sha256(path.read_bytes()).hexdigest()
     manifest = {"version": version, "files": files}
+    if successors:
+        # #468 option (i): the successors list joins the manifest BEFORE the
+        # digest is taken, so the published runtime's own bytes bless exactly
+        # these successor digests. An unnamed publish keeps the stock
+        # manifest — identical sources still digest identically.
+        manifest["successors"] = list(successors)
+        status_runtime.manifest_successors(manifest)
     pin = {"schema": status_runtime.RUNTIME_SCHEMA, "version": version,
            "digest": status_runtime.manifest_digest(manifest)}
     return manifest, pin
@@ -114,9 +122,33 @@ def publication_lock(parent, digest):
         os.close(descriptor)
 
 
-def publish(source, *, expected=None, dry_run=False, repair=False):
-    manifest, pin = source_manifest(source)
+def _blessed_store_entry(expected, source_manifest_dict) -> bool:
+    """True when the expected runtime is in the store, hash-valid, stamped with
+    successors, and built from the SAME version and files as the supplied
+    source — only the stamp may differ (#468). A wrong package never restores,
+    even for a blessed pin."""
+    try:
+        root = status_runtime.validate_runtime(expected)
+        manifest = json.loads((root / "manifest.json").read_text(encoding="utf-8"))
+        return bool(
+            status_runtime.manifest_successors(manifest)
+            and manifest.get("version") == source_manifest_dict.get("version")
+            and manifest.get("files") == source_manifest_dict.get("files")
+        )
+    except (OSError, ValueError, TypeError):
+        return False
+
+
+def publish(source, *, expected=None, dry_run=False, repair=False, successors=()):
+    manifest, pin = source_manifest(source, successors)
     if expected is not None and any(pin[key] != expected.get(key) for key in pin):
+        # A blessed pin's digest covers its successors stamp, so an unstamped
+        # source cannot reproduce it. When the blessed entry itself is in the
+        # store, hash-valid, stamped, and built from the same version and
+        # files as this source, restore returns those exact bytes; every
+        # other mismatch stays the caller's error.
+        if _blessed_store_entry(expected, manifest):
+            return expected
         raise ValueError(f"source does not match declared runtime {expected['version']} ({expected['digest']}); use its matching package")
     if dry_run:
         return pin
@@ -336,3 +368,56 @@ def operate(source, project, action, *, dry_run=False, provenance=None):
         raise
     journal.unlink()
     return {**pin, "backup": str(backup)} if backup else pin
+
+
+def main(argv=None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Content-addressed runtime store operations. Publication only adds a "
+                    "store entry: it never selects a runtime for, or writes to, any project.")
+    subcommands = parser.add_subparsers(dest="command", required=True)
+    publish_parser = subcommands.add_parser(
+        "publish", help="publish and verify a runtime without touching any project pin")
+    publish_parser.add_argument("--source", required=True,
+                                help="runtime source root (holds package.json and scripts/)")
+    publish_parser.add_argument("--expected-version",
+                                help="with --expected-digest: refuse a source that differs")
+    publish_parser.add_argument("--expected-digest",
+                                help="with --expected-version: refuse a source that differs")
+    publish_parser.add_argument("--provenance", default=None,
+                                help="provenance note echoed in the output; the store never keeps it")
+    publish_parser.add_argument("--dry-run", action="store_true",
+                                help="compute the identity without writing to the store")
+    publish_parser.add_argument("--repair", action="store_true",
+                                help="replace a store entry that fails verification")
+    publish_parser.add_argument("--name-successor", action="append", default=[], metavar="DIGEST",
+                                help="record a successor runtime digest in this runtime's hashed "
+                                     "manifest (#468 option (i)); publish the successor first, then "
+                                     "name its digest here — repeatable for several successors")
+    arguments = parser.parse_args(argv)
+    source = Path(arguments.source).resolve()
+    if (arguments.expected_version is None) != (arguments.expected_digest is None):
+        parser.error("--expected-version and --expected-digest are given together or not at all")
+    expected = None
+    if arguments.expected_version is not None:
+        if not arguments.expected_version or not arguments.expected_digest:
+            parser.error("--expected-version and --expected-digest must be non-empty")
+        expected = {"schema": status_runtime.RUNTIME_SCHEMA,
+                    "version": arguments.expected_version,
+                    "digest": arguments.expected_digest}
+    try:
+        pin = publish(source, expected=expected,
+                      dry_run=arguments.dry_run, repair=arguments.repair,
+                      successors=arguments.name_successor)
+        path = None if arguments.dry_run else str(status_runtime.validate_runtime(pin))
+    except (ValueError, OSError) as error:
+        print(f"publish failed: {error}", file=sys.stderr)
+        return 1
+    result = {**pin, "path": path, "provenance": arguments.provenance}
+    print(json.dumps(result, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/state_checkpoint.py

@@ -458,6 +458,21 @@ def _validate_plan_briefs(repo: Path, kind: str, project_dir: str) -> None:
     if head.returncode != 0:
         # Pre-Git approval defers base-dependent checks to build.
         return
+    if project_dir == ".project":
+        # Unsupported .project entries must surface at approval, before build,
+        # where removing them is cheapest (#466). Like the checkpoint, judge
+        # each git-visible entry by whether it still exists in the worktree.
+        project = repo / ".project"
+        unsupported = sorted(
+            name
+            for name in pipeline_state._common.git_visible_entries(project) - PROJECT_ENTRIES
+            if (project / name).exists() or (project / name).is_symlink()
+        )
+        if unsupported:
+            raise PipelineStateError(
+                "unsupported .project artifacts: " + ", ".join(unsupported)
+                + "; remove or relocate them before approving the plan"
+            )
     if __package__:
         from .check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
     else:

package/scripts/status_runtime.py

@@ -128,7 +128,76 @@ def manifest_digest(manifest: dict) -> str:
     return hashlib.sha256(json.dumps(manifest, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
 
 
+def manifest_successors(manifest: dict) -> tuple:
+    """The validated successor digests a runtime's hashed manifest names (#468).
+
+    `successors` is an optional list of unique 64-hex lowercase store digests.
+    It lives inside the manifest, so the runtime's own digest covers it: a
+    runtime can only bless successors its hashed bytes name. A malformed
+    field makes the whole runtime invalid — acceptance never widens on a
+    shape the store cannot prove.
+    """
+    successors = manifest.get("successors", [])
+    if (not isinstance(successors, list)
+            or not all(
+                isinstance(item, str) and len(item) == 64
+                and all(char in "0123456789abcdef" for char in item)
+                for item in successors
+            )
+            or len(set(successors)) != len(successors)):
+        raise ValueError("invalid manifest successors")
+    return tuple(successors)
+
+
+def accepted_runtime_dirs(repo: Path) -> set:
+    """The pinned runtime's directory plus every validated successor (#468).
+
+    Owner-ruled option (i) on #468: acceptance after ship is anchored in the
+    pinned runtime's own hashed manifest. It names successor digests; each
+    hop is validated exactly like the pin and may name further successors.
+    A named entry that is missing or fails validation simply does not widen
+    the set — the pinned runtime keeps working — and a visited set ends
+    blessed cycles. Nothing outside the pin's hashed reach is ever accepted.
+    """
+    pin = declaration(repo)
+    pin_root, pin_manifest = _validated_manifest(pin)
+    accepted = {pin_root.resolve()}
+    seen = {pin["digest"]}
+    pending = list(manifest_successors(pin_manifest))
+    while pending:
+        digest = pending.pop()
+        if digest in seen:
+            continue
+        seen.add(digest)
+        try:
+            # version None: the hop's trust anchor is the digest the pinned
+            # bytes named, never a version claim. The successors followed
+            # come from the same manifest read whose digest was proven —
+            # a mid-walk entry swap cannot smuggle a different list.
+            root, manifest = _validated_manifest(
+                {"schema": RUNTIME_SCHEMA, "version": None, "digest": digest}
+            )
+            named = manifest_successors(manifest)
+        except (OSError, ValueError, TypeError):
+            continue
+        pending.extend(named)
+        accepted.add(root.resolve())
+    return accepted
+
+
 def validate_runtime(data: dict) -> Path:
+    return _validated_manifest(data)[0]
+
+
+def _validated_manifest(data: dict) -> tuple:
+    """validate_runtime, returning the exact manifest whose digest was proven.
+
+    Callers that act on manifest content (the #468 successor walk) must use
+    this returned object, never a second read of manifest.json: a concurrent
+    swap between reads could otherwise validate one manifest while following
+    successors from another. `version` None anchors on the digest alone —
+    used by the walk for hops whose version no declaration supplies.
+    """
     root = runtime_home() / data["digest"]
     hint = (f"Runtime {data['version']} ({data['digest']}) is unavailable or invalid at {root}. "
             "Run gsd-path --runtime-restore --project <project-root> "
@@ -141,7 +210,8 @@ def validate_runtime(data: dict) -> Path:
             raise ValueError("symlinked manifest")
         manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
         if (not isinstance(manifest, dict) or manifest_digest(manifest) != data["digest"]
-                or manifest.get("version") != data["version"]):
+                or (data["version"] is not None
+                    and manifest.get("version") != data["version"])):
             raise ValueError("manifest identity mismatch")
         files = manifest.get("files")
         if not isinstance(files, dict) or "pipeline_state.py" not in files:
@@ -164,9 +234,10 @@ def validate_runtime(data: dict) -> Path:
             runtime_entries.add(path.name)
         if runtime_entries != set(files) | {"manifest.json"}:
             raise ValueError("unexpected runtime files")
+        manifest_successors(manifest)
     except (OSError, ValueError, TypeError) as error:
         raise ValueError(hint + f" ({error})") from error
-    return root
+    return root, manifest
 
 
 def resolve_runtime(repo: Path) -> Path: