devlyn-cli 2.10.0 → 2.10.1

package/config/skills/_shared/state-phase-write.py

@@ -38,6 +38,7 @@ import tempfile
 
 VALID_VERDICTS = {"PASS", "PASS_WITH_ISSUES", "FAIL", "NEEDS_WORK", "BLOCKED"}
 VALID_TRIGGERS = {"build_gate", "verify"}
+SPAWN_TRIGGERS = VALID_TRIGGERS | {"plan"}
 PHASE_NAMES = {"plan", "probe_derive", "implement", "surface_close", "build_gate", "cleanup", "verify", "final_report"}
 LEGAL_TRANSITIONS = {
     "plan": {"probe_derive", "implement", "final_report"},
@@ -68,6 +69,14 @@ VALIDATION_EXECUTION_RE = re.compile(
 )
 SURFACE_SKIP_REASON = "auto_surface_close_claude_unavailable"
 SURFACE_RECOVERY_REASON = "surface_close_rolled_back_adjudication_malformed"
+PLAN_MAX_DISPATCHES = 2
+PLAN_SPAWN_RECEIPT_FIELDS = (
+    "round", "started_at", "triggered_by", "engine", "model_requested", "prompt_sha256",
+)
+PLAN_COMPLETION_RECEIPT_FIELDS = (
+    "completed_at", "duration_ms", "verdict", "model_effective",
+)
+PLAN_RECEIPT_FIELDS = PLAN_SPAWN_RECEIPT_FIELDS + PLAN_COMPLETION_RECEIPT_FIELDS
 
 
 def reject_json_constant(token: str) -> None:
@@ -242,6 +251,9 @@ def validate_authorized_surface(raw: str) -> list[str]:
 
 
 def path_matches_surface(path: str, surface: list[str]) -> bool:
+    parsed = pathlib.PurePosixPath(path)
+    if parsed.is_absolute() or ".." in parsed.parts:
+        return False
     for entry in surface:
         if entry.endswith("/**"):
             prefix = entry[:-3].rstrip("/")
@@ -252,6 +264,63 @@ def path_matches_surface(path: str, surface: list[str]) -> bool:
     return False
 
 
+def worktree_file_exists(work: pathlib.Path, path: str) -> bool:
+    parsed = pathlib.PurePosixPath(path)
+    if parsed.is_absolute() or ".." in parsed.parts:
+        return False
+    try:
+        resolved = (work / path).resolve()
+        resolved.relative_to(work.resolve())
+        return resolved.is_file()
+    except (OSError, RuntimeError, ValueError):
+        return False
+
+
+def worktree_path_exists(work: pathlib.Path, path: str) -> bool:
+    parsed = pathlib.PurePosixPath(path)
+    if parsed.is_absolute() or ".." in parsed.parts:
+        return False
+    try:
+        resolved = (work / path).resolve()
+        resolved.relative_to(work.resolve())
+        return resolved.exists()
+    except (OSError, RuntimeError, ValueError):
+        return False
+
+
+def resolve_na_surface_citation(
+    work: pathlib.Path, raw: str, parsed_path: str, parsed_line: int | None,
+    surface: list[str],
+) -> tuple[str, int | None]:
+    def proven(path: str) -> bool:
+        if path in surface and not path.endswith("/**"):
+            return True
+        return worktree_file_exists(work, path) and any(
+            entry.endswith("/**") and path_matches_surface(path, [entry])
+            for entry in surface
+        )
+
+    if proven(raw):
+        return raw, None
+    if worktree_path_exists(work, raw) and not path_matches_surface(raw, surface):
+        raise SystemExit(f"BLOCKED:surface-close-adjudication-out-of-surface: {raw}")
+    if (
+        worktree_path_exists(work, parsed_path)
+        and not path_matches_surface(parsed_path, surface)
+    ):
+        raise SystemExit(f"BLOCKED:surface-close-adjudication-out-of-surface: {raw}")
+    for split in range(len(raw) - 1, -1, -1):
+        if raw[split] != ":" or not proven(raw[:split]):
+            continue
+        suffix = raw[split:]
+        if not re.fullmatch(r":[1-9][0-9]*", suffix):
+            raise SystemExit(
+                f"BLOCKED:surface-close-adjudication-malformed: citation {raw!r}"
+            )
+        return raw[:split], int(suffix[1:])
+    return parsed_path, parsed_line
+
+
 def surface_offenders(work: pathlib.Path, devlyn: pathlib.Path, state: dict,
                       surface: list[str]) -> list[str]:
     tracked, untracked = surface_delta_paths(work, devlyn, state)
@@ -342,14 +411,20 @@ def validate_surface_adjudication(
         raw_line = match.group("fired_line") or match.group("na_line")
         line_number = int(raw_line) if raw_line is not None else None
         citation = path if line_number is None else f"{path}:{line_number}"
+        if status == "N/A":
+            path, line_number = resolve_na_surface_citation(
+                work, citation, path, line_number, surface,
+            )
+            citation = path if line_number is None else f"{path}:{line_number}"
         if not path_matches_surface(path, surface):
             raise SystemExit(
                 f"BLOCKED:surface-close-adjudication-out-of-surface: {citation}"
             )
-        cited = work / path
         try:
+            cited = (work / path).resolve()
+            cited.relative_to(work.resolve())
             cited_lines = cited.read_text(encoding="utf-8").splitlines()
-        except (OSError, UnicodeError) as exc:
+        except (OSError, RuntimeError, UnicodeError, ValueError) as exc:
             raise SystemExit(
                 f"BLOCKED:surface-close-adjudication-citation-missing: {citation}: {exc}"
             ) from exc
@@ -488,6 +563,60 @@ def require_surface_adjudication_malformed(
     )
 
 
+CLAUDE_USAGE_COUNTERS = (
+    ("input_tokens", "inputTokens"),
+    ("output_tokens", "outputTokens"),
+    ("cache_read_input_tokens", "cacheReadInputTokens"),
+    ("cache_creation_input_tokens", "cacheCreationInputTokens"),
+)
+
+
+def select_claude_primary_model(evidence: dict) -> str:
+    model_usage = evidence.get("modelUsage")
+    models = (
+        [model for model in model_usage if isinstance(model, str) and model]
+        if isinstance(model_usage, dict)
+        else []
+    )
+    if len(models) == 1:
+        return models[0]
+    if not models:
+        raise ValueError("Claude JSON wrapper has no effective-model evidence")
+
+    usage = evidence.get("usage")
+    if not isinstance(usage, dict):
+        raise ValueError("multi-entry Claude JSON wrapper has malformed top-level usage")
+
+    def counters(container: dict, fields: tuple[str, ...]) -> tuple[int, ...]:
+        values = tuple(container.get(field) for field in fields)
+        if any(
+            not isinstance(value, int)
+            or isinstance(value, bool)
+            or value < 0
+            for value in values
+        ):
+            raise ValueError("multi-entry Claude JSON wrapper has malformed usage counters")
+        return values
+
+    primary_usage = counters(
+        usage, tuple(field[0] for field in CLAUDE_USAGE_COUNTERS)
+    )
+    matches = []
+    for model in models:
+        entry = model_usage[model]
+        if not isinstance(entry, dict):
+            raise ValueError("multi-entry Claude JSON wrapper has malformed modelUsage entry")
+        if counters(
+            entry, tuple(field[1] for field in CLAUDE_USAGE_COUNTERS)
+        ) == primary_usage:
+            matches.append(model)
+    if len(matches) == 1:
+        return matches[0]
+    raise ValueError(
+        "multi-entry Claude JSON wrapper has no unique primary usage match"
+    )
+
+
 def parse_effective_model(session_log: pathlib.Path) -> str:
     try:
         text = session_log.read_text(encoding="utf-8")
@@ -520,9 +649,8 @@ def parse_effective_model(session_log: pathlib.Path) -> str:
             evidence = loads_strict_json(text)
         except ValueError:
             evidence = None
-        model_usage = evidence.get("modelUsage") if isinstance(evidence, dict) else None
-        if isinstance(model_usage, dict):
-            models.update(model for model in model_usage if isinstance(model, str) and model)
+        if isinstance(evidence, dict) and isinstance(evidence.get("modelUsage"), dict):
+            return select_claude_primary_model(evidence)
 
     if len(models) == 1:
         return next(iter(models))
@@ -1134,18 +1262,21 @@ def clear_verify_round_artifacts(devlyn: pathlib.Path) -> None:
     (devlyn / "verify-merge.summary.json").unlink(missing_ok=True)
 
 
-def append_phase_history(entry: dict) -> None:
+def is_plan_dispatch_receipt(entry: dict) -> bool:
+    return all(field in entry for field in PLAN_RECEIPT_FIELDS)
+
+
+def append_phase_history(entry: dict, phase: str) -> None:
     if entry.get("started_at") is None:
         return
     history = entry.get("history")
     if not isinstance(history, list):
         history = []
-    history.append({
-        "started_at": entry.get("started_at"),
-        "verdict": entry.get("verdict"),
-        "completed_at": entry.get("completed_at"),
-        "duration_ms": entry.get("duration_ms"),
-    })
+    fields = (
+        PLAN_RECEIPT_FIELDS if phase == "plan" and is_plan_dispatch_receipt(entry)
+        else ("started_at", "verdict", "completed_at", "duration_ms")
+    )
+    history.append({field: entry.get(field) for field in fields})
     entry["history"] = history
 
 
@@ -1156,12 +1287,33 @@ def do_spawn(state: dict, phase: str, round_: int, triggered_by: str | None,
              untracked_before: list[str] | None = None) -> None:
     # Merge, don't replace: a phase-gated large run's `exec` progress (or any
     # other field this script doesn't own) survives a fix-loop respawn.
+    phases_value = state.get("phases")
+    entry = phases_value.get(phase) if isinstance(phases_value, dict) else None
+    if phase == "plan":
+        history = entry.get("history", []) if isinstance(entry, dict) else []
+        if not isinstance(history, list):
+            raise SystemExit("error: phases.plan.history must be an array")
+        dispatch_count = len(history) + int(
+            isinstance(entry, dict) and entry.get("started_at") is not None
+        )
+        if dispatch_count >= PLAN_MAX_DISPATCHES:
+            raise SystemExit("BLOCKED:plan-respawn-exhausted")
+        if round_ != dispatch_count:
+            raise SystemExit(
+                f"BLOCKED:plan-round-nonmonotonic: expected={dispatch_count} supplied={round_}"
+            )
+        if not isinstance(engine, str) or not engine:
+            raise SystemExit("error: phases.plan spawn requires --engine")
+        if not isinstance(model, str) or not model:
+            raise SystemExit("error: phases.plan spawn requires --model")
+        if prompt_sha256 is None or not SHA256_RE.fullmatch(prompt_sha256):
+            raise SystemExit("error: phases.plan spawn requires --prompt-sha256")
+        if dispatch_count > 0 and triggered_by is None:
+            raise SystemExit("error: phases.plan re-spawn requires --triggered-by")
     if phase == "surface_close" and engine != "claude":
         raise SystemExit("error: phases.surface_close spawn requires --engine claude")
     if phase == "surface_close" and not model:
         raise SystemExit("error: phases.surface_close spawn requires --model")
-    phases = state.setdefault("phases", {})
-    entry = phases.get(phase)
     if phase == "surface_close" and isinstance(entry, dict) and (
         entry.get("started_at") is not None or entry.get("skipped_reason") is not None
     ):
@@ -1175,8 +1327,12 @@ def do_spawn(state: dict, phase: str, round_: int, triggered_by: str | None,
             raise SystemExit("error: phases.surface_close spawn requires --prompt-sha256")
         if untracked_before is None:
             raise SystemExit("error: phases.surface_close spawn requires --untracked-before-json")
+    elif phase == "plan":
+        if input_patch_sha256 is not None or untracked_before is not None:
+            raise SystemExit("error: SURFACE_CLOSE metadata is invalid for this phase")
     elif input_patch_sha256 is not None or prompt_sha256 is not None or untracked_before is not None:
         raise SystemExit("error: SURFACE_CLOSE metadata is invalid for this phase")
+    phases = state.setdefault("phases", {})
     if not isinstance(entry, dict):
         entry = {}
         phases[phase] = entry
@@ -1184,7 +1340,7 @@ def do_spawn(state: dict, phase: str, round_: int, triggered_by: str | None,
         raise SystemExit(
             f"error: phases.{phase} has an open span — complete it before respawn"
         )
-    append_phase_history(entry)
+    append_phase_history(entry, phase)
     entry["started_at"] = now_iso()
     entry["completed_at"] = None
     entry["duration_ms"] = None
@@ -1205,9 +1361,10 @@ def do_spawn(state: dict, phase: str, round_: int, triggered_by: str | None,
     entry["model_effective"] = None
     if pre_sha is not None:
         entry["pre_sha"] = pre_sha
+    if phase in {"plan", "surface_close"}:
+        entry["prompt_sha256"] = prompt_sha256
     if phase == "surface_close":
         entry["input_patch_sha256"] = input_patch_sha256
-        entry["prompt_sha256"] = prompt_sha256
         entry["untracked_before"] = untracked_before
 
 
@@ -1243,6 +1400,16 @@ def do_complete(state: dict, phase: str, verdict: str | None,
     entry = phases.get(phase)
     if not isinstance(entry, dict) or not entry.get("started_at"):
         raise SystemExit(f"error: phases.{phase} was never spawned (no started_at) — cannot complete")
+    if phase == "plan" and entry.get("prompt_sha256") is not None:
+        missing = [field for field in PLAN_SPAWN_RECEIPT_FIELDS if field not in entry]
+        if missing:
+            raise SystemExit(
+                "error: phases.plan spawn receipt is incomplete: " + ",".join(missing)
+            )
+        if engine is not None and engine != entry["engine"]:
+            raise SystemExit("error: phases.plan completion cannot replace spawn engine")
+        if model is not None and model != entry["model_requested"]:
+            raise SystemExit("error: phases.plan completion cannot replace requested model")
     started = parse_iso(entry["started_at"])
     now = now_ms()
     entry["completed_at"] = now_iso(now)
@@ -1268,11 +1435,11 @@ def do_complete(state: dict, phase: str, verdict: str | None,
             artifacts["findings_file"] = findings_file
         if log_file is not None:
             artifacts["log_file"] = log_file
-    if engine is not None:
+    if engine is not None and phase != "plan":
         entry["engine"] = engine
-    if model is not None:
+    if model is not None and phase != "plan":
         entry["model_requested"] = model
-    else:
+    elif phase != "plan":
         entry.setdefault("model_requested", None)
     entry.pop("model", None)
 
@@ -1385,6 +1552,194 @@ def self_test() -> int:
         state_path = devlyn / "pipeline.state.json"
         write_state(state_path, {"phases": {}})
 
+        # Iter-0089 P-0089-1/2/6: PLAN authorization is a CLI-level,
+        # state-derived ledger contract. Rejections must leave the actual
+        # state file byte-identical, not merely preserve an in-memory copy.
+        script = str(pathlib.Path(__file__).resolve())
+        digest0 = hashlib.sha256(b"plan prompt round 0").hexdigest()
+        digest1 = hashlib.sha256(b"plan prompt round 1").hexdigest()
+
+        def plan_cli(*event_args: str) -> subprocess.CompletedProcess[str]:
+            return subprocess.run(
+                [
+                    sys.executable, script, "--devlyn-dir", str(devlyn),
+                    "--phase", "plan", *event_args,
+                ],
+                capture_output=True, text=True, check=False,
+            )
+
+        def assert_plan_rejected_unchanged(
+            expected_stderr: str, *event_args: str,
+        ) -> None:
+            before = state_path.read_bytes()
+            before_hash = hashlib.sha256(before).hexdigest()
+            result = plan_cli(*event_args)
+            assert result.returncode != 0, result.stdout
+            assert result.stderr.strip() == expected_stderr, result.stderr
+            after = state_path.read_bytes()
+            assert after == before
+            assert hashlib.sha256(after).hexdigest() == before_hash
+
+        required_spawn = (
+            "spawn", "--round", "0", "--engine", "claude",
+            "--model", "plan-test-model", "--prompt-sha256", digest0,
+        )
+        assert_plan_rejected_unchanged(
+            "error: phases.plan spawn requires --engine",
+            "spawn", "--round", "0", "--model", "plan-test-model",
+            "--prompt-sha256", digest0,
+        )
+        assert_plan_rejected_unchanged(
+            "error: phases.plan spawn requires --model",
+            "spawn", "--round", "0", "--engine", "claude",
+            "--prompt-sha256", digest0,
+        )
+        assert_plan_rejected_unchanged(
+            "error: phases.plan spawn requires --prompt-sha256",
+            "spawn", "--round", "0", "--engine", "claude",
+            "--model", "plan-test-model",
+        )
+        assert_plan_rejected_unchanged(
+            "error: phases.plan spawn requires --prompt-sha256",
+            "spawn", "--round", "0", "--engine", "claude",
+            "--model", "plan-test-model", "--prompt-sha256", "ABC",
+        )
+        assert_plan_rejected_unchanged(
+            "BLOCKED:plan-round-nonmonotonic: expected=0 supplied=1",
+            "spawn", "--round", "1", "--engine", "claude",
+            "--model", "plan-test-model", "--prompt-sha256", digest0,
+        )
+
+        result = plan_cli(*required_spawn)
+        assert result.returncode == 0, result.stderr
+        plan0 = read_state(state_path)["phases"]["plan"]
+        assert {field: plan0[field] for field in PLAN_SPAWN_RECEIPT_FIELDS} == {
+            "round": 0,
+            "started_at": plan0["started_at"],
+            "triggered_by": None,
+            "engine": "claude",
+            "model_requested": "plan-test-model",
+            "prompt_sha256": digest0,
+        }
+        result = plan_cli("complete", "--verdict", "NEEDS_WORK")
+        assert result.returncode == 0, result.stderr
+        completed0 = read_state(state_path)["phases"]["plan"]
+        assert all(field in completed0 for field in PLAN_RECEIPT_FIELDS)
+        assert completed0["model_effective"] is None
+        assert completed0["completed_at"] is not None
+        assert completed0["duration_ms"] >= 0
+        assert_plan_rejected_unchanged(
+            "BLOCKED:plan-round-nonmonotonic: expected=1 supplied=0",
+            "spawn", "--round", "0", "--triggered-by", "plan",
+            "--engine", "claude", "--model", "plan-test-model",
+            "--prompt-sha256", digest1,
+        )
+        assert_plan_rejected_unchanged(
+            "BLOCKED:plan-round-nonmonotonic: expected=1 supplied=2",
+            "spawn", "--round", "2", "--triggered-by", "plan",
+            "--engine", "claude", "--model", "plan-test-model",
+            "--prompt-sha256", digest1,
+        )
+        assert_plan_rejected_unchanged(
+            "error: phases.plan re-spawn requires --triggered-by",
+            "spawn", "--round", "1", "--engine", "claude",
+            "--model", "plan-test-model", "--prompt-sha256", digest1,
+        )
+        result = plan_cli(
+            "spawn", "--round", "1", "--triggered-by", "plan",
+            "--engine", "claude", "--model", "plan-test-model",
+            "--prompt-sha256", digest1,
+        )
+        assert result.returncode == 0, result.stderr
+        plan1 = read_state(state_path)["phases"]["plan"]
+        assert len(plan1["history"]) == 1
+        assert set(plan1["history"][0]) == set(PLAN_RECEIPT_FIELDS)
+        assert plan1["history"][0]["prompt_sha256"] == digest0
+        assert plan1["prompt_sha256"] == digest1
+        guard_error = (
+            "error: phases.plan complete with PASS or PASS_WITH_ISSUES requires "
+            "--phase plan transition --verdict <verdict> --next-phase <phase>"
+        )
+        assert_plan_rejected_unchanged(
+            guard_error, "complete", "--verdict", "PASS",
+        )
+        assert_plan_rejected_unchanged(
+            guard_error, "complete", "--verdict", "PASS_WITH_ISSUES",
+        )
+        result = plan_cli(
+            "transition", "--verdict", "PASS", "--next-phase", "implement",
+            "--next-round", "0", "--next-engine", "claude",
+        )
+        assert result.returncode == 0, result.stderr
+        for supplied_round in (0, 1, 2):
+            assert_plan_rejected_unchanged(
+                "BLOCKED:plan-respawn-exhausted",
+                "spawn", "--round", str(supplied_round),
+                "--triggered-by", "plan", "--engine", "claude",
+                "--model", "plan-test-model", "--prompt-sha256", digest1,
+            )
+        old_receipt = {
+            "started_at": "2026-01-01T00:00:00.000Z",
+            "verdict": "PASS",
+            "completed_at": "2026-01-01T00:00:01.000Z",
+            "duration_ms": 1000,
+        }
+        assert not is_plan_dispatch_receipt(old_receipt)
+        assert is_plan_dispatch_receipt(read_state(state_path)["phases"]["plan"])
+        write_state(state_path, {
+            "phases": {
+                "plan": {
+                    "started_at": "2026-01-01T00:00:00.000Z",
+                    "completed_at": None,
+                    "duration_ms": None,
+                    "round": 0,
+                    "triggered_by": None,
+                    "verdict": None,
+                },
+                "implement": None,
+            }
+        })
+        result = plan_cli("complete", "--verdict", "BLOCKED")
+        assert result.returncode == 0, result.stderr
+        assert read_state(state_path)["phases"]["plan"]["verdict"] == "BLOCKED"
+        write_state(state_path, {
+            "phases": {
+                "plan": {
+                    "started_at": "2026-01-01T00:00:00.000Z",
+                    "completed_at": None,
+                    "duration_ms": None,
+                    "round": 0,
+                    "triggered_by": None,
+                    "verdict": None,
+                },
+                "implement": None,
+            }
+        })
+        result = plan_cli(
+            "complete", "--verdict", "PASS", "--engine-session-log",
+            str(devlyn / "missing-session.jsonl"),
+        )
+        assert result.returncode == 1, result.stderr
+        assert "BLOCKED:model-attestation-failed" in result.stderr
+        assert guard_error not in result.stderr
+        attestation_blocked = read_state(state_path)["phases"]["plan"]
+        assert attestation_blocked["verdict"] == "BLOCKED"
+        assert attestation_blocked["completed_at"] is not None
+        assert attestation_blocked["model_effective"] is None
+        legacy_state = {"phases": {"plan": old_receipt | {"round": 0}}}
+        write_state(state_path, legacy_state)
+        result = plan_cli(
+            "spawn", "--round", "1", "--triggered-by", "plan",
+            "--engine", "claude", "--model", "plan-test-model",
+            "--prompt-sha256", digest1,
+        )
+        assert result.returncode == 0, result.stderr
+        archived_legacy = read_state(state_path)["phases"]["plan"]["history"][0]
+        assert archived_legacy == old_receipt
+        print("PASS iter-0089 PLAN ledger: P-0089-1/2/6")
+
+        write_state(state_path, {"phases": {}})
+
         # Round 0: spawn -> complete.
         state = read_state(state_path)
         do_spawn(state, "implement", 0, None, None, "claude", None)
@@ -1657,7 +2012,10 @@ def self_test() -> int:
         # flow does.
         write_state(state_path, {"phases": {}})
         state = read_state(state_path)
-        do_spawn(state, "plan", 0, None, None, None, None)
+        do_spawn(
+            state, "plan", 0, None, None, "claude", "plan-test-model",
+            prompt_sha256=digest0,
+        )
         write_state(state_path, state)
         state = read_state(state_path)
         try:
@@ -1782,14 +2140,24 @@ def self_test() -> int:
         subprocess.run(["git", "config", "user.name", "self-test"], cwd=work, check=True)
         (work / "allowed.txt").write_text("base\n", encoding="utf-8")
         (work / "blocked.txt").write_text("base\n", encoding="utf-8")
+        (work / "blocked:literal.txt:1").write_text("base\n", encoding="utf-8")
+        (work / "blocked:raw.txt").write_text("base\n", encoding="utf-8")
+        (work / "branchbase").write_text("line\n" * 10, encoding="utf-8")
+        (work / "branchbase:7").write_text("base\n", encoding="utf-8")
+        (work / "branchbase:dir").mkdir()
+        (work / "branchbase:dir" / "marker").write_text("base\n", encoding="utf-8")
+        (work / "exact:1").write_text("base\n", encoding="utf-8")
         (work / "schedule").mkdir()
         (work / "schedule" / "__init__.py").write_text("line\n" * 700, encoding="utf-8")
         (work / "test_schedule.py").write_text("line\n", encoding="utf-8")
         (work / "tests").mkdir()
         (work / "tests" / "cli.test.js").write_text("line\n" * 170, encoding="utf-8")
+        (work / "tests" / "literal:1-3").write_text("line\n", encoding="utf-8")
         subprocess.run(
-            ["git", "add", "--", "allowed.txt", "blocked.txt", "schedule/__init__.py",
-             "test_schedule.py", "tests/cli.test.js"],
+            ["git", "add", "--", "allowed.txt", "blocked.txt", "blocked:literal.txt:1",
+             "blocked:raw.txt", "branchbase", "branchbase:7", "branchbase:dir/marker",
+             "exact:1", "schedule/__init__.py", "test_schedule.py", "tests/cli.test.js",
+             "tests/literal:1-3"],
             cwd=work, check=True,
         )
         subprocess.run(["git", "commit", "-qm", "base"], cwd=work, check=True)
@@ -1846,8 +2214,53 @@ def self_test() -> int:
         validate_surface_prompt(work_devlyn, surface_state)
         ensure_surface_clean_baseline(work, work_devlyn, surface_state)
         surface = validate_authorized_surface(
-            '["allowed.txt", "schedule/**", "test_schedule.py", "tests/**"]'
+            '["allowed.txt", "branchbase", "exact-link", "exact:1", "schedule/**", '
+            '"test_schedule.py", "tests/**", "x.ts"]'
         )
+        outside = devlyn / "outside.txt"
+        outside.write_text("outside\n", encoding="utf-8")
+        (work / "outside-link").symlink_to(outside)
+        assert worktree_file_exists(work, "allowed.txt")
+        assert not worktree_file_exists(work, str(outside))
+        assert not worktree_file_exists(work, "../outside.txt")
+        assert not worktree_file_exists(work, "outside-link")
+        assert worktree_path_exists(work, "branchbase:dir")
+        assert not worktree_path_exists(work, str(outside))
+        assert not worktree_path_exists(work, "../outside.txt")
+        assert not worktree_path_exists(work, "outside-link")
+        (work / "outside-link").unlink()
+        for link, target in (
+            ("exact-link", "allowed.txt"),
+            ("tests/inside-link", "cli.test.js"),
+        ):
+            (work / link).symlink_to(target)
+            output = work_devlyn / "surface-close.stdout"
+            output.write_text(
+                f"UVR-STALE: N/A {link} — contained symlink\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                encoding="utf-8",
+            )
+            validate_surface_adjudication(
+                work, work_devlyn, surface_state, surface,
+            )
+            (work / link).unlink()
+        for link in ("exact-link", "tests/outside-link"):
+            (work / link).symlink_to(outside)
+            output = work_devlyn / "surface-close.stdout"
+            output.write_text(
+                f"UVR-STALE: N/A {link} — escaping symlink\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                encoding="utf-8",
+            )
+            try:
+                validate_surface_adjudication(
+                    work, work_devlyn, surface_state, surface,
+                )
+            except SystemExit as exc:
+                assert "citation-missing" in str(exc), (link, exc)
+            else:
+                raise AssertionError(f"SURFACE_CLOSE followed escaping symlink: {link}")
+            (work / link).unlink()
         entry = surface_entry(surface_state)
         assert entry["prompt_sha256"] == file_sha256(prompt)
         assert entry["model_requested"] == "sonnet"
@@ -1873,6 +2286,18 @@ def self_test() -> int:
             encoding="utf-8",
         )
         validate_surface_adjudication(work, work_devlyn, surface_state, surface)
+        output.write_text(
+            "UVR-STALE: N/A exact:1 — exact colon path is unchanged\n"
+            "PATH-TEST: N/A exact:1:1 — exact colon path line is covered\nPASS\n",
+            encoding="utf-8",
+        )
+        validate_surface_adjudication(work, work_devlyn, surface_state, surface)
+        output.write_text(
+            "UVR-STALE: N/A tests/literal:1-3 — literal range-shaped path is unchanged\n"
+            "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+            encoding="utf-8",
+        )
+        validate_surface_adjudication(work, work_devlyn, surface_state, surface)
 
         output.write_text(
             "PATH-TEST review confirms every success/failure path the goal specifies (chaining in both positions, exact-nth-run cancellation via both `run_pending()` and `run_all()`, first-limit-wins with `.until()` in both directions, `next_run`/`idle_seconds` reflecting removal, validation errors, repeated-call override, per-job independence) is already covered by the added tests — no gap found.\n\n"
@@ -1924,6 +2349,81 @@ def self_test() -> int:
                 "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
                 "citation-missing",
             ),
+            (
+                "UVR-STALE: N/A allowed.txt:49-73,223-235,293-295 — production range citation\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "adjudication-malformed",
+            ),
+            (
+                "UVR-STALE: N/A allowed.txt:1, allowed.txt:1 — production list citation\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "adjudication-malformed",
+            ),
+            (
+                "UVR-STALE: N/A tests/cli.test.js:1-3 — glob range citation\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "adjudication-malformed",
+            ),
+            (
+                "UVR-STALE: N/A x.ts:12:34 — doubled line citation\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "adjudication-malformed",
+            ),
+            (
+                "UVR-STALE: N/A allowed.txt:0 — zero line citation\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "adjudication-malformed",
+            ),
+            (
+                "UVR-STALE: N/A allowed.txt:012 — leading-zero line citation\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "adjudication-malformed",
+            ),
+            (
+                "UVR-STALE: N/A allowed.txt: — empty line citation\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "adjudication-malformed",
+            ),
+            (
+                "UVR-STALE: N/A blocked.txt:1 — blocked parsed path\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "out-of-surface",
+            ),
+            (
+                "UVR-STALE: N/A blocked.txt:1-3 — blocked range citation\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "out-of-surface",
+            ),
+            (
+                "UVR-STALE: N/A blocked:literal.txt:1 — blocked raw colon path\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "out-of-surface",
+            ),
+            (
+                "UVR-STALE: N/A blocked:raw.txt:1 — blocked parsed colon path\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "out-of-surface",
+            ),
+            (
+                "UVR-STALE: N/A branchbase:7 — existing unauthorized raw path\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "out-of-surface",
+            ),
+            (
+                "UVR-STALE: N/A branchbase:dir:1 — existing unauthorized parsed directory\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "out-of-surface",
+            ),
+            (
+                "UVR-STALE: N/A tests/../blocked.txt:1 — wildcard traversal\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "out-of-surface",
+            ),
+            (
+                "UVR-STALE: N/A tests/ghost.txt:1 — nonexistent glob descendant\n"
+                "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+                "citation-missing",
+            ),
         )
         for raw_output, marker in rejected_outputs:
             output.write_text(raw_output, encoding="utf-8")
@@ -1934,6 +2434,14 @@ def self_test() -> int:
             else:
                 raise AssertionError(f"SURFACE_CLOSE accepted invalid adjudication: {marker}")
 
+        output.write_text(
+            "UVR-STALE: N/A allowed.txt:49-73,223-235,293-295 — production range citation\n"
+            "PATH-TEST: FIRED allowed.txt:1\nPASS\n",
+            encoding="utf-8",
+        )
+        require_surface_adjudication_malformed(
+            work, work_devlyn, surface_state, surface,
+        )
         output.write_text(
             "UVR-STALE: N/A allowed.txt:1 — no stale interface text\n"
             "PATH-TEST: N/A allowed.txt:1 — requested path already covered\nPASS\n",
@@ -2069,10 +2577,162 @@ def self_test() -> int:
         }) + "\n", encoding="utf-8")
         assert parse_effective_model(rollout_log) == "gpt-5.6-terra"
         claude_log = devlyn / "claude-result.json"
-        claude_log.write_text(json.dumps({
-            "modelUsage": {"claude-alpha-1": {"inputTokens": 1}},
-        }) + "\n", encoding="utf-8")
-        assert parse_effective_model(claude_log) == "claude-alpha-1"
+
+        def claude_wrapper(primary_usage, entries):
+            wrapper = {"modelUsage": {}}
+            if primary_usage is not None:
+                wrapper["usage"] = dict(zip((
+                    "input_tokens", "output_tokens", "cache_read_input_tokens",
+                    "cache_creation_input_tokens",
+                ), primary_usage))
+            for model, entry_usage, metadata in entries:
+                entry = dict(zip((
+                    "inputTokens", "outputTokens", "cacheReadInputTokens",
+                    "cacheCreationInputTokens",
+                ), entry_usage))
+                entry.update(metadata)
+                wrapper["modelUsage"][model] = entry
+            return wrapper
+
+        oversized_counter = 10 ** 400
+        claude_selector_rows = (
+            (
+                "singleton",
+                {"modelUsage": {"claude-alpha-1": {"inputTokens": 1}}},
+                "claude-alpha-1",
+            ),
+            (
+                "opus-primary",
+                claude_wrapper(
+                    (2854, 9927, 1095180, 73889),
+                    (
+                        ("claude-" "haiku-4-5-20251001", (4106, 14, 0, 0), {
+                            "costUSD": 0.004176,
+                        }),
+                        ("claude-" "opus-5[1m]", (2854, 9927, 1095180, 73889), {
+                            "costUSD": 1.5489249999999999,
+                            "canonicalModel": "claude-" "opus-5",
+                        }),
+                    ),
+                ),
+                "claude-" "opus-5[1m]",
+            ),
+            (
+                "fable-primary",
+                claude_wrapper(
+                    (8068, 26740, 403950, 76656),
+                    (
+                        ("claude-" "haiku-4-5-20251001", (2246, 22, 0, 0), {
+                            "costUSD": 0.002356,
+                        }),
+                        ("claude-" "fable-5", (8068, 26740, 403950, 76656), {
+                            "costUSD": 3.35475,
+                            "canonicalModel": "claude-" "fable-5",
+                        }),
+                    ),
+                ),
+                "claude-" "fable-5",
+            ),
+            (
+                "rank-confound",
+                claude_wrapper(
+                    (3, 5, 7, 11),
+                    (
+                        ("larger-auxiliary", (300000, 500000, 700000, 1100000), {
+                            "costUSD": 999.0,
+                        }),
+                        ("expected-primary", (3, 5, 7, 11), {"costUSD": 0.01}),
+                    ),
+                ),
+                "expected-primary",
+            ),
+            (
+                "oversized-integer",
+                claude_wrapper(
+                    (oversized_counter, 5, 7, 11),
+                    (
+                        ("oversized-primary", (oversized_counter, 5, 7, 11), {}),
+                        ("auxiliary", (3, 5, 7, 11), {}),
+                    ),
+                ),
+                "oversized-primary",
+            ),
+            (
+                "zero-match",
+                claude_wrapper(
+                    (1, 2, 3, 4),
+                    (("model-a", (10, 2, 3, 4), {}), ("model-b", (1, 20, 3, 4), {})),
+                ),
+                ValueError,
+            ),
+            (
+                "duplicate-match",
+                claude_wrapper(
+                    (1, 2, 3, 4),
+                    (("model-a", (1, 2, 3, 4), {}), ("model-b", (1, 2, 3, 4), {})),
+                ),
+                ValueError,
+            ),
+            (
+                "missing-top-level-usage",
+                claude_wrapper(
+                    None,
+                    (("model-a", (1, 2, 3, 4), {}), ("model-b", (5, 6, 7, 8), {})),
+                ),
+                ValueError,
+            ),
+            (
+                "malformed-top-level-float",
+                claude_wrapper(
+                    (1.0, 2, 3, 4),
+                    (("model-a", (1, 2, 3, 4), {}), ("model-b", (5, 6, 7, 8), {})),
+                ),
+                ValueError,
+            ),
+            (
+                "malformed-top-level-negative",
+                claude_wrapper(
+                    (-1, 2, 3, 4),
+                    (("model-a", (-1, 2, 3, 4), {}), ("model-b", (5, 6, 7, 8), {})),
+                ),
+                ValueError,
+            ),
+            (
+                "malformed-entry-counter",
+                claude_wrapper(
+                    (1, 2, 3, 4),
+                    (("model-a", (1, 2, 3, 4), {}), ("model-b", (True, 20, 30, 40), {})),
+                ),
+                ValueError,
+            ),
+        )
+        for row_name, wrapper, expected in claude_selector_rows:
+            claude_log.write_text(json.dumps(wrapper) + "\n", encoding="utf-8")
+            if expected is ValueError:
+                try:
+                    parse_effective_model(claude_log)
+                except ValueError:
+                    pass
+                else:
+                    raise AssertionError(f"Claude selector accepted {row_name}")
+            else:
+                assert parse_effective_model(claude_log) == expected, row_name
+
+        claude_log.write_text(
+            json.dumps(claude_selector_rows[-1][1]) + "\n", encoding="utf-8"
+        )
+        write_state(state_path, {"phases": {}})
+        state = read_state(state_path)
+        do_spawn(
+            state, "plan", 0, None, None, "claude", "claude-default",
+            prompt_sha256=digest0,
+        )
+        malformed = do_complete(
+            state, "plan", "PASS", None, None, None, None, None, str(claude_log)
+        )
+        assert malformed and "model-attestation-failed" in malformed
+        assert state["phases"]["plan"]["model_effective"] is None
+        assert state["phases"]["plan"]["verdict"] == "BLOCKED"
 
         # Requested/effective drift is a persisted, fail-closed attestation.
         write_state(state_path, {"phases": {}})
@@ -2087,6 +2747,21 @@ def self_test() -> int:
         assert mismatched["model_effective"] == "gpt-5.6-terra"
         assert mismatched["verdict"] == "BLOCKED"
 
+        claude_log.write_text(
+            json.dumps(claude_selector_rows[1][1]) + "\n", encoding="utf-8"
+        )
+        write_state(state_path, {"phases": {}})
+        state = read_state(state_path)
+        do_spawn(state, "build_gate", 0, None, None, "claude", "claude-" "opus-5")
+        mismatch = do_complete(
+            state, "build_gate", "PASS", None, None, None, None, None, str(claude_log)
+        )
+        mismatched = state["phases"]["build_gate"]
+        assert mismatch and "model-attestation-mismatch" in mismatch
+        assert mismatched["model_requested"] == "claude-" "opus-5"
+        assert mismatched["model_effective"] == "claude-" "opus-5[1m]"
+        assert mismatched["verdict"] == "BLOCKED"
+
         # A retained mutation-worker session makes the completion flag
         # mandatory; without a retained file, null remains legal.
         retained_log = devlyn / "implement.worker-session.0.jsonl"
@@ -2128,14 +2803,20 @@ def self_test() -> int:
         # Supplied evidence must parse and never silently record null.
         write_state(state_path, {"phases": {}})
         state = read_state(state_path)
-        do_spawn(state, "plan", 0, None, None, "claude", "claude-default")
+        do_spawn(
+            state, "plan", 0, None, None, "claude", "claude-default",
+            prompt_sha256=digest0,
+        )
         assert do_complete(state, "plan", "PASS", None, None, None, None, None) is None
         assert state["phases"]["plan"]["model_effective"] is None
         invalid_log = devlyn / "invalid-session.log"
         invalid_log.write_text("no model evidence\n", encoding="utf-8")
         write_state(state_path, {"phases": {}})
         state = read_state(state_path)
-        do_spawn(state, "plan", 0, None, None, "claude", "claude-default")
+        do_spawn(
+            state, "plan", 0, None, None, "claude", "claude-default",
+            prompt_sha256=digest0,
+        )
         invalid = do_complete(
             state, "plan", "PASS", None, None, None, None, None, str(invalid_log)
         )
@@ -2506,7 +3187,7 @@ def main() -> int:
 
     spawn_p = sub.add_parser("spawn")
     spawn_p.add_argument("--round", type=int, required=True)
-    spawn_p.add_argument("--triggered-by", choices=sorted(VALID_TRIGGERS), default=None)
+    spawn_p.add_argument("--triggered-by", choices=sorted(SPAWN_TRIGGERS), default=None)
     spawn_p.add_argument("--pre-sha", default=None)
     spawn_p.add_argument("--input-patch-sha256", default=None)
     spawn_p.add_argument("--prompt-sha256", default=None)
@@ -2533,7 +3214,7 @@ def main() -> int:
     transition_p.add_argument("--engine-session-log", default=None)
     transition_p.add_argument("--next-phase", choices=sorted(PHASE_NAMES), required=True)
     transition_p.add_argument("--next-round", type=int, required=True)
-    transition_p.add_argument("--next-triggered-by", choices=sorted(VALID_TRIGGERS), default=None)
+    transition_p.add_argument("--next-triggered-by", choices=sorted(SPAWN_TRIGGERS), default=None)
     transition_p.add_argument("--next-pre-sha", default=None)
     transition_p.add_argument("--next-input-patch-sha256", default=None)
     transition_p.add_argument("--next-prompt-sha256", default=None)
@@ -2560,7 +3241,6 @@ def main() -> int:
     }
     if not args.phase or args.event not in {"spawn", "complete", "transition", "durability-enforce", *surface_events}:
         ap.error("--phase and a phase event are required unless --self-test")
-
     devlyn = pathlib.Path(args.devlyn_dir)
     if not devlyn.is_dir():
         sys.stderr.write(f"error: {devlyn} is not a directory\n")
@@ -2701,6 +3381,14 @@ def main() -> int:
             state, args.phase, args.verdict, args.post_sha, args.findings_file,
             args.log_file, args.engine, args.model, args.engine_session_log, devlyn,
         )
+        if (
+            args.phase == "plan"
+            and state["phases"]["plan"]["verdict"] in {"PASS", "PASS_WITH_ISSUES"}
+        ):
+            raise SystemExit(
+                "error: phases.plan complete with PASS or PASS_WITH_ISSUES requires "
+                "--phase plan transition --verdict <verdict> --next-phase <phase>"
+            )
 
     if args.event not in {"spawn", "transition"}:
         write_state(state_path, state)