wydcode 0.4.3

package/socra_harness/job/manager.py

@@ -0,0 +1,3785 @@
+from __future__ import annotations
+
+import argparse
+import base64
+import difflib
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from pathlib import Path
+from typing import Any
+
+from ..attempts import AttemptFailure, attempt_failure_payload, classify_creator_finish
+from ..central_traces import export_failed_trace, export_promoted_trace, retrieve_validated_behavior
+from ..recurrence import canonical_json as recurrence_canonical_json
+from ..recurrence import behavior_overlaps_patch
+from ..recurrence import injection_budget_decision
+from ..recurrence import sha256_json as recurrence_sha256_json
+from .events import JobEventLog, read_events
+from .lock import JobLock
+from .planner import canonical_task_hash, materialize_plan_from_events, planner_tasks_for_goal, ready_task_ids, validate_task_graph
+from .state import replay, state_to_json, write_state_snapshot
+
+CREATOR_PROMPT_LAYOUT = "stable_prefix_v2_anchored_large_file"
+MAX_JSON_CONTRACT_DECLARED_FILES = 2
+ANCHORED_EDIT_OUTPUT_HEADROOM_RATIO = 0.75
+MAX_ANCHORED_EDITS = 16
+
+
+def slugify(value: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9]+", "-", value.strip().lower()).strip("-")
+    return slug[:48] or "job"
+
+
+def job_root(project: Path) -> Path:
+    return project / ".socra" / "jobs"
+
+
+def new_job_id(goal: str) -> str:
+    return f"{slugify(goal)}-{uuid.uuid4().hex[:8]}"
+
+
+def write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def copytree_ignore_for_runner(_dir: str, names: list[str]) -> set[str]:
+    ignored = {
+        ".git",
+        ".socra",
+        "node_modules",
+        "dist",
+        "build",
+        ".next",
+        ".turbo",
+        ".vite",
+        "coverage",
+    }
+    return {name for name in names if name in ignored}
+
+
+def sha256_file(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def elapsed_ms(start: float) -> int:
+    return int(round((time.monotonic() - start) * 1000))
+
+
+def task_inventory_package_entry(job_dir: Path | None) -> dict[str, Any] | None:
+    if job_dir is None:
+        return None
+    inventory_path = job_dir / "artifacts" / "tasks" / "task-001" / "inventory.json"
+    if not inventory_path.exists():
+        return None
+    try:
+        inventory = json.loads(inventory_path.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001 - conventions are advisory context.
+        return None
+    for item in inventory.get("declared_files") or []:
+        if isinstance(item, dict) and item.get("path") == "package.json":
+            return {
+                "path": "package.json",
+                "sha256": item.get("sha256"),
+                "scripts": item.get("scripts") or [],
+                "dependencies": item.get("dependencies") or [],
+                "dev_dependencies": item.get("dev_dependencies") or [],
+                "inventory_path": str(inventory_path.relative_to(job_dir)),
+            }
+    return None
+
+
+def project_conventions(project: Path, job_dir: Path | None = None) -> dict[str, Any]:
+    package_path = project / "package.json"
+    package_type = None
+    package_source = "package_json_current_file"
+    inventory_package = task_inventory_package_entry(job_dir)
+    if package_path.exists() and package_path.is_file():
+        try:
+            package = json.loads(package_path.read_text(encoding="utf-8"))
+            package_type = package.get("type") if isinstance(package.get("type"), str) else None
+            if inventory_package:
+                current_hash = sha256_file(package_path)
+                if inventory_package.get("sha256") == current_hash:
+                    package_source = "task_001_inventory_package_json_hash_match"
+                else:
+                    package_source = "package_json_current_file_inventory_hash_mismatch"
+        except Exception:  # noqa: BLE001 - conventions are advisory context.
+            package_type = None
+    javascript_module_system = "esm" if package_type == "module" else "commonjs_or_unspecified"
+    return {
+        "source": package_source,
+        "inventory_package": inventory_package,
+        "package_type": package_type,
+        "javascript_module_system": javascript_module_system,
+        "javascript_import_rule": (
+            "Use ESM import/export syntax with explicit .js relative import extensions. "
+            "Do not use require(), module.exports, or exports.*."
+            if javascript_module_system == "esm"
+            else "Follow the existing project module syntax."
+        ),
+    }
+
+
+def write_handoff(job_dir: Path, state: dict[str, Any], plan: dict[str, Any]) -> None:
+    tasks = plan.get("tasks") if isinstance(plan.get("tasks"), list) else []
+    pending = [task for task in tasks if task.get("status") == "pending"]
+    completed = [task for task in tasks if task.get("status") == "passed"]
+    creator = state.get("creator_config") if isinstance(state.get("creator_config"), dict) else {}
+    text = "\n".join(
+        [
+            f"# Socra Job Handoff: {state.get('goal')}",
+            "",
+            f"- Job: `{state.get('job_id')}`",
+            f"- Phase: `{state.get('phase')}`",
+            f"- Project: `{state.get('project')}`",
+            f"- Completed tasks: {len(completed)}",
+            f"- Pending tasks: {len(pending)}",
+            f"- Active task: `{state.get('active_task_id')}`",
+            f"- Creator model: `{creator.get('model_alias') or creator.get('model') or 'unconfigured'}`",
+            f"- Creator endpoint: `{creator.get('endpoint') or 'unconfigured'}`",
+            "",
+            "## Next Action",
+            "",
+            "Resume can safely replay `events.jsonl` and continue from the first ready pending task.",
+            "",
+        ]
+    )
+    (job_dir / "handoff.md").write_text(text, encoding="utf-8")
+
+
+def starter_plan(goal: str) -> dict[str, Any]:
+    return {
+        "version": 1,
+        "goal": goal,
+        "tasks": [
+            {
+                "id": "task-001",
+                "description": "Clarify architecture and create the first implementation slice.",
+                "acceptance": ["A concrete implementation plan exists", "Declared files are known before coding"],
+                "risk_tier": 0,
+                "status": "pending",
+                "depends_on": [],
+                "declared_files": [],
+                "attempt_count": 0,
+                "produced_artifacts": [],
+            }
+        ],
+    }
+
+
+def load_plan(job_dir: Path) -> dict[str, Any]:
+    path = job_dir / "plan.json"
+    fallback = {"version": 1, "goal": "", "tasks": []}
+    if not path.exists():
+        return fallback
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def materialize_job_plan(job_dir: Path) -> dict[str, Any]:
+    return materialize_plan_from_events(read_events(job_dir / "events.jsonl"), load_plan(job_dir))
+
+
+def plan_prereg_metadata(job_dir: Path) -> dict[str, Any]:
+    prereg_dir = job_dir / "artifacts" / "preregistration"
+    candidates = sorted(prereg_dir.glob("*.json"))
+    if not candidates:
+        return {}
+    path = candidates[0]
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return {
+        "path": str(path.relative_to(job_dir)),
+        "sha256": hashlib.sha256(path.read_bytes()).hexdigest(),
+        "expected_task_count": payload.get("expected_task_count"),
+    }
+
+
+def find_latest_incomplete_job(project: Path) -> Path | None:
+    root = job_root(project)
+    if not root.exists():
+        return None
+    candidates = []
+    for job_dir in root.iterdir():
+        if not job_dir.is_dir() or not (job_dir / "events.jsonl").exists():
+            continue
+        state = replay(read_events(job_dir / "events.jsonl"))
+        if state.phase not in {"done", "failed"}:
+            candidates.append((state.last_seq, job_dir))
+    if not candidates:
+        return None
+    return sorted(candidates, key=lambda item: item[0], reverse=True)[0][1]
+
+
+def job_start_main(args: argparse.Namespace) -> int:
+    project = args.project.expanduser().resolve()
+    project.mkdir(parents=True, exist_ok=True)
+    job_id = args.job_id or new_job_id(args.goal)
+    job_dir = job_root(project) / job_id
+    job_dir.mkdir(parents=True, exist_ok=False)
+    with JobLock(job_dir / ".lock"):
+        for folder in ["artifacts", "patches", "sandbox", "checkpoints"]:
+            (job_dir / folder).mkdir(parents=True, exist_ok=True)
+
+        plan = starter_plan(args.goal)
+        write_json(job_dir / "plan.json", plan)
+
+        log = JobEventLog(job_dir / "events.jsonl", job_id)
+        log.append("job_created", {"goal": args.goal, "project": str(project)})
+        log.append("plan_written", {"plan": "plan.json", "task_count": len(plan["tasks"])})
+        log.append("job_paused", {"reason": "start_only_no_execution"})
+
+        state = replay(read_events(job_dir / "events.jsonl"))
+        write_state_snapshot(job_dir / "job.json", state)
+        write_handoff(job_dir, state_to_json(state), plan)
+
+    print(f"Created Socra job: {job_id}")
+    print(f"Project: {project}")
+    print(f"Job dir: {job_dir}")
+    print(f"Phase: {state.phase}")
+    return 0
+
+
+def job_resume_main(args: argparse.Namespace) -> int:
+    project = args.project.expanduser().resolve()
+    if args.job_id:
+        job_dir = job_root(project) / args.job_id
+    else:
+        found = find_latest_incomplete_job(project)
+        if not found:
+            raise SystemExit(f"No incomplete Socra jobs found under {job_root(project)}")
+        job_dir = found
+    with JobLock(job_dir / ".lock"):
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        write_state_snapshot(job_dir / "job.json", state)
+        write_json(job_dir / "plan.json", plan)
+        write_handoff(job_dir, state_to_json(state), plan)
+
+    print(f"Resumed Socra job: {state.job_id}")
+    print(f"Project: {state.project}")
+    print(f"Job dir: {job_dir}")
+    print(f"Phase: {state.phase}")
+    print(f"Events replayed: {len(events)}")
+    print(f"Active task: {state.active_task_id or 'none'}")
+    print(f"Plan tasks: {len(plan.get('tasks', []))}")
+    print(f"Ready tasks: {', '.join(ready_task_ids(plan)[:8]) or 'none'}")
+    print(f"Handoff: {job_dir / 'handoff.md'}")
+    return 0
+
+
+def job_plan_main(args: argparse.Namespace) -> int:
+    project = args.project.expanduser().resolve()
+    if args.job_id:
+        job_dir = job_root(project) / args.job_id
+    else:
+        found = find_latest_incomplete_job(project)
+        if not found:
+            raise SystemExit(f"No incomplete Socra jobs found under {job_root(project)}")
+        job_dir = found
+
+    with JobLock(job_dir / ".lock"):
+        events = read_events(job_dir / "events.jsonl")
+        if any(event.type == "plan_committed" for event in events) and not args.force:
+            raise SystemExit("Plan already committed for this job. Pass --force to append a revised plan.")
+
+        state = replay(events)
+        prereg = plan_prereg_metadata(job_dir)
+        tasks = planner_tasks_for_goal(state.goal, project)
+        validate_task_graph(tasks)
+        task_hash = canonical_task_hash(tasks)
+        expected_count = prereg.get("expected_task_count")
+        actual_count = len(tasks)
+        log = JobEventLog(job_dir / "events.jsonl", state.job_id or job_dir.name)
+
+        previous_commits = [event for event in events if event.type == "plan_committed"]
+        revision = len(previous_commits) + 1
+        if previous_commits:
+            log.append("plan_revised", {"reason": args.reason or "manual_replan", "previous_plan_event_seen": True})
+            if args.reason and "count" in args.reason.lower():
+                log.append(
+                    "planner_count_anchor_audit",
+                    {
+                        "previous_exact_match_to_prereg": True,
+                        "template_authored_after_prereg_visible": True,
+                        "runtime_planner_receives_expected_count": False,
+                        "remediation": "replan_to_granularity_and_record_count_delta",
+                    },
+                )
+
+        for task in tasks:
+            log.append("task_added", task)
+
+        if expected_count is not None and int(expected_count) != actual_count:
+            log.append(
+                "plan_count_delta_recorded",
+                {
+                    "expected_task_count": int(expected_count),
+                    "actual_task_count": actual_count,
+                    "delta": actual_count - int(expected_count),
+                    "note": "Planner follows task granularity; preregistered count is a reference, not a target.",
+                },
+            )
+
+        log.append(
+            "plan_committed",
+            {
+                "revision": revision,
+                "task_count": actual_count,
+                "task_hash": task_hash,
+                "preregistration": prereg,
+                "planner_rule": "plan_to_granularity_not_preregistered_count",
+            },
+        )
+
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        write_json(job_dir / "plan.json", plan)
+        write_state_snapshot(job_dir / "job.json", state)
+        write_handoff(job_dir, state_to_json(state), plan)
+
+    ready = ready_task_ids(plan)
+    print(f"Planned Socra job: {state.job_id}")
+    print(f"Project: {project}")
+    print(f"Job dir: {job_dir}")
+    print(f"Tasks: {actual_count}")
+    if expected_count is not None:
+        print(f"Preregistered reference count: {expected_count}")
+    print(f"Task hash: {task_hash}")
+    print(f"Ready tasks: {', '.join(ready[:8]) or 'none'}")
+    return 0
+
+
+def job_configure_creator_main(args: argparse.Namespace) -> int:
+    project = args.project.expanduser().resolve()
+    if args.job_id:
+        job_dir = job_root(project) / args.job_id
+    else:
+        found = find_latest_incomplete_job(project)
+        if not found:
+            raise SystemExit(f"No incomplete Socra jobs found under {job_root(project)}")
+        job_dir = found
+
+    config = {
+        "role": "creator",
+        "model_alias": args.model_alias,
+        "model": args.model,
+        "expected_served_model_id": args.expected_served_model_id or Path(str(args.model)).name,
+        "endpoint": args.endpoint,
+        "backend": args.backend,
+        "temperature": args.temperature,
+        "seed": args.seed,
+        "context_budget_tokens": args.context_budget_tokens,
+        "max_output_tokens": args.max_output_tokens,
+        "hosted_fallback": bool(args.hosted_fallback),
+        "local_first": not bool(args.hosted_fallback),
+        "notes": args.notes or "",
+    }
+
+    with JobLock(job_dir / ".lock"):
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        log = JobEventLog(job_dir / "events.jsonl", state.job_id or job_dir.name)
+        log.append("creator_configured", config)
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        write_json(job_dir / "plan.json", plan)
+        write_state_snapshot(job_dir / "job.json", state)
+        write_handoff(job_dir, state_to_json(state), plan)
+
+    print(f"Configured Creator for Socra job: {state.job_id}")
+    print(f"Model alias: {args.model_alias}")
+    print(f"Model: {args.model}")
+    print(f"Endpoint: {args.endpoint}")
+    print(f"Temperature: {args.temperature}")
+    print(f"Seed: {args.seed if args.seed is not None else 'provider default'}")
+    print(f"Context budget tokens: {args.context_budget_tokens}")
+    print(f"Hosted fallback: {bool(args.hosted_fallback)}")
+    return 0
+
+
+def git_capture(project: Path, args: list[str]) -> tuple[int, str, str]:
+    result = subprocess.run(
+        ["git", *args],
+        cwd=project,
+        text=True,
+        capture_output=True,
+        timeout=20,
+        check=False,
+    )
+    return result.returncode, result.stdout.strip(), result.stderr.strip()
+
+
+def target_repo_state(project: Path) -> dict[str, Any]:
+    state: dict[str, Any] = {"project": str(project)}
+    code, out, err = git_capture(project, ["rev-parse", "--show-toplevel"])
+    state["is_git_repo"] = code == 0
+    state["git_toplevel"] = out if code == 0 else None
+    if code != 0:
+        state["error"] = err or "not_a_git_repository"
+        return state
+    for key, git_args in {
+        "current_head": ["rev-parse", "HEAD"],
+        "current_branch": ["branch", "--show-current"],
+        "origin_dev_head": ["rev-parse", "--verify", "refs/remotes/origin/dev"],
+        "origin_head": ["rev-parse", "--verify", "refs/remotes/origin/HEAD"],
+    }.items():
+        code, out, err = git_capture(project, git_args)
+        state[key] = out if code == 0 else None
+        if code != 0 and key in {"current_head"}:
+            state[f"{key}_error"] = err
+    code, out, _ = git_capture(project, ["status", "--short"])
+    state["dirty"] = bool(out.strip()) if code == 0 else None
+    state["status_short"] = out.splitlines() if code == 0 and out else []
+    return state
+
+
+def default_dayjs_exam_pack_path() -> Path:
+    return Path(__file__).resolve().parents[2] / "docs" / "stress_tests" / "dayjs_exam_set_v1.json"
+
+
+def load_dayjs_exam_pack(path: Path) -> dict[str, Any]:
+    return json.loads(path.expanduser().resolve().read_text(encoding="utf-8"))
+
+
+def find_dayjs_candidate(pack: dict[str, Any], candidate_id: str) -> dict[str, Any]:
+    wanted = candidate_id.lower()
+    for candidate in pack.get("candidates") or []:
+        keys = {
+            str(candidate.get("exam_id") or "").lower(),
+            str(candidate.get("id") or "").lower(),
+        }
+        if wanted in keys:
+            return dict(candidate)
+    raise SystemExit(f"Unknown dayjs exam candidate: {candidate_id}")
+
+
+def job_exam_dayjs_main(args: argparse.Namespace) -> int:
+    project = args.project.expanduser().resolve()
+    pack_path = args.pack.expanduser().resolve() if args.pack else default_dayjs_exam_pack_path()
+    pack = load_dayjs_exam_pack(pack_path)
+    candidate = find_dayjs_candidate(pack, args.candidate)
+    exam_id = str(candidate.get("exam_id") or args.candidate).upper()
+    prediction = args.prediction or (pack.get("preregistered_predictions") or {}).get(exam_id) or "unspecified"
+    expected_checkout = str(candidate.get("upstream_fix_commit_parent") or "")
+    repo_state = target_repo_state(project)
+
+    if not repo_state.get("is_git_repo"):
+        raise SystemExit(f"Project is not a git repository: {project}")
+    if repo_state.get("current_head") != expected_checkout and not args.allow_checkout_mismatch:
+        raise SystemExit(
+            "dayjs exam checkout mismatch: "
+            f"HEAD={repo_state.get('current_head')} expected={expected_checkout}. "
+            "Checkout the pre-fix parent or pass --allow-checkout-mismatch to record a dry scaffold."
+        )
+
+    job_id = args.job_id or f"dayjs-exam-{exam_id.lower()}-{slugify(candidate.get('id') or '')}"
+    job_dir = job_root(project) / job_id
+    job_dir.mkdir(parents=True, exist_ok=False)
+
+    source_file = str((candidate.get("declared_files") or [""])[0])
+    hidden_test_file = str(candidate.get("hidden_test_file") or "")
+    focused_gate = str((pack.get("default_commands") or {}).get("focused_gate_template") or "npx jest <hidden_test_file> --coverage=false").replace(
+        "<hidden_test_file>", hidden_test_file
+    )
+    hidden_gate_extract = str((pack.get("protocol") or {}).get("hidden_gate_extraction_template") or "git show <upstream_fix_commit> -- <hidden_test_file> > hidden-gate.patch")
+    hidden_gate_extract = hidden_gate_extract.replace("<upstream_fix_commit>", str(candidate.get("upstream_fix_commit") or "")).replace(
+        "<hidden_test_file>", hidden_test_file
+    )
+    goal = f"dayjs exam {exam_id}: {candidate.get('task_spec', {}).get('title') or candidate.get('id')}"
+    task = {
+        "id": "exam-task-001",
+        "description": (candidate.get("task_spec") or {}).get("issue_summary") or goal,
+        "acceptance": [
+            "Fix the reported Day.js behavior without seeing the hidden regression patch.",
+            f"Focused gate passes after hidden gate is applied: {focused_gate}",
+            "Promoted source diff is graded for mechanism shape against upstream, not byte identity.",
+        ],
+        "risk_tier": 1,
+        "status": "pending",
+        "depends_on": [],
+        "declared_files": [source_file],
+        "attempt_count": 0,
+        "produced_artifacts": [],
+    }
+    plan = {"version": 1, "goal": goal, "tasks": [task]}
+
+    with JobLock(job_dir / ".lock"):
+        for folder in ["artifacts", "patches", "sandbox", "checkpoints"]:
+            (job_dir / folder).mkdir(parents=True, exist_ok=True)
+        exam_dir = job_dir / "artifacts" / "exam"
+        exam_dir.mkdir(parents=True, exist_ok=True)
+        visible_spec = {
+            "exam_id": exam_id,
+            "candidate_id": candidate.get("id"),
+            "difficulty": candidate.get("difficulty"),
+            "title": (candidate.get("task_spec") or {}).get("title"),
+            "issue_summary": (candidate.get("task_spec") or {}).get("issue_summary"),
+            "source_issue_urls": candidate.get("source_issue_urls") or [],
+            "creator_declared_files": [source_file],
+            "focused_gate_command": focused_gate,
+        }
+        hidden_manifest = {
+            "exam_id": exam_id,
+            "candidate_id": candidate.get("id"),
+            "upstream_fix_commit": candidate.get("upstream_fix_commit"),
+            "upstream_fix_commit_parent": expected_checkout,
+            "upstream_commit_url": candidate.get("upstream_commit_url"),
+            "hidden_test_file": hidden_test_file,
+            "hidden_gate_extraction_command": hidden_gate_extract,
+            "upstream_changed_files": candidate.get("declared_files") or [],
+            "source_changes": candidate.get("source_changes"),
+            "test_changes": candidate.get("test_changes"),
+        }
+        code, hidden_patch, hidden_patch_err = git_capture(project, ["show", str(candidate.get("upstream_fix_commit") or ""), "--", hidden_test_file])
+        if code != 0:
+            raise SystemExit(f"Failed to extract hidden gate patch: {hidden_patch_err}")
+        hidden_patch_path = exam_dir / "hidden-gate.patch"
+        hidden_patch_path.write_text(hidden_patch + ("\n" if hidden_patch and not hidden_patch.endswith("\n") else ""), encoding="utf-8")
+        hidden_manifest.update(
+            {
+                "hidden_gate_patch": "artifacts/exam/hidden-gate.patch",
+                "hidden_gate_patch_sha256": sha256_file(hidden_patch_path),
+            }
+        )
+        write_json(exam_dir / "visible-task-spec.json", visible_spec)
+        write_json(exam_dir / "hidden-gate-manifest.json", hidden_manifest)
+        write_json(exam_dir / "exam-pack-excerpt.json", {"pack": {"name": pack.get("name"), "version": pack.get("version")}, "candidate": candidate})
+        write_json(job_dir / "plan.json", plan)
+
+        log = JobEventLog(job_dir / "events.jsonl", job_id)
+        log.append("job_created", {"goal": goal, "project": str(project)})
+        log.append(
+            "exam_pack_loaded",
+            {
+                "exam": "dayjs",
+                "pack": str(pack_path),
+                "pack_sha256": sha256_file(pack_path),
+                "pack_name": pack.get("name"),
+                "pack_version": pack.get("version"),
+                "verified_on": pack.get("verified_on"),
+            },
+        )
+        log.append("exam_target_repo_state_recorded", repo_state)
+        log.append("exam_candidate_selected", {**hidden_manifest, "visible_task_spec": "artifacts/exam/visible-task-spec.json"})
+        log.append(
+            "exam_prediction_recorded",
+            {
+                "exam_id": exam_id,
+                "candidate_id": candidate.get("id"),
+                "prediction": prediction,
+                "prediction_source": "cli_override" if args.prediction else "exam_pack_preregistered_predictions",
+                "notes": args.prediction_notes or "",
+            },
+        )
+        log.append("task_added", task)
+        task_hash = canonical_task_hash([task])
+        log.append(
+            "plan_committed",
+            {
+                "revision": 1,
+                "task_count": 1,
+                "task_hash": task_hash,
+                "source": "dayjs_exam_pack",
+                "candidate": exam_id,
+            },
+        )
+        log.append("job_paused", {"reason": "dayjs_exam_scaffold_created_no_execution"})
+
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        materialized = materialize_plan_from_events(events, plan)
+        write_json(job_dir / "plan.json", materialized)
+        write_state_snapshot(job_dir / "job.json", state)
+        write_handoff(job_dir, state_to_json(state), materialized)
+
+    print(f"Created dayjs exam job: {job_id}")
+    print(f"Candidate: {exam_id} / {candidate.get('id')}")
+    print(f"Project HEAD: {repo_state.get('current_head')}")
+    print(f"Expected pre-fix checkout: {expected_checkout}")
+    print(f"Prediction: {prediction}")
+    print(f"Job dir: {job_dir}")
+    return 0
+
+
+def endpoint_health(endpoint: str) -> dict[str, Any]:
+    def parse_model_ids(text: str) -> list[str]:
+        try:
+            payload = json.loads(text)
+        except json.JSONDecodeError:
+            return []
+        ids: list[str] = []
+        for key in ("data", "models"):
+            rows = payload.get(key)
+            if not isinstance(rows, list):
+                continue
+            for row in rows:
+                if not isinstance(row, dict):
+                    continue
+                for field in ("id", "name", "model"):
+                    value = row.get(field)
+                    if isinstance(value, str) and value and value not in ids:
+                        ids.append(value)
+        return ids
+
+    url = endpoint.rstrip("/") + "/models"
+    try:
+        with urllib.request.urlopen(url, timeout=2) as response:
+            body = response.read().decode("utf-8", errors="replace")
+            return {"ok": True, "url": url, "status": response.status, "sample": body[:200], "model_ids": parse_model_ids(body)}
+    except Exception as exc:  # noqa: BLE001 - health checks should record all failures.
+        urllib_error = str(exc)
+    try:
+        result = subprocess.run(
+            ["curl", "-sS", "--max-time", "5", "-w", "\n__HTTP_STATUS__:%{http_code}", url],
+            text=True,
+            capture_output=True,
+            timeout=8,
+            check=False,
+        )
+        marker = "\n__HTTP_STATUS__:"
+        body, _, raw_status = result.stdout.rpartition(marker)
+        status = int(raw_status.strip() or "0")
+        if result.returncode == 0 and 200 <= status < 500:
+            return {"ok": True, "url": url, "status": status, "sample": body[:200], "model_ids": parse_model_ids(body), "transport": "curl_fallback"}
+        return {
+            "ok": False,
+            "url": url,
+            "error": result.stderr.strip() or f"curl_status_{status}",
+            "urllib_error": urllib_error,
+            "transport": "curl_fallback",
+        }
+    except Exception as exc:  # noqa: BLE001 - health checks should record all failures.
+        return {"ok": False, "url": url, "error": str(exc), "urllib_error": urllib_error}
+
+
+def inventory_declared_files(project: Path, task: dict[str, Any], artifact_dir: Path) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    for rel in task.get("declared_files", []):
+        path = project / str(rel)
+        row: dict[str, Any] = {
+            "path": str(rel),
+            "exists": path.exists(),
+        }
+        if path.exists() and path.is_file():
+            text = path.read_text(encoding="utf-8", errors="replace")
+            row.update(
+                {
+                    "bytes": path.stat().st_size,
+                    "lines": len(text.splitlines()),
+                    "sha256": sha256_file(path),
+                }
+            )
+            if str(rel) == "server.js":
+                row["api_routes"] = sorted(set(re.findall(r"app\.(?:get|post|put|delete|patch)\(['\"]([^'\"]+)", text)))
+                row["websocket_mentions"] = len(re.findall(r"WebSocket|broadcast|WebSocketServer", text))
+            elif str(rel) == "App.jsx":
+                row["state_hooks"] = len(re.findall(r"\buseState\s*\(", text))
+                row["effect_hooks"] = len(re.findall(r"\buseEffect\s*\(", text))
+                row["api_calls"] = sorted(set(re.findall(r"api(?:Get|Post|Delete|Put)?\(['\"]([^'\"]+)", text)))
+            elif str(rel) == "package.json":
+                try:
+                    package = json.loads(text)
+                except json.JSONDecodeError:
+                    package = {}
+                row["scripts"] = sorted((package.get("scripts") or {}).keys())
+                row["dependencies"] = sorted((package.get("dependencies") or {}).keys())
+                row["dev_dependencies"] = sorted((package.get("devDependencies") or {}).keys())
+            elif str(rel) == "mumpixdb-core.js":
+                row["class_mentions"] = sorted(set(re.findall(r"\bclass\s+([A-Za-z0-9_]+)", text)))
+                row["method_mentions"] = sorted(set(re.findall(r"\b(?:async\s+)?([A-Za-z0-9_]+)\s*\(", text)))[:80]
+        rows.append(row)
+
+    artifact_dir.mkdir(parents=True, exist_ok=True)
+    inventory_json = artifact_dir / "inventory.json"
+    inventory_md = artifact_dir / "inventory.md"
+    inventory_json.write_text(json.dumps({"task": task["id"], "declared_files": rows}, indent=2) + "\n", encoding="utf-8")
+    lines = [
+        f"# Task {task['id']} Inventory",
+        "",
+        f"Description: {task.get('description')}",
+        "",
+        "## Declared Files",
+        "",
+    ]
+    for row in rows:
+        lines.append(f"### `{row['path']}`")
+        lines.append("")
+        lines.append(f"- Exists: `{row['exists']}`")
+        if row.get("exists"):
+            lines.append(f"- Lines: `{row.get('lines')}`")
+            lines.append(f"- Bytes: `{row.get('bytes')}`")
+            lines.append(f"- SHA256: `{row.get('sha256')}`")
+        if row.get("api_routes"):
+            lines.append(f"- API routes: {', '.join(f'`{route}`' for route in row['api_routes'])}")
+        if row.get("scripts"):
+            lines.append(f"- Package scripts: {', '.join(f'`{script}`' for script in row['scripts'])}")
+        if row.get("state_hooks") is not None:
+            lines.append(f"- React state hooks: `{row.get('state_hooks')}`")
+            lines.append(f"- React effect hooks: `{row.get('effect_hooks')}`")
+        lines.append("")
+    inventory_md.write_text("\n".join(lines), encoding="utf-8")
+    return [
+        {"path": str(inventory_json.relative_to(artifact_dir.parent.parent)), "sha256": sha256_file(inventory_json)},
+        {"path": str(inventory_md.relative_to(artifact_dir.parent.parent)), "sha256": sha256_file(inventory_md)},
+    ]
+
+
+def normalize_declared_path(path: str) -> str:
+    value = str(path).replace("\\", "/").strip()
+    if not value or value.startswith("/") or value.startswith("../") or "/../" in value or value == "..":
+        raise ValueError(f"unsafe relative path: {path}")
+    return value
+
+
+def declared_file_set(task: dict[str, Any]) -> set[str]:
+    return {normalize_declared_path(str(path)) for path in task.get("declared_files", [])}
+
+
+def latest_passed_artifacts_by_path(job_dir: Path, plan: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    latest: dict[str, dict[str, Any]] = {}
+    tasks = plan.get("tasks") if isinstance(plan.get("tasks"), list) else []
+    for task in tasks:
+        if task.get("status") != "passed":
+            continue
+        task_id = str(task.get("id") or "")
+        for artifact in task.get("produced_artifacts") or []:
+            if not isinstance(artifact, dict):
+                continue
+            rel = artifact.get("path")
+            sandbox_path = artifact.get("sandbox_path")
+            if not isinstance(rel, str) or not isinstance(sandbox_path, str):
+                continue
+            absolute_path = job_dir / sandbox_path
+            if not absolute_path.exists() or not absolute_path.is_file():
+                continue
+            latest[normalize_declared_path(rel)] = {
+                "path": normalize_declared_path(rel),
+                "source": "passed_sandbox_artifact",
+                "source_task_id": task_id,
+                "sandbox_path": sandbox_path,
+                "absolute_path": str(absolute_path),
+                "sha256": artifact.get("sha256") or sha256_file(absolute_path),
+            }
+    return latest
+
+
+def read_declared_file_context(project: Path, task: dict[str, Any], effective_sources: dict[str, dict[str, Any]] | None = None) -> list[dict[str, Any]]:
+    files: list[dict[str, Any]] = []
+    for rel in task.get("declared_files", []):
+        rel_path = normalize_declared_path(str(rel))
+        source = (effective_sources or {}).get(rel_path)
+        path = Path(str(source["absolute_path"])).resolve() if source else (project / rel_path).resolve()
+        project_root = project.resolve()
+        sandbox_source = bool(source and source.get("source") == "passed_sandbox_artifact")
+        if not sandbox_source and project_root != path and project_root not in path.parents:
+            raise ValueError(f"declared file escapes project: {rel_path}")
+        if path.exists() and path.is_file():
+            content = path.read_text(encoding="utf-8", errors="replace")
+            files.append(
+                {
+                    "path": rel_path,
+                    "exists": True,
+                    "content": content,
+                    "sha256": sha256_text(content),
+                    "source": source.get("source") if source else "project_file",
+                    "source_task_id": source.get("source_task_id") if source else None,
+                    "sandbox_path": source.get("sandbox_path") if source else None,
+                    "absolute_path": str(path),
+                }
+            )
+        else:
+            files.append(
+                {
+                    "path": rel_path,
+                    "exists": False,
+                    "content": "",
+                    "sha256": None,
+                    "source": source.get("source") if source else "project_file",
+                    "source_task_id": source.get("source_task_id") if source else None,
+                    "sandbox_path": source.get("sandbox_path") if source else None,
+                    "absolute_path": str(path),
+                }
+            )
+    return files
+
+
+def strip_json_fences(text: str) -> str:
+    value = text.strip()
+    if value.startswith("```"):
+        value = re.sub(r"^```(?:[a-zA-Z0-9_-]+)?\s*", "", value)
+        value = re.sub(r"\s*```$", "", value)
+    return value.strip()
+
+
+def strip_json_trailing_commas(text: str) -> str:
+    return re.sub(r",(\s*[\]}])", r"\1", text)
+
+
+def parse_creator_json_with_repair(raw_text: str) -> tuple[dict[str, Any], dict[str, Any] | None]:
+    repair_types: list[str] = []
+    text = strip_json_fences(raw_text)
+    if text != raw_text.strip():
+        repair_types.append("strip_markdown_fence")
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as exc:
+        # Local reasoning models often add prose around JSON. Accept a single JSON
+        # object if it can be recovered unambiguously; otherwise attribute the
+        # failure to the Creator contract, not to the reviewer.
+        start = text.find("{")
+        end = text.rfind("}")
+        if start < 0 or end <= start:
+            raise ValueError(f"creator_output_malformed: {exc}") from exc
+        candidate = text[start : end + 1]
+        if candidate != text:
+            repair_types.append("extract_json_object")
+        try:
+            payload = json.loads(candidate)
+        except json.JSONDecodeError as inner:
+            stripped_commas = strip_json_trailing_commas(candidate)
+            if stripped_commas != candidate:
+                repair_types.append("strip_trailing_commas_before_json_closer")
+            try:
+                payload = json.loads(stripped_commas)
+            except json.JSONDecodeError:
+                raise ValueError(f"creator_output_malformed: {inner}") from inner
+    if not isinstance(payload, dict):
+        raise ValueError("creator_output_malformed: root must be an object")
+    files = payload.get("files")
+    edits = payload.get("edits")
+    if not isinstance(files, list) and not isinstance(edits, list):
+        raise ValueError("creator_output_malformed: files or edits must be a list")
+    if isinstance(files, list) and isinstance(edits, list):
+        raise ValueError("creator_output_malformed: files and edits are mutually exclusive")
+    if isinstance(files, list):
+        for index, file_payload in enumerate(files):
+            if not isinstance(file_payload, dict):
+                raise ValueError(f"creator_output_malformed: files[{index}] must be an object")
+            if not isinstance(file_payload.get("path"), str) or not file_payload.get("path"):
+                raise ValueError(f"creator_output_malformed: files[{index}].path must be a non-empty string")
+            content = file_payload.get("content")
+            content_lines = file_payload.get("content_lines")
+            if isinstance(content, str):
+                pass
+            elif isinstance(content_lines, list) and all(isinstance(line, str) for line in content_lines):
+                file_payload["content"] = "\n".join(content_lines)
+                file_payload.pop("content_lines", None)
+            else:
+                raise ValueError(f"creator_output_malformed: files[{index}] needs content string or content_lines string list")
+    if isinstance(edits, list):
+        for index, edit in enumerate(edits):
+            if not isinstance(edit, dict):
+                raise ValueError(f"creator_output_malformed: edits[{index}] must be an object")
+            if not isinstance(edit.get("path"), str) or not edit.get("path"):
+                raise ValueError(f"creator_output_malformed: edits[{index}].path must be a non-empty string")
+            if not isinstance(edit.get("before"), str) or not edit.get("before"):
+                raise ValueError(f"creator_output_malformed: edits[{index}].before must be a non-empty string")
+            if not isinstance(edit.get("after"), str):
+                raise ValueError(f"creator_output_malformed: edits[{index}].after must be a string")
+    notes = payload.get("notes")
+    if notes is not None and not isinstance(notes, str):
+        raise ValueError("creator_output_malformed: notes must be a string when present")
+    repair = None
+    if repair_types:
+        repair = {"types": repair_types, "applied": True}
+    return payload, repair
+
+
+def parse_creator_json(raw_text: str) -> dict[str, Any]:
+    payload, _repair = parse_creator_json_with_repair(raw_text)
+    return payload
+
+
+def coerce_single_file_creator_output(raw_text: str, allowed: set[str]) -> tuple[dict[str, Any], str] | None:
+    if len(allowed) != 1:
+        return None
+    rel = next(iter(allowed))
+    text = raw_text.strip()
+    if not text:
+        return None
+    if text.startswith("{") or text.startswith("["):
+        return None
+    # Recovery path for local models that follow the spirit of the request
+    # (full file content) but miss the JSON envelope. This is intentionally
+    # limited to one declared file so the path is not guessed.
+    if text.startswith("```"):
+        content = strip_json_fences(text)
+    else:
+        content = strip_reasoning_like_text(text)
+    if not content.strip():
+        return None
+    return {"files": [{"path": rel, "content": content}], "notes": "Recovered from single declared file raw code output."}, "single_file_raw_code"
+
+
+def strip_reasoning_like_text(text: str) -> str:
+    value = re.sub(r"(?is)<think>.*?</think>", "", text)
+    value = re.sub(r"(?is)<reasoning>.*?</reasoning>", "", value)
+    return value.strip()
+
+
+def select_creator_output_contract(
+    task: dict[str, Any], file_context: list[dict[str, Any]], reserved_output_tokens: int
+) -> dict[str, Any]:
+    declared = [str(path) for path in task.get("declared_files", [])]
+    if len(declared) != 1 or len(file_context) != 1 or not file_context[0].get("exists"):
+        return {"mode": "full_replacement", "reason": "task_shape_requires_file_payload"}
+    content = str(file_context[0].get("content") or "")
+    estimated_tokens = (len(content) + 3) // 4
+    effective_output_tokens = reserved_output_tokens if reserved_output_tokens > 0 else 4096
+    threshold = max(512, int(effective_output_tokens * ANCHORED_EDIT_OUTPUT_HEADROOM_RATIO))
+    if estimated_tokens < threshold:
+        return {
+            "mode": "full_replacement",
+            "reason": "replacement_estimate_fits_output_headroom",
+            "estimated_full_replacement_tokens": estimated_tokens,
+            "anchored_edit_threshold_tokens": threshold,
+        }
+    return {
+        "mode": "anchored_edits",
+        "reason": "replacement_estimate_exceeds_output_headroom",
+        "estimated_full_replacement_tokens": estimated_tokens,
+        "anchored_edit_threshold_tokens": threshold,
+        "max_edits": MAX_ANCHORED_EDITS,
+    }
+
+
+def anchored_edit_response_schema(allowed: set[str], max_edits: int = MAX_ANCHORED_EDITS) -> dict[str, Any]:
+    paths = sorted(normalize_declared_path(path) for path in allowed)
+    if not paths:
+        raise ValueError("anchored edit schema requires at least one declared path")
+    return {
+        "type": "object",
+        "properties": {
+            "edits": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": max_edits,
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string", "enum": paths},
+                        "before": {"type": "string", "minLength": 1},
+                        "after": {"type": "string"},
+                    },
+                    "required": ["path", "before", "after"],
+                    "additionalProperties": False,
+                },
+            },
+            "notes": {"type": "string"},
+        },
+        "required": ["edits"],
+        "additionalProperties": False,
+    }
+
+
+def materialize_anchored_edits(
+    payload: dict[str, Any], file_context: list[dict[str, Any]], allowed: set[str]
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    if "files" in payload:
+        raise ValueError("creator_output_contract_violation: anchored mode does not accept replacement files")
+    edits = payload.get("edits")
+    if not isinstance(edits, list) or not edits:
+        raise ValueError("creator_output_contract_violation: anchored mode requires at least one edit")
+    if len(edits) > MAX_ANCHORED_EDITS:
+        raise ValueError(f"creator_output_contract_violation: anchored mode allows at most {MAX_ANCHORED_EDITS} edits")
+    originals = {
+        normalize_declared_path(str(item.get("path") or "")): str(item.get("content") or "")
+        for item in file_context
+        if item.get("exists")
+    }
+    by_path: dict[str, list[tuple[int, int, str, str]]] = {}
+    metadata: list[dict[str, Any]] = []
+    for index, edit in enumerate(edits):
+        rel = normalize_declared_path(str(edit.get("path") or ""))
+        if rel not in allowed:
+            raise ValueError(f"creator_output_contract_violation: anchored edit path is not declared: {rel}")
+        if rel not in originals:
+            raise ValueError(f"creator_output_contract_violation: anchored edit target does not exist: {rel}")
+        before = str(edit.get("before") or "")
+        after = edit.get("after")
+        if not before or not isinstance(after, str):
+            raise ValueError(f"creator_output_contract_violation: anchored edit {index} needs before and after strings")
+        if before == after:
+            raise ValueError(f"creator_output_contract_violation: anchored edit {index} makes no change")
+        positions: list[int] = []
+        cursor = 0
+        while True:
+            position = originals[rel].find(before, cursor)
+            if position < 0:
+                break
+            positions.append(position)
+            cursor = position + 1
+        if len(positions) != 1:
+            raise ValueError(
+                f"creator_output_contract_violation: anchored edit {index} before text matched {len(positions)} times in {rel}; exactly one required"
+            )
+        start = positions[0]
+        end = start + len(before)
+        by_path.setdefault(rel, []).append((start, end, before, after))
+        metadata.append(
+            {
+                "index": index,
+                "path": rel,
+                "start": start,
+                "before_bytes": len(before.encode("utf-8")),
+                "after_bytes": len(after.encode("utf-8")),
+                "before_sha256": sha256_text(before),
+                "after_sha256": sha256_text(after),
+            }
+        )
+    files: list[dict[str, Any]] = []
+    for rel, path_edits in by_path.items():
+        ordered = sorted(path_edits, key=lambda item: item[0])
+        for previous, current in zip(ordered, ordered[1:]):
+            if current[0] < previous[1]:
+                raise ValueError(f"creator_output_contract_violation: anchored edits overlap in {rel}")
+        content = originals[rel]
+        for start, end, _before, after in reversed(ordered):
+            content = content[:start] + after + content[end:]
+        files.append({"path": rel, "content": content})
+    return {"files": files, "notes": payload.get("notes") or "Applied exact anchored edits."}, metadata
+
+
+def validate_creator_declared_files(payload: dict[str, Any], allowed: set[str]) -> list[str]:
+    violations: list[str] = []
+    seen: set[str] = set()
+    for file_payload in payload.get("files", []):
+        try:
+            rel = normalize_declared_path(str(file_payload.get("path")))
+        except ValueError:
+            violations.append(str(file_payload.get("path")))
+            continue
+        if rel not in allowed:
+            violations.append(rel)
+        if rel in seen:
+            violations.append(f"{rel} (duplicate)")
+        seen.add(rel)
+    return violations
+
+
+def backend_smoke_endpoint_paths(job_dir: Path | None) -> list[str]:
+    if job_dir is None:
+        return []
+    evidence_path = job_dir / "artifacts" / "tasks" / "task-029" / "backend-smoke-evidence.json"
+    if not evidence_path.exists():
+        return []
+    try:
+        evidence = json.loads(evidence_path.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001 - reviewer evidence is best-effort.
+        return []
+    paths: list[str] = []
+    for row in evidence.get("endpoints") or []:
+        if not isinstance(row, dict):
+            continue
+        url = row.get("url")
+        if not isinstance(url, str):
+            continue
+        parsed = urllib.parse.urlparse(url)
+        path = parsed.path
+        if path and path not in paths:
+            paths.append(path)
+    return paths
+
+
+def admin_data_client_endpoint_errors(written_text_by_path: dict[str, str], job_dir: Path | None) -> list[str]:
+    relevant_paths = {"src/adminDashboard/config.js", "src/adminDashboard/dataClient.js"}
+    if not any(path in written_text_by_path for path in relevant_paths):
+        return []
+    combined = "\n".join(written_text_by_path.values())
+    required = backend_smoke_endpoint_paths(job_dir)
+    missing = [path for path in required if path not in combined]
+    errors = [f"admin data client missing backend-smoke endpoint {path}" for path in missing]
+    forbidden = [
+        "/api/admin/health",
+        "/api/admin/status",
+        "/api/admin/genes",
+        "/api/admin/routes",
+        "/api/admin/benchmarks",
+        "/api/wal",
+        "/api/genes",
+        "/api/routes",
+        "/api/dashboard",
+    ]
+    for path in forbidden:
+        if path in combined:
+            errors.append(f"admin data client uses unverified endpoint prefix {path}")
+    return errors
+
+
+def previous_attempt_feedback(job_dir: Path, events: list[Any], task_id: str) -> list[dict[str, Any]]:
+    feedback: list[dict[str, Any]] = []
+    for event in events:
+        if event.payload.get("task_id") != task_id:
+            continue
+        if event.type == "task_failed":
+            item: dict[str, Any] = {
+                "event": event.type,
+                "seq": event.seq,
+                "error": event.payload.get("error"),
+                "message": event.payload.get("message"),
+                "reason": event.payload.get("reason"),
+                "failure_feedback": event.payload.get("failure_feedback"),
+                "review_errors": event.payload.get("review_errors"),
+                "attempt": event.payload.get("attempt"),
+            }
+            response_path = event.payload.get("response_path")
+            if isinstance(response_path, str):
+                path = job_dir / response_path
+                if path.exists():
+                    try:
+                        response = json.loads(path.read_text(encoding="utf-8"))
+                        content = str(response.get("content") or "")
+                        item["response_content_chars"] = len(content)
+                        item["response_head"] = content[:1200]
+                        item["response_tail"] = content[-2000:]
+                        item["finish_reason"] = response.get("finish_reason")
+                        item["reasoning_chars"] = len(str(response.get("reasoning_content") or ""))
+                    except Exception as exc:  # noqa: BLE001 - feedback is best-effort.
+                        item["response_read_error"] = str(exc)
+            feedback.append(item)
+        elif event.type in {"creator_output_repaired", "declared_file_violation"}:
+            feedback.append({"event": event.type, "seq": event.seq, **event.payload})
+    return feedback[-6:]
+
+
+def build_creator_messages(
+    job_dir: Path,
+    project: Path,
+    task: dict[str, Any],
+    file_context: list[dict[str, Any]] | None = None,
+    retry_feedback: list[dict[str, Any]] | None = None,
+    validated_behavior: dict[str, Any] | None = None,
+    output_contract: dict[str, Any] | None = None,
+) -> list[dict[str, str]]:
+    handoff_path = job_dir / "handoff.md"
+    handoff = handoff_path.read_text(encoding="utf-8", errors="replace") if handoff_path.exists() else ""
+    files = file_context if file_context is not None else read_declared_file_context(project, task)
+    declared = [str(path) for path in task.get("declared_files", [])]
+    conventions = project_conventions(project, job_dir)
+    js_rule = str(conventions.get("javascript_import_rule") or "Follow the existing project module syntax.")
+    contract = output_contract or select_creator_output_contract(task, files, 4096)
+    if contract.get("mode") == "anchored_edits":
+        system = "\n".join(
+            [
+                "You are the Socra Creator agent.",
+                f"Project JavaScript module rule: {js_rule}",
+                f"This task has exactly one large declared file: {declared[0]}.",
+                "Return only valid JSON. Do not return Markdown, prose outside JSON, a unified diff, or a full replacement file.",
+                "Output schema:",
+                '{"edits":[{"path":"relative/path","before":"small exact unique existing text","after":"replacement text"}],"notes":"short implementation notes"}',
+                "Each before value must match the existing file exactly once. Include only enough unchanged context to make it unique.",
+                f"Return at most {int(contract.get('max_edits') or MAX_ANCHORED_EDITS)} non-overlapping edits.",
+                "You may only edit the declared path. Do not use line numbers as anchors.",
+            ]
+        )
+    elif len(declared) == 1:
+        system = "\n".join(
+            [
+                "You are the Socra Creator agent.",
+                f"Project JavaScript module rule: {js_rule}",
+                f"This task has exactly one declared file: {declared[0]}.",
+                "Return only the complete replacement file content for that one file.",
+                "Do not return JSON, Markdown explanation, diffs, or patches.",
+                "A code fence is allowed but not required.",
+                "You may not create or modify any other path.",
+            ]
+        )
+    else:
+        system = "\n".join(
+            [
+                "You are the Socra Creator agent.",
+                f"Project JavaScript module rule: {js_rule}",
+                "Return only valid JSON. Do not use Markdown fences unless unavoidable.",
+                "Output schema:",
+                '{"files":[{"path":"relative/path","content_lines":["full replacement file content line 1","line 2"]}],"notes":"short implementation notes"}',
+                "Prefer content_lines for code so newlines do not need JSON escaping. content as one string is also accepted.",
+                "You may only write paths listed in the declared files. Any other path fails the task.",
+                "Return full file contents, not diffs or patches.",
+                "If a declared file does not need changes, omit it from files and explain in notes.",
+            ]
+        )
+    if validated_behavior:
+        system += "\nA validated PREFER behavior is included as advisory context. Derive a fresh fix for this task; do not copy a prior patch, and do not bypass any gate."
+    user = json.dumps(
+        {
+            "prompt_layout": CREATOR_PROMPT_LAYOUT,
+            "project_conventions": conventions,
+            "handoff_md": handoff,
+            "declared_file_contents": files,
+            "task": {
+                "id": task.get("id"),
+                "description": task.get("description"),
+                "acceptance": task.get("acceptance", []),
+                "risk_tier": task.get("risk_tier"),
+                "declared_files": task.get("declared_files", []),
+            },
+            "previous_attempt_feedback": retry_feedback or [],
+            "validated_behavior_preference": validated_behavior,
+            "output_contract": contract,
+        },
+        indent=2,
+    )
+    return [{"role": "system", "content": system}, {"role": "user", "content": user}]
+
+
+def call_creator_model(
+    creator: dict[str, Any],
+    messages: list[dict[str, str]],
+    *,
+    json_mode: bool = True,
+    response_schema: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    endpoint = str(creator.get("endpoint") or "http://127.0.0.1:11439/v1").rstrip("/")
+    url = endpoint + "/chat/completions"
+    max_tokens = int(creator.get("max_output_tokens", 4096))
+    payload = {
+        "model": creator.get("model_alias") or creator.get("model") or "Socra-14B-Coder",
+        "messages": messages,
+        "temperature": float(creator.get("temperature", 0.2)),
+        "max_tokens": max_tokens,
+    }
+    seed = creator.get("seed")
+    if seed is not None:
+        payload["seed"] = int(seed)
+    if response_schema is not None:
+        # llama.cpp's enforced schema transport is json_object + schema. Its
+        # json_schema variant is accepted by some builds without constraining
+        # output, so do not use acceptance of the request as proof of grammar use.
+        payload["response_format"] = {"type": "json_object", "schema": response_schema}
+        # llama.cpp applies response grammars to the answer channel. Keeping a
+        # reasoning channel active has historically allowed unconstrained output.
+        payload["chat_template_kwargs"] = {"enable_thinking": False}
+    elif json_mode:
+        payload["response_format"] = {"type": "json_object"}
+    timeout_seconds = int(creator.get("timeout_seconds") or max(240, min(1800, max_tokens // 8)))
+    request = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout_seconds) as response:
+            body = response.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"creator_http_{exc.code}: {body[:2000]}") from exc
+    data = json.loads(body)
+    choice = (data.get("choices") or [{}])[0]
+    message = choice.get("message") or {}
+    content = message.get("content")
+    if not isinstance(content, str):
+        content = ""
+    reasoning_content = message.get("reasoning_content")
+    if not isinstance(reasoning_content, str):
+        reasoning_content = ""
+    return {
+        "url": url,
+        "request_model": payload["model"],
+        "response_model": data.get("model"),
+        "content": content,
+        "reasoning_content": reasoning_content,
+        "finish_reason": choice.get("finish_reason"),
+        "usage": data.get("usage") if isinstance(data.get("usage"), dict) else {},
+        "request_max_tokens": max_tokens,
+        "request_temperature": payload["temperature"],
+        "request_seed": payload.get("seed"),
+        "json_mode": json_mode,
+        "structured_output_schema_sha256": (
+            recurrence_sha256_json(response_schema) if response_schema is not None else None
+        ),
+        "structured_output_mode": "json_schema" if response_schema is not None else ("json_object" if json_mode else None),
+        "structured_output_transport": (
+            "llama_cpp_response_format_json_object_schema" if response_schema is not None else None
+        ),
+        "thinking_disabled_for_schema": response_schema is not None,
+        "raw": data,
+    }
+
+
+def atomic_write_creator_sandbox(job_dir: Path, task_id: str, payload: dict[str, Any]) -> tuple[Path, list[dict[str, Any]]]:
+    sandbox_root = job_dir / "sandbox" / "tasks"
+    final_dir = sandbox_root / task_id
+    sandbox_root.mkdir(parents=True, exist_ok=True)
+    temp_parent = job_dir / "sandbox" / ".tmp"
+    temp_parent.mkdir(parents=True, exist_ok=True)
+    temp_dir = Path(tempfile.mkdtemp(prefix=f"{task_id}-", dir=temp_parent))
+    written: list[dict[str, Any]] = []
+    try:
+        for file_payload in payload.get("files", []):
+            rel = normalize_declared_path(str(file_payload["path"]))
+            target = temp_dir / rel
+            target.parent.mkdir(parents=True, exist_ok=True)
+            content = str(file_payload["content"])
+            target.write_text(content, encoding="utf-8")
+            written.append(
+                {
+                    "path": rel,
+                    "absolute_path": str(target),
+                    "sha256": sha256_text(content),
+                    "bytes": len(content.encode("utf-8")),
+                    "lines": len(content.splitlines()),
+                }
+            )
+        if final_dir.exists():
+            shutil.rmtree(final_dir)
+        temp_dir.rename(final_dir)
+        for row in written:
+            row["absolute_path"] = str(final_dir / str(row["path"]))
+        return final_dir, written
+    except Exception:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+        raise
+
+
+def preserve_existing_final_newlines(
+    payload: dict[str, Any], file_context: list[dict[str, Any]]
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    originals = {
+        normalize_declared_path(str(item.get("path") or "")): str(item.get("content") or "")
+        for item in file_context
+        if item.get("exists") and str(item.get("content") or "")
+    }
+    normalized_files: list[dict[str, Any]] = []
+    changes: list[dict[str, Any]] = []
+    for file_payload in payload.get("files", []):
+        row = dict(file_payload)
+        rel = normalize_declared_path(str(row.get("path") or ""))
+        content = str(row.get("content") or "")
+        original = originals.get(rel)
+        if original is not None:
+            original_has_newline = original.endswith("\n")
+            generated_has_newline = content.endswith(("\n", "\r"))
+            if original_has_newline and not generated_has_newline:
+                content += "\n"
+            elif not original_has_newline and generated_has_newline:
+                content = content.rstrip("\r\n")
+            if content != str(row.get("content") or ""):
+                changes.append(
+                    {
+                        "path": rel,
+                        "original_has_final_newline": original_has_newline,
+                        "generated_had_final_newline": generated_has_newline,
+                        "normalized_has_final_newline": content.endswith("\n"),
+                        "policy": "preserve_existing_file_final_newline_state",
+                    }
+                )
+        row["content"] = content
+        normalized_files.append(row)
+    return {**payload, "files": normalized_files}, changes
+
+
+def js_syntax_check(project: Path, source_path: Path, rel_path: str) -> tuple[str, str]:
+    suffix = Path(rel_path).suffix.lower()
+    script = f"""
+const fs = require("fs");
+const source = fs.readFileSync({json.dumps(str(source_path))}, "utf8");
+const project = {json.dumps(str(project))};
+const relPath = {json.dumps(rel_path)};
+const suffix = {json.dumps(suffix)};
+function resolveFromProject(name) {{
+  try {{ return require.resolve(name, {{ paths: [project] }}); }} catch (_) {{ return null; }}
+}}
+const babelPath = resolveFromProject("@babel/parser");
+const typescriptPath = resolveFromProject("typescript");
+try {{
+  if (babelPath) {{
+    const parser = require(babelPath);
+    parser.parse(source, {{
+      sourceType: "module",
+      errorRecovery: false,
+      plugins: ["jsx", "typescript", "classProperties", "objectRestSpread", "dynamicImport"]
+    }});
+  }} else if (typescriptPath) {{
+    const ts = require(typescriptPath);
+    const kind = suffix === ".tsx" ? ts.ScriptKind.TSX
+      : suffix === ".jsx" ? ts.ScriptKind.JSX
+      : suffix === ".ts" ? ts.ScriptKind.TS
+      : ts.ScriptKind.JS;
+    const parsed = ts.createSourceFile(relPath, source, ts.ScriptTarget.Latest, true, kind);
+    if (parsed.parseDiagnostics && parsed.parseDiagnostics.length) {{
+      const message = parsed.parseDiagnostics
+        .map((item) => ts.flattenDiagnosticMessageText(item.messageText, "\\n"))
+        .join("; ");
+      throw new Error(message);
+    }}
+  }} else if (suffix === ".js") {{
+    process.stderr.write("CHECKER_UNAVAILABLE:node --check fallback required");
+    process.exit(2);
+  }} else {{
+    process.stderr.write("CHECKER_UNAVAILABLE:no @babel/parser or typescript resolvable from target project");
+    process.exit(2);
+  }}
+}} catch (error) {{
+  console.error(String(error && error.message || error));
+  process.exit(1);
+}}
+"""
+    result = subprocess.run(
+        ["node", "-e", script],
+        cwd=project,
+        text=True,
+        capture_output=True,
+        timeout=30,
+        check=False,
+    )
+    if result.returncode == 0:
+        return "passed", "ok"
+    if result.returncode == 2 and "CHECKER_UNAVAILABLE:" in (result.stderr or ""):
+        if suffix == ".js":
+            fallback = subprocess.run(
+                ["node", "--check", str(source_path)],
+                cwd=project,
+                text=True,
+                capture_output=True,
+                timeout=30,
+                check=False,
+            )
+            if fallback.returncode == 0:
+                return "passed", "ok_node_check"
+            detail = (fallback.stderr or fallback.stdout or "unknown parse error").strip()
+            return "failed", f"{rel_path} syntax check failed: {detail}"
+        detail = (result.stderr or result.stdout).strip().replace("CHECKER_UNAVAILABLE:", "")
+        return "unavailable", f"{rel_path} syntax checker unavailable: {detail}"
+    detail = (result.stderr or result.stdout or "unknown parse error").strip()
+    return "failed", f"{rel_path} syntax check failed: {detail}"
+
+
+def regression_surface_tokens(source: str) -> list[str]:
+    tokens: set[str] = set()
+    for match in re.findall(r"app\.(?:get|post|put|delete|patch)\(\s*['\"]([^'\"]+)['\"]", source):
+        tokens.add(match)
+    for match in re.findall(r"\b(?:function|class)\s+([A-Za-z_$][A-Za-z0-9_$]*)", source):
+        tokens.add(match)
+    for match in re.findall(r"\b(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=", source):
+        tokens.add(match)
+    keywords = ("admin", "artifact", "safe", "local", "root", "wal", "event", "gene", "route", "benchmark", "health", "normalize", "summary", "source")
+    return sorted(token for token in tokens if any(key in token.lower() for key in keywords))
+
+
+def review_creator_sandbox(
+    project: Path,
+    task: dict[str, Any],
+    written: list[dict[str, Any]],
+    output_mode: str,
+    file_context: list[dict[str, Any]] | None = None,
+    job_dir: Path | None = None,
+) -> tuple[bool, list[str], str, list[dict[str, Any]], list[str]]:
+    errors: list[str] = []
+    infrastructure_errors: list[str] = []
+    if not isinstance(written, list):
+        return False, ["written artifact list missing"], "contract", [], []
+    syntax_checked = False
+    written_text = ""
+    written_text_by_path: dict[str, str] = {}
+    for row in written:
+        if not row.get("path") or not row.get("sha256"):
+            errors.append(f"incomplete artifact metadata for {row!r}")
+        path = str(row.get("path") or "")
+        if path.endswith((".jsx", ".tsx", ".js", ".ts")):
+            sandbox_path = row.get("absolute_path")
+            if sandbox_path:
+                try:
+                    content = Path(str(sandbox_path)).read_text(encoding="utf-8", errors="replace").lstrip()
+                except OSError:
+                    content = ""
+                written_text += "\n" + content
+                written_text_by_path[path] = content
+                if content.startswith('{"files"') or content.startswith("{'files'"):
+                    errors.append(f"{path} looks like an unparsed Creator JSON envelope")
+                if sandbox_path and output_mode in {"single_file_raw_code", "anchored_edit_json"}:
+                    syntax_status, detail = js_syntax_check(project, Path(str(sandbox_path)), path)
+                    syntax_checked = True
+                    if syntax_status == "failed":
+                        errors.append(detail)
+                    elif syntax_status == "unavailable":
+                        infrastructure_errors.append(detail)
+    if not written:
+        errors.append("creator returned no file changes")
+    errors.extend(admin_data_client_endpoint_errors(written_text_by_path, job_dir))
+    regression_checks: list[dict[str, Any]] = []
+    for item in file_context or []:
+        if item.get("source") != "passed_sandbox_artifact":
+            continue
+        prior_path = item.get("sandbox_path")
+        if not isinstance(prior_path, str):
+            continue
+        prior_abs = Path(str(item.get("absolute_path") or ""))
+        if not prior_abs.exists() and prior_path:
+            # file_context uses absolute_path internally but request artifacts only
+            # expose sandbox_path. Keep this fallback defensive for older entries.
+            prior_abs = Path(prior_path)
+        if not prior_abs.exists():
+            continue
+        prior_text = prior_abs.read_text(encoding="utf-8", errors="replace")
+        tokens = regression_surface_tokens(prior_text)
+        item_path = str(item.get("path") or "")
+        if item_path not in written_text_by_path:
+            check = {
+                "path": item.get("path"),
+                "source_task_id": item.get("source_task_id"),
+                "token_count": len(tokens),
+                "missing": [],
+                "ok": True,
+                "status": "omitted_declared_file_treated_as_unchanged",
+            }
+            regression_checks.append(check)
+            continue
+        missing = [token for token in tokens if token not in written_text_by_path[item_path]]
+        check = {
+            "path": item.get("path"),
+            "source_task_id": item.get("source_task_id"),
+            "token_count": len(tokens),
+            "missing": missing[:25],
+            "ok": not missing,
+            "status": "rewritten_file_checked",
+        }
+        regression_checks.append(check)
+        if missing:
+            errors.append(f"{item.get('path')} regression surface missing {len(missing)} prior tokens from {item.get('source_task_id')}: {', '.join(missing[:8])}")
+    if syntax_checked:
+        review_level = "static_syntax"
+    else:
+        review_level = "contract"
+    return not errors and not infrastructure_errors, errors, review_level, regression_checks, infrastructure_errors
+
+
+def task_review_metadata(events: list[Any]) -> dict[str, dict[str, Any]]:
+    reviews: dict[str, dict[str, Any]] = {}
+    for event in events:
+        payload = event.payload
+        task_id = str(payload.get("task_id") or "")
+        if not task_id:
+            continue
+        if event.type == "review_completed":
+            reviews.setdefault(task_id, {}).update(
+                {
+                    "review_ok": bool(payload.get("ok")),
+                    "review_level": payload.get("review_level") or "contract",
+                    "output_mode": payload.get("output_mode"),
+                    "review_errors": payload.get("errors") or [],
+                    "review_event_seq": event.seq,
+                    "review_event_id": event.event_id,
+                }
+            )
+        elif event.type == "task_passed":
+            reviews.setdefault(task_id, {}).update(
+                {
+                    "task_passed": True,
+                    "review_level": payload.get("review_level") or reviews.get(task_id, {}).get("review_level"),
+                    "output_mode": payload.get("output_mode") or reviews.get(task_id, {}).get("output_mode"),
+                    "acceptance_review": payload.get("acceptance_review") or reviews.get(task_id, {}).get("acceptance_review") or "unspecified",
+                }
+            )
+        elif event.type == "task_review_reclassified":
+            reviews.setdefault(task_id, {}).update(
+                {
+                    "review_level": payload.get("review_level"),
+                    "output_mode": payload.get("output_mode"),
+                    "acceptance_review": payload.get("acceptance_review"),
+                    "reclassified": True,
+                    "reclassification_reason": payload.get("reason"),
+                }
+            )
+        elif event.type == "task_reverified":
+            criteria = payload.get("criteria") if isinstance(payload.get("criteria"), list) else []
+            all_passed = bool(criteria) and all(str(item.get("status")) == "pass" for item in criteria if isinstance(item, dict))
+            reviews.setdefault(task_id, {}).update(
+                {
+                    "review_level": payload.get("review_level") or ("acceptance_reverified" if all_passed else "acceptance_partial"),
+                    "acceptance_review": payload.get("acceptance_review") or ("full" if all_passed else "partial"),
+                    "reverified": True,
+                    "reverification_all_passed": all_passed,
+                    "reverification_event": event.event_id,
+                    "reverification_notes": payload.get("notes"),
+                }
+            )
+    return reviews
+
+
+def reviewer_audit_requirements(events: list[Any]) -> dict[str, dict[str, Any]]:
+    requirements: dict[str, dict[str, Any]] = {}
+    for event in events:
+        if event.type != "reviewer_path_audit":
+            continue
+        for item in event.payload.get("affected_events") or []:
+            if not isinstance(item, dict):
+                continue
+            task_id = str(item.get("task_id") or "")
+            if not task_id:
+                continue
+            effect = str(item.get("effect") or "")
+            if "false_review_failed" in effect:
+                continue
+            requirements[task_id] = {
+                "audit_event_seq": event.seq,
+                "audit_event_id": event.event_id,
+                "affected_review_seq": item.get("seq"),
+                "effect": effect,
+                "reason": "reviewer audit requires explicit reverification before promotion-grade milestone claims",
+            }
+    return requirements
+
+
+def tasks_requiring_milestone_reverification(events: list[Any], task_ids: list[str]) -> list[dict[str, Any]]:
+    reviews = task_review_metadata(events)
+    audit_requirements = reviewer_audit_requirements(events)
+    needs: list[dict[str, Any]] = []
+    for task_id in task_ids:
+        meta = reviews.get(task_id, {})
+        review_level = str(meta.get("review_level") or "")
+        acceptance_review = str(meta.get("acceptance_review") or "")
+        audit_requirement = audit_requirements.get(task_id)
+        if audit_requirement and not meta.get("reverification_all_passed"):
+            needs.append(
+                {
+                    "task_id": task_id,
+                    "review_level": review_level or "unknown",
+                    "acceptance_review": acceptance_review or "unknown",
+                    "reason": audit_requirement["reason"],
+                    "audit_event_seq": audit_requirement.get("audit_event_seq"),
+                    "affected_review_seq": audit_requirement.get("affected_review_seq"),
+                    "effect": audit_requirement.get("effect"),
+                }
+            )
+            continue
+        if meta.get("reverification_all_passed"):
+            continue
+        if acceptance_review == "partial_smoke_only" or review_level.endswith("_smoke") or review_level == "static_syntax_smoke":
+            needs.append(
+                {
+                    "task_id": task_id,
+                    "review_level": review_level or "unknown",
+                    "acceptance_review": acceptance_review or "unknown",
+                    "reason": "partial smoke task must be explicitly reverified by milestone runner before promotion claims",
+                }
+            )
+    return needs
+
+
+def validate_reverification_evidence(task: dict[str, Any], evidence: dict[str, Any]) -> tuple[list[dict[str, Any]], list[str], bool]:
+    acceptance = [str(item) for item in task.get("acceptance", [])]
+    criteria = evidence.get("criteria")
+    errors: list[str] = []
+    if not isinstance(criteria, list):
+        return [], ["evidence.criteria must be a list"], False
+    normalized: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    allowed_status = {"pass", "fail", "not_checked"}
+    for index, item in enumerate(criteria):
+        if not isinstance(item, dict):
+            errors.append(f"criteria[{index}] must be an object")
+            continue
+        criterion = str(item.get("criterion") or "")
+        status = str(item.get("status") or "")
+        if criterion not in acceptance:
+            errors.append(f"criteria[{index}] does not match task acceptance: {criterion}")
+        if criterion in seen:
+            errors.append(f"duplicate criterion: {criterion}")
+        if status not in allowed_status:
+            errors.append(f"invalid status for {criterion}: {status}")
+        seen.add(criterion)
+        normalized.append(
+            {
+                "criterion": criterion,
+                "status": status,
+                "evidence_kind": str(item.get("evidence_kind") or ""),
+                "details": item.get("details") if item.get("details") is not None else "",
+                "artifacts": item.get("artifacts") if isinstance(item.get("artifacts"), list) else [],
+            }
+        )
+    missing = [criterion for criterion in acceptance if criterion not in seen]
+    for criterion in missing:
+        errors.append(f"missing criterion evidence: {criterion}")
+    all_passed = bool(normalized) and not errors and all(item["status"] == "pass" for item in normalized)
+    return normalized, errors, all_passed
+
+
+def overlay_passed_task_artifacts(project: Path, job_dir: Path, plan: dict[str, Any], target_dir: Path) -> list[dict[str, Any]]:
+    shutil.copytree(project, target_dir, ignore=copytree_ignore_for_runner)
+    tasks = plan.get("tasks") if isinstance(plan.get("tasks"), list) else []
+    overlays: list[dict[str, Any]] = []
+    for task in tasks:
+        if task.get("status") != "passed":
+            continue
+        task_id = str(task.get("id"))
+        sandbox_dir = job_dir / "sandbox" / "tasks" / task_id
+        if not sandbox_dir.exists():
+            continue
+        for src in sandbox_dir.rglob("*"):
+            if not src.is_file():
+                continue
+            rel = src.relative_to(sandbox_dir)
+            dest = target_dir / rel
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, dest)
+            overlays.append({"task_id": task_id, "path": str(rel), "sha256": sha256_file(dest)})
+    return overlays
+
+
+def link_existing_dependency_trees(project: Path, overlay_dir: Path) -> list[str]:
+    """Reuse installed dependencies without copying them or invoking an installer."""
+    linked: list[str] = []
+    for root, dirs, _files in os.walk(project, topdown=True):
+        root_path = Path(root)
+        dirs[:] = [name for name in dirs if name not in {".git", ".socra"}]
+        if "node_modules" not in dirs:
+            continue
+        source = root_path / "node_modules"
+        rel = source.relative_to(project)
+        target = overlay_dir / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if not target.exists() and not target.is_symlink():
+            target.symlink_to(source, target_is_directory=True)
+            linked.append(rel.as_posix())
+        dirs.remove("node_modules")
+    return linked
+
+
+RUNNER_INFRASTRUCTURE_PATTERNS = (
+    "command not found",
+    "err_pnpm_ignored_builds",
+    "err_pnpm_aborted_remove_modules_dir_no_tty",
+    "err_pnpm_outdated_lockfile",
+    "err_pnpm_lockfile_config_mismatch",
+    "could not determine executable to run",
+    "jest: not found",
+    "vitest: not found",
+    "mocha: not found",
+    "tsx: not found",
+)
+RUNNER_STARTED_INFRASTRUCTURE_PATTERNS = ("listen eperm: operation not permitted",)
+
+
+def classify_gate_process(returncode: int, stdout: str, stderr: str) -> tuple[str, bool, str | None]:
+    if returncode == 0:
+        return "passed", True, None
+    combined = f"{stdout}\n{stderr}".lower()
+    if returncode in {126, 127} or any(pattern in combined for pattern in RUNNER_INFRASTRUCTURE_PATTERNS):
+        return "infrastructure_unavailable", False, "runner_infrastructure_unavailable"
+    if any(pattern in combined for pattern in RUNNER_STARTED_INFRASTRUCTURE_PATTERNS):
+        return "infrastructure_unavailable", True, "runner_infrastructure_unavailable"
+    return "test_failed", True, "test_command_failed"
+
+
+def infer_milestone_review_level(command: str) -> tuple[str, bool]:
+    text = command.lower()
+    if "preview" in text or "http.server" in text or "playwright" in text:
+        return "preview_gate", False
+    if "npm run build" in text or "vite" in text and "build" in text or "xcodebuild" in text:
+        return "build_gate", False
+    return "static_gate_only", False
+
+
+def dependency_manifest(project_dir: Path) -> dict[str, Any]:
+    payload: dict[str, Any] = {}
+    for name in ["package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb"]:
+        path = project_dir / name
+        if path.exists() and path.is_file():
+            payload[name] = {"sha256": sha256_file(path), "bytes": path.stat().st_size}
+    return payload
+
+
+def prepare_runner_dependencies(overlay_dir: Path, mode: str, timeout_seconds: int) -> tuple[dict[str, Any], int]:
+    if mode == "none":
+        return {"mode": mode, "skipped": True}, 0
+    if mode == "npm-ci":
+        command = "npm ci"
+    elif mode == "npm-install":
+        command = "npm install"
+    else:
+        return {"mode": mode, "error": f"unknown dependency preparation mode: {mode}"}, 2
+    before = dependency_manifest(overlay_dir)
+    result = subprocess.run(
+        command,
+        cwd=overlay_dir,
+        shell=True,
+        text=True,
+        capture_output=True,
+        timeout=timeout_seconds,
+        check=False,
+    )
+    after = dependency_manifest(overlay_dir)
+    return (
+        {
+            "mode": mode,
+            "command": command,
+            "returncode": result.returncode,
+            "stdout_tail": (result.stdout or "")[-4000:],
+            "stderr_tail": (result.stderr or "")[-4000:],
+            "manifest_before": before,
+            "manifest_after": after,
+            "node_modules_exists": (overlay_dir / "node_modules").exists(),
+        },
+        0 if result.returncode == 0 else 2,
+    )
+
+
+def parse_npm_vulnerability_counts(text: str) -> dict[str, int]:
+    counts = {"low": 0, "moderate": 0, "high": 0, "critical": 0}
+    match = re.search(r"(\d+)\s+vulnerabilities?\s*\(([^)]*)\)", text, flags=re.IGNORECASE)
+    if not match:
+        return counts
+    for count, level in re.findall(r"(\d+)\s+(low|moderate|high|critical)", match.group(2), flags=re.IGNORECASE):
+        counts[level.lower()] = int(count)
+    return counts
+
+
+def active_vulnerability_exception_counts(events: list[Any]) -> dict[str, int]:
+    counts = {"high": 0, "critical": 0}
+    for event in events:
+        if event.type != "vulnerability_exception_recorded":
+            continue
+        payload = event.payload
+        if payload.get("active") is False:
+            continue
+        severity = str(payload.get("severity") or "").lower()
+        if severity in counts:
+            counts[severity] += 1
+    return counts
+
+
+def dependency_vulnerability_policy(dep_payload: dict[str, Any], promotion_grade: bool, exception_counts: dict[str, int] | None = None) -> dict[str, Any]:
+    text = "\n".join(str(dep_payload.get(key) or "") for key in ("stdout_tail", "stderr_tail"))
+    counts = parse_npm_vulnerability_counts(text)
+    exceptions = exception_counts or {}
+    unexcepted_high = max(0, int(counts.get("high", 0)) - int(exceptions.get("high", 0)))
+    unexcepted_critical = max(0, int(counts.get("critical", 0)) - int(exceptions.get("critical", 0)))
+    blocking = unexcepted_high + unexcepted_critical
+    return {
+        "policy": "verification_records_all_vulns_promotion_blocks_high_critical",
+        "counts": counts,
+        "active_exception_counts": {"high": int(exceptions.get("high", 0)), "critical": int(exceptions.get("critical", 0))},
+        "unexcepted_blocking_counts": {"high": unexcepted_high, "critical": unexcepted_critical},
+        "blocking_vulnerabilities": blocking,
+        "promotion_grade": promotion_grade,
+        "blocks_promotion": bool(promotion_grade and blocking > 0),
+    }
+
+
+def find_job_dir(project: Path, job_id: str | None) -> Path:
+    if job_id:
+        return job_root(project) / job_id
+    found = find_latest_incomplete_job(project)
+    if not found:
+        raise SystemExit(f"No incomplete Socra jobs found under {job_root(project)}")
+    return found
+
+
+def human_promotion_review(events: list[Any], task_id: str) -> dict[str, Any] | None:
+    for event in reversed(events):
+        if event.type != "promotion_human_authorized":
+            continue
+        payload = event.payload
+        if payload.get("task_id") != task_id:
+            continue
+        if payload.get("human_source_promotion_authorized") is True:
+            return {
+                "event_seq": event.seq,
+                "reviewer_name": payload.get("authorizer_name"),
+                "review": payload.get("authorization"),
+                "sha256": payload.get("authorization_sha256"),
+                "event_type": event.type,
+                "bundle_sha256": payload.get("bundle_sha256"),
+                "dry_run_diff_sha256": payload.get("dry_run_diff_sha256"),
+                "rollback_manifest_sha256": payload.get("rollback_manifest_sha256"),
+                "presentation_event_seq": payload.get("presentation_event_seq"),
+            }
+    for event in reversed(events):
+        if event.type != "promotion_human_diff_reviewed":
+            continue
+        payload = event.payload
+        if payload.get("task_id") != task_id:
+            continue
+        if payload.get("human_source_promotion_approval_granted") is True:
+            return {
+                "event_seq": event.seq,
+                "reviewer_name": payload.get("reviewer_name"),
+                "review": payload.get("review"),
+                "sha256": payload.get("sha256"),
+                "event_type": event.type,
+                "bundle_sha256": payload.get("bundle_sha256"),
+                "legacy_compatibility": True,
+            }
+    return None
+
+
+def latest_diff_presentation(events: list[Any], task_id: str, bundle_sha256: str, dry_run_diff_sha256: str) -> dict[str, Any] | None:
+    for event in reversed(events):
+        if event.type != "promotion_diff_presented":
+            continue
+        payload = event.payload
+        if payload.get("task_id") != task_id:
+            continue
+        if payload.get("bundle_sha256") != bundle_sha256:
+            continue
+        if payload.get("dry_run_diff_sha256") != dry_run_diff_sha256:
+            continue
+        if payload.get("displayed_hash_matched_approval_target") is True:
+            return {
+                "event_seq": event.seq,
+                "presentation": payload,
+            }
+    return None
+
+
+def matching_diff_rejection(events: list[Any], task_id: str, bundle_sha256: str, dry_run_diff_sha256: str) -> dict[str, Any] | None:
+    for event in reversed(events):
+        if event.type != "promotion_human_rejected":
+            continue
+        payload = event.payload
+        if payload.get("task_id") != task_id:
+            continue
+        if payload.get("bundle_sha256") != bundle_sha256:
+            continue
+        if payload.get("dry_run_diff_sha256") != dry_run_diff_sha256:
+            continue
+        return {"event_seq": event.seq, "rejection": payload}
+    return None
+
+
+def ensure_promotion_artifacts(project: Path, job_dir: Path, task_id: str) -> dict[str, Any]:
+    artifact_dir = job_dir / "artifacts" / "tasks" / task_id
+    dry_run_diff = artifact_dir / "dry-run-diff.md"
+    patch_bundle = artifact_dir / "promotion-patch-bundle.json"
+    rollback_manifest = artifact_dir / "rollback-manifest.json"
+    if dry_run_diff.exists() and patch_bundle.exists() and rollback_manifest.exists():
+        return {"generated": False}
+
+    sandbox_dir = job_dir / "sandbox" / "tasks" / task_id
+    if not sandbox_dir.exists():
+        return {"generated": False, "error": "promotion_sandbox_artifacts_missing"}
+
+    artifact_dir.mkdir(parents=True, exist_ok=True)
+    changed_files: list[dict[str, Any]] = []
+    rollback_entries: list[dict[str, Any]] = []
+    diff_sections: list[str] = [f"# Promotion Diff: {task_id}", ""]
+
+    for src in sorted(sandbox_dir.rglob("*")):
+        if not src.is_file():
+            continue
+        rel = src.relative_to(sandbox_dir).as_posix()
+        target = project / rel
+        old_exists = target.exists()
+        old_text = target.read_text(encoding="utf-8", errors="replace") if old_exists and target.is_file() else ""
+        new_text = src.read_text(encoding="utf-8", errors="replace")
+        old_sha = sha256_text(old_text) if old_exists else None
+        new_sha = sha256_text(new_text)
+        if old_exists and old_sha == new_sha:
+            continue
+        sandbox_path = src.relative_to(job_dir).as_posix()
+        changed_files.append(
+            {
+                "path": rel,
+                "source_task_id": task_id,
+                "sandbox_path": sandbox_path,
+                "old_exists": old_exists,
+                "old_sha256": old_sha,
+                "new_sha256": new_sha,
+            }
+        )
+        rollback_entries.append(
+            {
+                "path": rel,
+                "old_exists": old_exists,
+                "old_sha256": old_sha,
+            }
+        )
+        old_lines = old_text.splitlines()
+        new_lines = new_text.splitlines()
+        diff = "\n".join(
+            difflib.unified_diff(
+                old_lines,
+                new_lines,
+                fromfile=f"a/{rel}",
+                tofile=f"b/{rel}",
+                lineterm="",
+            )
+        )
+        diff_sections.extend([f"## {rel}", "", "```diff", diff or "(no textual diff)", "```", ""])
+
+    if not changed_files:
+        diff_sections.extend(["No changed files in sandbox artifacts.", ""])
+
+    dry_run_diff.write_text("\n".join(diff_sections), encoding="utf-8")
+    bundle = {
+        "schema_version": 1,
+        "task_id": task_id,
+        "source": "sandbox_task_artifacts",
+        "changed_files": changed_files,
+    }
+    patch_bundle.write_text(json.dumps(bundle, indent=2) + "\n", encoding="utf-8")
+    rollback = {
+        "schema_version": 1,
+        "task_id": task_id,
+        "source": "project_preimage_manifest",
+        "entries": rollback_entries,
+    }
+    rollback_manifest.write_text(json.dumps(rollback, indent=2) + "\n", encoding="utf-8")
+    return {
+        "generated": True,
+        "changed_file_count": len(changed_files),
+        "dry_run_diff": str(dry_run_diff.relative_to(job_dir)),
+        "patch_bundle": str(patch_bundle.relative_to(job_dir)),
+        "rollback_manifest": str(rollback_manifest.relative_to(job_dir)),
+    }
+
+
+def promotion_artifact_hashes(job_dir: Path, task_id: str) -> dict[str, Any]:
+    artifact_dir = job_dir / "artifacts" / "tasks" / task_id
+    dry_run_diff = artifact_dir / "dry-run-diff.md"
+    patch_bundle = artifact_dir / "promotion-patch-bundle.json"
+    rollback_manifest = artifact_dir / "rollback-manifest.json"
+    missing = [str(path.relative_to(job_dir)) for path in [dry_run_diff, patch_bundle, rollback_manifest] if not path.exists()]
+    hashes: dict[str, Any] = {
+        "artifact_dir": artifact_dir,
+        "dry_run_diff": dry_run_diff,
+        "patch_bundle": patch_bundle,
+        "rollback_manifest": rollback_manifest,
+        "missing": missing,
+    }
+    if not missing:
+        hashes.update(
+            {
+                "dry_run_diff_sha256": sha256_file(dry_run_diff),
+                "bundle_sha256": sha256_file(patch_bundle),
+                "rollback_manifest_sha256": sha256_file(rollback_manifest),
+            }
+        )
+    return hashes
+
+
+def promotion_apply_bundle(project: Path, job_dir: Path, task_id: str) -> dict[str, Any]:
+    artifact_dir = job_dir / "artifacts" / "tasks" / task_id
+    bundle_path = artifact_dir / "promotion-patch-bundle.json"
+    if not bundle_path.exists():
+        return {
+            "ok": False,
+            "error": "promotion_patch_bundle_missing",
+            "missing": str(bundle_path.relative_to(job_dir)),
+            "real_project_modified": False,
+        }
+    bundle = json.loads(bundle_path.read_text(encoding="utf-8"))
+    changed_files = bundle.get("changed_files") or []
+    if not isinstance(changed_files, list) or not changed_files:
+        return {
+            "ok": False,
+            "error": "promotion_patch_bundle_has_no_changed_files",
+            "bundle": str(bundle_path.relative_to(job_dir)),
+            "real_project_modified": False,
+        }
+
+    errors: list[dict[str, Any]] = []
+    rollback_entries: list[dict[str, Any]] = []
+    for item in changed_files:
+        try:
+            rel = normalize_declared_path(str(item.get("path") or ""))
+        except ValueError as exc:
+            errors.append({"path": item.get("path"), "stage": "path_validation", "error": str(exc)})
+            continue
+        target = project / rel
+        old_exists = target.exists()
+        old_data = target.read_bytes() if old_exists else None
+        old_sha = hashlib.sha256(old_data).hexdigest() if old_data is not None else None
+        if old_exists != bool(item.get("old_exists")) or old_sha != item.get("old_sha256"):
+            errors.append(
+                {
+                    "path": rel,
+                    "stage": "preimage_check",
+                    "expected_exists": item.get("old_exists"),
+                    "actual_exists": old_exists,
+                    "expected_sha256": item.get("old_sha256"),
+                    "actual_sha256": old_sha,
+                }
+            )
+        rollback_entries.append(
+            {
+                "path": rel,
+                "old_exists": old_exists,
+                "old_sha256": old_sha,
+                "old_content_b64": base64.b64encode(old_data).decode("ascii") if old_data is not None else None,
+            }
+        )
+    if errors:
+        return {
+            "ok": False,
+            "error": "promotion_preimage_check_failed",
+            "errors": errors,
+            "real_project_modified": False,
+        }
+
+    apply_dir = artifact_dir / "promotion-apply"
+    apply_dir.mkdir(parents=True, exist_ok=True)
+    rollback_snapshot = {
+        "task_id": task_id,
+        "bundle_sha256": sha256_file(bundle_path),
+        "entries": rollback_entries,
+    }
+    rollback_snapshot_path = apply_dir / "rollback-content-snapshot.json"
+    rollback_snapshot_text = json.dumps(rollback_snapshot, indent=2) + "\n"
+    rollback_snapshot_path.write_text(rollback_snapshot_text, encoding="utf-8")
+
+    applied: list[dict[str, Any]] = []
+    written_targets: list[Path] = []
+    try:
+        for item in changed_files:
+            rel = normalize_declared_path(str(item.get("path") or ""))
+            sandbox_rel = normalize_declared_path(str(item.get("sandbox_path") or ""))
+            source = (job_dir / sandbox_rel).resolve()
+            job_root_resolved = job_dir.resolve()
+            if job_root_resolved != source and job_root_resolved not in source.parents:
+                raise RuntimeError(f"source artifact escapes job dir for {rel}: {source}")
+            target = project / rel
+            if not source.exists():
+                raise RuntimeError(f"source artifact missing for {rel}: {source}")
+            source_data = source.read_bytes()
+            source_sha = hashlib.sha256(source_data).hexdigest()
+            if source_sha != item.get("new_sha256"):
+                raise RuntimeError(f"source hash mismatch for {rel}: {source_sha} != {item.get('new_sha256')}")
+            target.parent.mkdir(parents=True, exist_ok=True)
+            # Write to a sibling temp file and replace to avoid torn targets.
+            tmp = target.with_name(f".{target.name}.socra-promote-tmp")
+            tmp.write_bytes(source_data)
+            tmp.replace(target)
+            written_targets.append(target)
+            actual_sha = sha256_file(target)
+            if actual_sha != item.get("new_sha256"):
+                raise RuntimeError(f"post-write hash mismatch for {rel}: {actual_sha} != {item.get('new_sha256')}")
+            applied.append(
+                {
+                    "path": rel,
+                    "new_sha256": actual_sha,
+                    "source_task_id": item.get("source_task_id"),
+                    "sandbox_path": item.get("sandbox_path"),
+                }
+            )
+    except Exception as exc:  # noqa: BLE001 - rollback best effort is recorded.
+        rollback_errors: list[dict[str, Any]] = []
+        by_path = {entry["path"]: entry for entry in rollback_entries}
+        for target in reversed(written_targets):
+            rel = str(target.relative_to(project))
+            entry = by_path.get(rel)
+            if not entry:
+                continue
+            try:
+                if entry.get("old_exists"):
+                    target.write_bytes(base64.b64decode(entry.get("old_content_b64") or ""))
+                elif target.exists():
+                    target.unlink()
+            except Exception as rollback_exc:  # noqa: BLE001
+                rollback_errors.append({"path": rel, "error": str(rollback_exc)})
+        return {
+            "ok": False,
+            "error": "promotion_apply_failed",
+            "exception": str(exc),
+            "applied_before_error": applied,
+            "rollback_errors": rollback_errors,
+            "rollback_content_snapshot": str(rollback_snapshot_path.relative_to(job_dir)),
+            "rollback_content_snapshot_sha256": sha256_text(rollback_snapshot_text),
+            "real_project_modified": bool(applied),
+        }
+
+    receipt = {
+        "task_id": task_id,
+        "bundle_sha256": sha256_file(bundle_path),
+        "applied_count": len(applied),
+        "applied": applied,
+        "rollback_content_snapshot": str(rollback_snapshot_path.relative_to(job_dir)),
+        "rollback_content_snapshot_sha256": sha256_text(rollback_snapshot_text),
+        "real_project_modified": True,
+    }
+    receipt_path = apply_dir / "promotion-apply-receipt.json"
+    receipt_text = json.dumps(receipt, indent=2) + "\n"
+    receipt_path.write_text(receipt_text, encoding="utf-8")
+    return {
+        "ok": True,
+        "receipt": receipt,
+        "receipt_path": str(receipt_path.relative_to(job_dir)),
+        "receipt_sha256": sha256_text(receipt_text),
+        "rollback_content_snapshot": str(rollback_snapshot_path.relative_to(job_dir)),
+        "rollback_content_snapshot_sha256": sha256_text(rollback_snapshot_text),
+        "real_project_modified": True,
+    }
+
+
+def present_promotion_diff(job_dir: Path, task_id: str, reviewer_name: str, notes: str = "") -> dict[str, Any]:
+    artifacts = promotion_artifact_hashes(job_dir, task_id)
+    missing = artifacts["missing"]
+    if missing:
+        return {
+            "ok": False,
+            "missing": missing,
+            "error": "promotion_dry_run_artifacts_missing",
+        }
+
+    dry_run_diff = artifacts["dry_run_diff"]
+    text = dry_run_diff.read_text(encoding="utf-8", errors="replace")
+    start = time.monotonic()
+    # Print the exact artifact bytes as text. This is intentionally simple and
+    # observable in logs; callers can pipe through a pager if desired.
+    sys.stdout.write(text)
+    if text and not text.endswith("\n"):
+        sys.stdout.write("\n")
+    sys.stdout.flush()
+    elapsed = elapsed_ms(start)
+    rendered_lines = len(text.splitlines())
+    return {
+        "ok": True,
+        "task_id": task_id,
+        "reviewer_role": "human",
+        "reviewer_name": reviewer_name,
+        "dry_run_diff": str(dry_run_diff.relative_to(job_dir)),
+        "dry_run_diff_sha256": artifacts["dry_run_diff_sha256"],
+        "bundle": str(artifacts["patch_bundle"].relative_to(job_dir)),
+        "bundle_sha256": artifacts["bundle_sha256"],
+        "rollback_manifest": str(artifacts["rollback_manifest"].relative_to(job_dir)),
+        "rollback_manifest_sha256": artifacts["rollback_manifest_sha256"],
+        "presentation_method": "stdout",
+        "rendered_line_count": rendered_lines,
+        "process_exit_status": 0,
+        "elapsed_ms": elapsed,
+        "displayed_hash_matched_approval_target": True,
+        "notes": notes,
+    }
+
+
+def job_review_promotion_main(args: argparse.Namespace) -> int:
+    project = args.project.expanduser().resolve()
+    job_dir = find_job_dir(project, args.job_id)
+    with JobLock(job_dir / ".lock"):
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        task = next((item for item in plan.get("tasks", []) if item.get("id") == args.task_id), None)
+        behavior_preference = getattr(args, "behavior_preference", None)
+        gene_evidence = getattr(args, "gene_evidence", None)
+        generated = ensure_promotion_artifacts(project, job_dir, args.task_id)
+        artifacts = promotion_artifact_hashes(job_dir, args.task_id)
+        artifact_dir = artifacts["artifact_dir"]
+        missing = artifacts["missing"]
+        log = JobEventLog(job_dir / "events.jsonl", state.job_id or job_dir.name)
+        if generated.get("generated"):
+            log.append("promotion_artifacts_generated", {"task_id": args.task_id, **generated})
+        if missing:
+            log.append(
+                "promotion_review_failed",
+                {
+                    "task_id": args.task_id,
+                    "reviewer_role": "human",
+                    "reviewer_name": args.reviewer_name,
+                    "error": "promotion_dry_run_artifacts_missing",
+                    "missing": missing,
+                },
+            )
+            code = 2
+            print(f"Promotion review failed: {args.task_id}")
+            print(f"Missing artifacts: {', '.join(missing)}")
+        elif bool(behavior_preference) != bool(gene_evidence):
+            log.append(
+                "promotion_behavior_preference_blocked",
+                {
+                    "task_id": args.task_id,
+                    "error": "behavior_and_heldout_evidence_required_together",
+                    "real_project_modified": False,
+                },
+            )
+            code = 2
+            print(f"Promotion authorization blocked: {args.task_id}")
+            print("Reason: behavior_and_heldout_evidence_required_together")
+        elif behavior_preference and behavior_overlaps_patch(
+            behavior_preference,
+            artifacts["dry_run_diff"].read_text(encoding="utf-8", errors="replace"),
+        ):
+            log.append(
+                "promotion_behavior_preference_blocked",
+                {
+                    "task_id": args.task_id,
+                    "error": "behavior_card_overlaps_patch_text",
+                    "real_project_modified": False,
+                },
+            )
+            code = 2
+            print(f"Promotion authorization blocked: {args.task_id}")
+            print("Reason: behavior_card_overlaps_patch_text")
+        elif behavior_preference and (
+            not task
+            or not isinstance(task.get("recurrence"), dict)
+            or task["recurrence"].get("status") != "assignable"
+        ):
+            log.append(
+                "promotion_behavior_preference_blocked",
+                {
+                    "task_id": args.task_id,
+                    "error": "assignable_recurrence_key_required",
+                    "real_project_modified": False,
+                },
+            )
+            code = 2
+            print(f"Promotion authorization blocked: {args.task_id}")
+            print("Reason: assignable_recurrence_key_required_for_behavior_gene")
+        else:
+            if args.present_diff and (args.approve_source_promotion or args.attest_reviewed):
+                log.append(
+                    "promotion_authorization_blocked",
+                    {
+                        "task_id": args.task_id,
+                        "error": "promotion_presentation_and_authorization_must_be_separate_invocations",
+                        "policy": "diff presentation must complete before a later human authorization command can approve that exact artifact hash",
+                        "real_project_modified": False,
+                    },
+                )
+                code = 2
+                print(f"Promotion authorization blocked: {args.task_id}")
+                print("Reason: promotion_presentation_and_authorization_must_be_separate_invocations")
+            else:
+                if args.present_diff:
+                    presentation = present_promotion_diff(job_dir, args.task_id, args.reviewer_name, args.notes)
+                    if not presentation.get("ok"):
+                        log.append("promotion_review_failed", presentation)
+                        code = 2
+                        print(f"Promotion diff presentation failed: {args.task_id}")
+                    else:
+                        log.append("promotion_diff_presented", {key: value for key, value in presentation.items() if key != "ok"})
+                        code = 0
+                else:
+                    presentation_event = latest_diff_presentation(
+                        events,
+                        args.task_id,
+                        str(artifacts["bundle_sha256"]),
+                        str(artifacts["dry_run_diff_sha256"]),
+                    )
+                    rejection_event = matching_diff_rejection(
+                        events,
+                        args.task_id,
+                        str(artifacts["bundle_sha256"]),
+                        str(artifacts["dry_run_diff_sha256"]),
+                    )
+                    if args.approve_source_promotion and presentation_event is None:
+                        log.append(
+                            "promotion_authorization_blocked",
+                            {
+                                "task_id": args.task_id,
+                                "error": "promotion_diff_presentation_required",
+                                "required_event": "promotion_diff_presented",
+                                "required_bundle_sha256": artifacts["bundle_sha256"],
+                                "required_dry_run_diff_sha256": artifacts["dry_run_diff_sha256"],
+                                "policy": "human authorization must be tied to a presented diff artifact hash",
+                                "real_project_modified": False,
+                            },
+                        )
+                        code = 2
+                        print(f"Promotion authorization blocked: {args.task_id}")
+                        print("Reason: promotion_diff_presentation_required")
+                    elif args.approve_source_promotion and rejection_event is not None:
+                        log.append(
+                            "promotion_authorization_blocked",
+                            {
+                                "task_id": args.task_id,
+                                "error": "promotion_diff_rejected",
+                                "rejection_event_seq": rejection_event["event_seq"],
+                                "bundle_sha256": artifacts["bundle_sha256"],
+                                "dry_run_diff_sha256": artifacts["dry_run_diff_sha256"],
+                                "policy": "a human-rejected artifact hash cannot later be authorized",
+                                "real_project_modified": False,
+                            },
+                        )
+                        code = 2
+                        print(f"Promotion authorization blocked: {args.task_id}")
+                        print("Reason: promotion_diff_rejected")
+                    else:
+                        if behavior_preference:
+                            preference_path = artifact_dir / "behavior-preference.json"
+                            write_json(preference_path, behavior_preference)
+                            evidence_path = artifact_dir / "heldout-gene-evidence.json"
+                            write_json(evidence_path, gene_evidence)
+                            log.append(
+                                "promotion_behavior_preference_bound",
+                                {
+                                    "task_id": args.task_id,
+                                    "reviewer_role": "human",
+                                    "reviewer_name": args.reviewer_name,
+                                    "bundle_sha256": artifacts["bundle_sha256"],
+                                    "recurrence_key_sha256": task["recurrence"]["recurrence_key_sha256"],
+                                    "preference": behavior_preference,
+                                    "preference_path": str(preference_path.relative_to(job_dir)),
+                                    "preference_sha256": recurrence_sha256_json(behavior_preference),
+                                    "heldout_evidence": gene_evidence,
+                                    "heldout_evidence_path": str(evidence_path.relative_to(job_dir)),
+                                    "heldout_evidence_sha256": sha256_file(evidence_path),
+                                    "contains_patch_or_source": False,
+                                    "behavior_not_answer_human_attested": True,
+                                    "policy": "reviewer_authored_prefer_behavior_bound_to_authorized_bundle",
+                                },
+                            )
+                        authorization = {
+                            "task_id": args.task_id,
+                            "authorizer_role": "human",
+                            "authorizer_name": args.reviewer_name,
+                            "human_source_promotion_authorized": bool(args.approve_source_promotion),
+                            "bundle": str(artifacts["patch_bundle"].relative_to(job_dir)),
+                            "bundle_sha256": artifacts["bundle_sha256"],
+                            "dry_run_diff": str(artifacts["dry_run_diff"].relative_to(job_dir)),
+                            "dry_run_diff_sha256": artifacts["dry_run_diff_sha256"],
+                            "rollback_manifest": str(artifacts["rollback_manifest"].relative_to(job_dir)),
+                            "rollback_manifest_sha256": artifacts["rollback_manifest_sha256"],
+                            "presentation_event_seq": presentation_event["event_seq"] if presentation_event else None,
+                            "notes": args.notes,
+                            "policy": "human_authorization_required_after_ai_prescreen_before_real_project_write",
+                        }
+                        authorization_path = artifact_dir / "human-promotion-authorization.json"
+                        authorization_path.write_text(json.dumps(authorization, indent=2) + "\n", encoding="utf-8")
+                        log.append(
+                            "promotion_human_authorized",
+                            {
+                                **authorization,
+                                "authorization": str(authorization_path.relative_to(job_dir)),
+                                "authorization_sha256": sha256_file(authorization_path),
+                            },
+                        )
+                        if args.attest_reviewed:
+                            attestation = {
+                                "task_id": args.task_id,
+                                "reviewer_role": "human",
+                                "reviewer_name": args.reviewer_name,
+                                "human_review_attested": True,
+                                "attestation_scope": "self_declared_review_of_presented_diff",
+                                "bundle_sha256": artifacts["bundle_sha256"],
+                                "dry_run_diff_sha256": artifacts["dry_run_diff_sha256"],
+                                "presentation_event_seq": presentation_event["event_seq"] if presentation_event else None,
+                                "notes": args.notes,
+                            }
+                            attestation_path = artifact_dir / "human-review-attestation.json"
+                            attestation_path.write_text(json.dumps(attestation, indent=2) + "\n", encoding="utf-8")
+                            log.append(
+                                "promotion_human_review_attested",
+                                {
+                                    **attestation,
+                                    "attestation": str(attestation_path.relative_to(job_dir)),
+                                    "attestation_sha256": sha256_file(attestation_path),
+                                },
+                            )
+                        # Legacy compatibility event for old analysis tools. It is now
+                        # explicitly scoped as authorization, not proof of observed review.
+                        legacy = {
+                            "task_id": args.task_id,
+                            "reviewer_role": "human",
+                            "reviewer_name": args.reviewer_name,
+                            "reviewed_artifacts": {
+                                "dry_run_diff": str(artifacts["dry_run_diff"].relative_to(job_dir)),
+                                "patch_bundle": str(artifacts["patch_bundle"].relative_to(job_dir)),
+                                "rollback_manifest": str(artifacts["rollback_manifest"].relative_to(job_dir)),
+                            },
+                            "human_source_promotion_approval_granted": bool(args.approve_source_promotion),
+                            "authorization_event": "promotion_human_authorized",
+                            "review_proof_scope": "authorization_only_unless_promotion_human_review_attested_exists",
+                            "notes": args.notes,
+                            "policy": "legacy_compatibility_event_do_not_treat_as_proof_of_observed_review",
+                        }
+                        legacy_path = artifact_dir / "human-promotion-review.json"
+                        legacy_path.write_text(json.dumps(legacy, indent=2) + "\n", encoding="utf-8")
+                        log.append(
+                            "promotion_human_diff_reviewed",
+                            {
+                                **legacy,
+                                "review": str(legacy_path.relative_to(job_dir)),
+                                "sha256": sha256_file(legacy_path),
+                            },
+                        )
+                        code = 0 if args.approve_source_promotion else 2
+                        print(f"Promotion human authorization recorded: {args.task_id}")
+                        print(f"Authorized for source promotion: {bool(args.approve_source_promotion)}")
+
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        write_json(job_dir / "plan.json", plan)
+        write_state_snapshot(job_dir / "job.json", state)
+        write_handoff(job_dir, state_to_json(state), plan)
+        return code
+
+
+def job_reject_promotion_main(args: argparse.Namespace) -> int:
+    project = args.project.expanduser().resolve()
+    job_dir = find_job_dir(project, args.job_id)
+    with JobLock(job_dir / ".lock"):
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        task = next((item for item in plan.get("tasks", []) if item.get("id") == args.task_id), None)
+        artifacts = promotion_artifact_hashes(job_dir, args.task_id)
+        log = JobEventLog(job_dir / "events.jsonl", state.job_id or job_dir.name)
+        presentation = None
+        if not artifacts.get("missing"):
+            presentation = latest_diff_presentation(
+                events,
+                args.task_id,
+                str(artifacts["bundle_sha256"]),
+                str(artifacts["dry_run_diff_sha256"]),
+            )
+        if not task or task.get("status") != "passed":
+            log.append(
+                "promotion_rejection_blocked",
+                {"task_id": args.task_id, "error": "promotion_task_not_passed", "real_project_modified": False},
+            )
+            code = 2
+            print(f"Promotion rejection blocked: {args.task_id}")
+            print("Reason: promotion_task_not_passed")
+        elif artifacts.get("missing"):
+            log.append(
+                "promotion_rejection_blocked",
+                {
+                    "task_id": args.task_id,
+                    "error": "promotion_artifacts_missing",
+                    "missing": artifacts.get("missing"),
+                    "real_project_modified": False,
+                },
+            )
+            code = 2
+            print(f"Promotion rejection blocked: {args.task_id}")
+            print("Reason: promotion_artifacts_missing")
+        elif presentation is None:
+            log.append(
+                "promotion_rejection_blocked",
+                {
+                    "task_id": args.task_id,
+                    "error": "promotion_diff_presentation_required",
+                    "required_event": "promotion_diff_presented",
+                    "bundle_sha256": artifacts["bundle_sha256"],
+                    "dry_run_diff_sha256": artifacts["dry_run_diff_sha256"],
+                    "real_project_modified": False,
+                },
+            )
+            code = 2
+            print(f"Promotion rejection blocked: {args.task_id}")
+            print("Reason: promotion_diff_presentation_required")
+        elif matching_diff_rejection(
+            events,
+            args.task_id,
+            str(artifacts["bundle_sha256"]),
+            str(artifacts["dry_run_diff_sha256"]),
+        ):
+            print(f"Promotion rejection already recorded: {args.task_id}")
+            code = 0
+        else:
+            rejection = {
+                "task_id": args.task_id,
+                "reviewer_role": "human",
+                "reviewer_name": args.reviewer_name,
+                "human_source_promotion_rejected": True,
+                "failure_class": "human_rejects_diff",
+                "error": "human_rejected_presented_diff",
+                "reason": args.reason,
+                "notes": args.notes,
+                "bundle": str(artifacts["patch_bundle"].relative_to(job_dir)),
+                "bundle_sha256": artifacts["bundle_sha256"],
+                "dry_run_diff": str(artifacts["dry_run_diff"].relative_to(job_dir)),
+                "dry_run_diff_sha256": artifacts["dry_run_diff_sha256"],
+                "rollback_manifest": str(artifacts["rollback_manifest"].relative_to(job_dir)),
+                "rollback_manifest_sha256": artifacts["rollback_manifest_sha256"],
+                "presentation_event_seq": presentation["event_seq"],
+                "policy": "human rejection is terminal for the exact presented artifact hashes",
+                "real_project_modified": False,
+            }
+            rejection_path = artifacts["artifact_dir"] / "human-promotion-rejection.json"
+            rejection_path.write_text(json.dumps(rejection, indent=2) + "\n", encoding="utf-8")
+            rejection_event = log.append(
+                "promotion_human_rejected",
+                {
+                    **rejection,
+                    "rejection": str(rejection_path.relative_to(job_dir)),
+                    "rejection_sha256": sha256_file(rejection_path),
+                },
+            )
+            try:
+                current_events = read_events(job_dir / "events.jsonl")
+                exported = export_failed_trace(project, task, current_events, rejection_event)
+                trace_event_type = "central_trace_exported" if exported.get("index_ok") else "central_trace_index_pending"
+                log.append(
+                    trace_event_type,
+                    {
+                        "task_id": args.task_id,
+                        "source_event_seq": rejection_event.seq,
+                        **exported,
+                    },
+                )
+                if not exported.get("index_ok"):
+                    print("Warning: rejection trace is durable but Mumpix indexing is pending; run `wydcode traces sync --project .`")
+            except Exception as exc:  # noqa: BLE001 - local rejection remains authoritative.
+                log.append(
+                    "central_trace_export_failed",
+                    {
+                        "task_id": args.task_id,
+                        "source_event_seq": rejection_event.seq,
+                        "error": str(exc),
+                        "ledger_status": "unknown",
+                        "next_action": "run `wydcode traces sync --project .`",
+                    },
+                )
+                print(f"Warning: rejection trace export failed; run `wydcode traces sync --project .`: {exc}")
+            code = 0
+            print(f"Promotion rejected: {args.task_id}")
+            print("Real project modified: false")
+
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        write_json(job_dir / "plan.json", plan)
+        write_state_snapshot(job_dir / "job.json", state)
+        write_handoff(job_dir, state_to_json(state), plan)
+        return code
+
+
+def job_promote_main(args: argparse.Namespace) -> int:
+    project = args.project.expanduser().resolve()
+    job_dir = find_job_dir(project, args.job_id)
+    with JobLock(job_dir / ".lock"):
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        task = next((item for item in plan.get("tasks", []) if item.get("id") == args.task_id), None)
+        log = JobEventLog(job_dir / "events.jsonl", state.job_id or job_dir.name)
+        generated = ensure_promotion_artifacts(project, job_dir, args.task_id)
+        if generated.get("generated"):
+            log.append("promotion_artifacts_generated", {"task_id": args.task_id, **generated})
+        human_review = human_promotion_review(events, args.task_id)
+        artifacts = promotion_artifact_hashes(job_dir, args.task_id)
+        if not task or task.get("status") != "passed":
+            log.append(
+                "promotion_blocked",
+                {
+                    "task_id": args.task_id,
+                    "error": "promotion_task_not_passed",
+                    "task_status": task.get("status") if task else "missing",
+                    "policy": "promotion_requires_passed_rehearsal_task_and_human_diff_review",
+                },
+            )
+            code = 2
+            print(f"Promotion blocked: {args.task_id}")
+            print("Reason: promotion_task_not_passed")
+        elif human_review is None:
+            log.append(
+                "promotion_blocked",
+                {
+                    "task_id": args.task_id,
+                    "error": "human_source_promotion_review_required",
+                    "policy": "ai_prescreen_is_not_source_promotion_authorization",
+                    "required_event": "promotion_human_authorized",
+                    "required_field": "human_source_promotion_authorized=true",
+                    "legacy_accepted_for_existing_jobs": "promotion_human_diff_reviewed",
+                    "real_project_modified": False,
+                },
+            )
+            code = 2
+            print(f"Promotion blocked: {args.task_id}")
+            print("Reason: human_source_promotion_review_required")
+        elif artifacts.get("missing"):
+            log.append(
+                "promotion_blocked",
+                {
+                    "task_id": args.task_id,
+                    "error": "promotion_artifacts_missing",
+                    "missing": artifacts.get("missing"),
+                    "human_review": human_review,
+                    "real_project_modified": False,
+                },
+            )
+            code = 2
+            print(f"Promotion blocked: {args.task_id}")
+            print("Reason: promotion_artifacts_missing")
+        elif human_review.get("bundle_sha256") and human_review.get("bundle_sha256") != artifacts.get("bundle_sha256"):
+            log.append(
+                "promotion_blocked",
+                {
+                    "task_id": args.task_id,
+                    "error": "promotion_authorized_bundle_hash_mismatch",
+                    "authorized_bundle_sha256": human_review.get("bundle_sha256"),
+                    "current_bundle_sha256": artifacts.get("bundle_sha256"),
+                    "human_review": human_review,
+                    "policy": "promotion applies only the exact bundle hash that was presented and authorized",
+                    "real_project_modified": False,
+                },
+            )
+            code = 2
+            print(f"Promotion blocked: {args.task_id}")
+            print("Reason: promotion_authorized_bundle_hash_mismatch")
+        elif not args.execute:
+            log.append(
+                "promotion_preflight_passed",
+                {
+                    "task_id": args.task_id,
+                    "human_review": human_review,
+                    "real_project_modified": False,
+                    "next_action": "rerun with --execute to apply the approved bundle",
+                },
+            )
+            code = 0
+            print(f"Promotion preflight passed: {args.task_id}")
+            print("Real project modified: false")
+        else:
+            apply_result = promotion_apply_bundle(project, job_dir, args.task_id)
+            if apply_result.get("ok"):
+                receipt = apply_result.get("receipt") or {}
+                promotion_event = log.append(
+                    "promotion_applied",
+                    {
+                        "task_id": args.task_id,
+                        "bundle_sha256": receipt.get("bundle_sha256"),
+                        "applied_count": receipt.get("applied_count"),
+                        "receipt_path": apply_result.get("receipt_path"),
+                        "receipt_sha256": apply_result.get("receipt_sha256"),
+                        "rollback_content_snapshot_path": apply_result.get("rollback_content_snapshot"),
+                        "rollback_content_snapshot_sha256": apply_result.get("rollback_content_snapshot_sha256"),
+                        "human_review": human_review,
+                        "real_project_modified": True,
+                    },
+                )
+                fired_event = next(
+                    (
+                        event
+                        for event in reversed(read_events(job_dir / "events.jsonl"))
+                        if event.type == "retrieval_fired" and event.payload.get("task_id") == args.task_id
+                    ),
+                    None,
+                )
+                fired = fired_event.to_json() if fired_event else None
+                if fired:
+                    log.append(
+                        "retrieval_backed_promotion",
+                        {
+                            "task_id": args.task_id,
+                            "retrieval_event_seq": fired.get("seq"),
+                            "retrieval_event_sha256": recurrence_sha256_json(fired),
+                            "gene_id": fired.get("payload", {}).get("gene_id"),
+                            "source_central_event_sha256": fired.get("payload", {}).get("source_central_event_sha256"),
+                            "recurrence_key_sha256": fired.get("payload", {}).get("recurrence_key_sha256"),
+                            "preference_sha256": fired.get("payload", {}).get("preference_sha256"),
+                            "promotion_event_seq": promotion_event.seq,
+                            "promotion_receipt_sha256": apply_result.get("receipt_sha256"),
+                            "classification": "route_fired_and_promoted_not_paired_capability_lift",
+                        },
+                    )
+                try:
+                    export_events = read_events(job_dir / "events.jsonl")
+                    export_result = export_promoted_trace(project, job_dir, task, export_events, promotion_event)
+                    log.append(
+                        "central_trace_exported" if export_result.get("index_ok") else "central_trace_export_partial",
+                        {
+                            "task_id": args.task_id,
+                            **export_result,
+                            "source_of_truth": "cross_project_hash_chained_jsonl",
+                            "mumpix_role": "derived_rebuildable_index",
+                            "retry_required": not export_result.get("index_ok"),
+                        },
+                    )
+                    if not export_result.get("index_ok"):
+                        print("Warning: promotion is durable, but its Mumpix index update failed.")
+                        print("Run `wydcode traces sync --project .` and verify `wydcode traces status` reports zero pending events.")
+                except Exception as exc:  # noqa: BLE001 - promotion already succeeded and must remain successful.
+                    log.append(
+                        "central_trace_export_failed",
+                        {
+                            "task_id": args.task_id,
+                            "error": str(exc)[:1000],
+                            "promotion_remains_applied": True,
+                            "retry_command": "wydcode traces sync --project .",
+                        },
+                    )
+                    print(f"Warning: promotion is durable, but central trace export failed: {exc}")
+                    print("Run `wydcode traces sync --project .` before relying on the cross-project trace index.")
+                code = 0
+                print(f"Promotion applied: {args.task_id}")
+                print(f"Applied files: {receipt.get('applied_count')}")
+                print(f"Receipt: {apply_result.get('receipt_path')}")
+            else:
+                log.append(
+                    "promotion_failed",
+                    {
+                        "task_id": args.task_id,
+                        "error": apply_result.get("error"),
+                        "details": apply_result,
+                        "human_review": human_review,
+                        "real_project_modified": apply_result.get("real_project_modified", False),
+                    },
+                )
+                code = 2
+                print(f"Promotion failed: {args.task_id}")
+                print(f"Reason: {apply_result.get('error')}")
+
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        write_json(job_dir / "plan.json", plan)
+        write_state_snapshot(job_dir / "job.json", state)
+        write_handoff(job_dir, state_to_json(state), plan)
+        return code
+
+
+def job_reverify_task_main(args: argparse.Namespace) -> int:
+    project = args.project.expanduser().resolve()
+    if args.job_id:
+        job_dir = job_root(project) / args.job_id
+    else:
+        found = find_latest_incomplete_job(project)
+        if not found:
+            raise SystemExit(f"No incomplete Socra jobs found under {job_root(project)}")
+        job_dir = found
+
+    with JobLock(job_dir / ".lock"):
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        tasks = {str(task.get("id")): task for task in plan.get("tasks", [])}
+        task = tasks.get(args.task_id)
+        if not task:
+            raise SystemExit(f"Task not found: {args.task_id}")
+        if task.get("status") != "passed" and not args.allow_unpassed:
+            raise SystemExit(f"Task is not passed: {args.task_id}. Pass --allow-unpassed to record evidence anyway.")
+
+        evidence_path = args.evidence.expanduser().resolve()
+        evidence = json.loads(evidence_path.read_text(encoding="utf-8"))
+        criteria, errors, all_passed = validate_reverification_evidence(task, evidence)
+        artifact_dir = job_dir / "artifacts" / "tasks" / args.task_id
+        artifact_dir.mkdir(parents=True, exist_ok=True)
+        stored_evidence = artifact_dir / "reverification-evidence.json"
+        stored_evidence.write_text(json.dumps({"task_id": args.task_id, **evidence, "criteria": criteria}, indent=2) + "\n", encoding="utf-8")
+
+        log = JobEventLog(job_dir / "events.jsonl", state.job_id or job_dir.name)
+        if errors:
+            log.append(
+                "task_reverification_failed",
+                {
+                    "task_id": args.task_id,
+                    "errors": errors,
+                    "evidence_path": str(stored_evidence.relative_to(job_dir)),
+                    "sha256": sha256_file(stored_evidence),
+                },
+            )
+            code = 2
+            print(f"Task reverification failed: {args.task_id}")
+            for error in errors:
+                print(f"- {error}")
+        else:
+            log.append(
+                "task_reverified",
+                {
+                    "task_id": args.task_id,
+                    "criteria": criteria,
+                    "runner_checks": evidence.get("runner_checks") if isinstance(evidence.get("runner_checks"), list) else [],
+                    "review_level": "acceptance_reverified" if all_passed else "acceptance_partial",
+                    "acceptance_review": "full" if all_passed else "partial",
+                    "all_criteria_passed": all_passed,
+                    "evidence_path": str(stored_evidence.relative_to(job_dir)),
+                    "sha256": sha256_file(stored_evidence),
+                    "notes": evidence.get("notes") or args.notes or "",
+                },
+            )
+            code = 0 if all_passed else 2
+            print(f"Task reverified: {args.task_id}")
+            print(f"Acceptance review: {'full' if all_passed else 'partial'}")
+
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        write_json(job_dir / "plan.json", plan)
+        write_state_snapshot(job_dir / "job.json", state)
+        write_handoff(job_dir, state_to_json(state), plan)
+        return code
+
+
+def job_run_milestone_main(args: argparse.Namespace) -> int:
+    project = args.project.expanduser().resolve()
+    if args.job_id:
+        job_dir = job_root(project) / args.job_id
+    else:
+        found = find_latest_incomplete_job(project)
+        if not found:
+            raise SystemExit(f"No incomplete Socra jobs found under {job_root(project)}")
+        job_dir = found
+
+    with JobLock(job_dir / ".lock"):
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        tasks = plan.get("tasks") if isinstance(plan.get("tasks"), list) else []
+        passed_task_ids = [str(task.get("id")) for task in tasks if task.get("status") == "passed"]
+        milestone_id = args.milestone_id or f"milestone-{len([e for e in events if e.type == 'milestone_runner_started']) + 1:03d}"
+        command = args.command or "npm run build"
+        review_level, inferred_promotion_grade = infer_milestone_review_level(command)
+        promotion_grade = bool(args.promotion_grade or inferred_promotion_grade)
+        log = JobEventLog(job_dir / "events.jsonl", state.job_id or job_dir.name)
+        log.append(
+            "milestone_runner_started",
+            {
+                "milestone_id": milestone_id,
+                "passed_task_ids": passed_task_ids,
+                "command": command,
+                "review_level": review_level,
+                "promotion_grade": promotion_grade,
+                "dependency_prep": args.prepare_deps,
+                "policy": "partial_smoke_reviewer_audit_enforced_dependency_vulnerabilities_block_only_promotion_grade",
+            },
+        )
+
+        partials = tasks_requiring_milestone_reverification(events, passed_task_ids)
+        if partials and not args.allow_partial_smoke:
+            log.append(
+                "milestone_runner_failed",
+                {
+                    "milestone_id": milestone_id,
+                    "error": "partial_smoke_tasks_require_reverification",
+                    "review_level": review_level,
+                    "promotion_grade": False,
+                    "partial_tasks": partials,
+                    "next_action": "run a milestone preview/build/review that proves acceptance, then emit a reclassification event",
+                },
+            )
+            events = read_events(job_dir / "events.jsonl")
+            state = replay(events)
+            plan = materialize_plan_from_events(events, load_plan(job_dir))
+            write_json(job_dir / "plan.json", plan)
+            write_state_snapshot(job_dir / "job.json", state)
+            write_handoff(job_dir, state_to_json(state), plan)
+            print(f"Milestone runner failed: {milestone_id}")
+            print("Reason: partial_smoke_tasks_require_reverification")
+            for item in partials:
+                print(f"- {item['task_id']}: {item['review_level']} / {item['acceptance_review']}")
+            return 2
+
+        runner_dir = job_dir / "sandbox" / "milestones" / milestone_id
+        if runner_dir.exists():
+            shutil.rmtree(runner_dir)
+        overlay_dir = runner_dir / "project"
+        overlays = overlay_passed_task_artifacts(project, job_dir, plan, overlay_dir)
+        dependency_links = link_existing_dependency_trees(project, overlay_dir) if args.prepare_deps == "none" else []
+        log.append(
+            "milestone_overlay_written",
+            {
+                "milestone_id": milestone_id,
+                "overlay_dir": str(overlay_dir.relative_to(job_dir)),
+                "overlays": overlays,
+                "reused_dependency_trees": dependency_links,
+            },
+        )
+
+        dep_payload, dep_code = prepare_runner_dependencies(overlay_dir, args.prepare_deps, args.deps_timeout_seconds)
+        exception_counts = active_vulnerability_exception_counts(events)
+        dep_vuln_policy = dependency_vulnerability_policy(dep_payload, promotion_grade, exception_counts) if args.prepare_deps != "none" else None
+        if args.prepare_deps != "none":
+            log.append(
+                "sandbox_env_prepared",
+                {
+                    "milestone_id": milestone_id,
+                    "overlay_dir": str(overlay_dir.relative_to(job_dir)),
+                    **dep_payload,
+                    "dependency_vulnerability_policy": dep_vuln_policy,
+                },
+            )
+        if dep_code != 0:
+            payload = {
+                "milestone_id": milestone_id,
+                "command": command,
+                "returncode": dep_code,
+                "overlay_dir": str(overlay_dir.relative_to(job_dir)),
+                "overlays_count": len(overlays),
+                "review_level": review_level,
+                "promotion_grade": False,
+                "dependency_prep": dep_payload,
+                "error": "sandbox_dependency_preparation_failed",
+            }
+            log.append(
+                "milestone_runner_unavailable",
+                {**payload, "outcome": "infrastructure_unavailable", "execution_reached_test_runner": False},
+            )
+            events = read_events(job_dir / "events.jsonl")
+            state = replay(events)
+            plan = materialize_plan_from_events(events, load_plan(job_dir))
+            write_json(job_dir / "plan.json", plan)
+            write_state_snapshot(job_dir / "job.json", state)
+            write_handoff(job_dir, state_to_json(state), plan)
+            print(f"Milestone runner unavailable: {milestone_id}")
+            print("Reason: sandbox_dependency_preparation_failed")
+            print(str(dep_payload.get("stderr_tail") or dep_payload.get("stdout_tail") or "")[-2000:])
+            return 2
+        if dep_vuln_policy and dep_vuln_policy.get("blocks_promotion"):
+            payload = {
+                "milestone_id": milestone_id,
+                "command": command,
+                "returncode": 2,
+                "overlay_dir": str(overlay_dir.relative_to(job_dir)),
+                "overlays_count": len(overlays),
+                "review_level": review_level,
+                "promotion_grade": False,
+                "dependency_prep": args.prepare_deps,
+                "dependency_vulnerability_policy": dep_vuln_policy,
+                "error": "dependency_vulnerability_policy_blocked",
+            }
+            log.append("milestone_runner_failed", payload)
+            events = read_events(job_dir / "events.jsonl")
+            state = replay(events)
+            plan = materialize_plan_from_events(events, load_plan(job_dir))
+            write_json(job_dir / "plan.json", plan)
+            write_state_snapshot(job_dir / "job.json", state)
+            write_handoff(job_dir, state_to_json(state), plan)
+            print(f"Milestone runner failed: {milestone_id}")
+            print("Reason: dependency_vulnerability_policy_blocked")
+            print(f"Vulnerabilities: {dep_vuln_policy.get('counts')}")
+            return 2
+
+        output_dir = runner_dir / "logs"
+        output_dir.mkdir(parents=True, exist_ok=True)
+        stdout_path = output_dir / "stdout.log"
+        stderr_path = output_dir / "stderr.log"
+        try:
+            runner_env = os.environ.copy()
+            if args.prepare_deps == "none":
+                # A gate may inspect existing dependencies, but it must not repair or install them implicitly.
+                runner_env["pnpm_config_verify_deps_before_run"] = "warn"
+            result = subprocess.run(
+                command,
+                cwd=overlay_dir,
+                shell=True,
+                text=True,
+                capture_output=True,
+                timeout=args.timeout_seconds,
+                check=False,
+                env=runner_env,
+            )
+            stdout = result.stdout or ""
+            stderr = result.stderr or ""
+            returncode = result.returncode
+            outcome, reached_test_runner, error = classify_gate_process(returncode, stdout, stderr)
+        except subprocess.TimeoutExpired as exc:
+            stdout = str(exc.stdout or "")
+            stderr = str(exc.stderr or "")
+            returncode = 124
+            outcome, reached_test_runner, error = "infrastructure_unavailable", False, "runner_timeout"
+        stdout_path.write_text(stdout, encoding="utf-8")
+        stderr_path.write_text(stderr, encoding="utf-8")
+        manifest_after_command = dependency_manifest(overlay_dir)
+        payload = {
+            "milestone_id": milestone_id,
+            "command": command,
+            "returncode": returncode,
+            "stdout": str(stdout_path.relative_to(job_dir)),
+            "stderr": str(stderr_path.relative_to(job_dir)),
+            "overlay_dir": str(overlay_dir.relative_to(job_dir)),
+            "overlays_count": len(overlays),
+            "review_level": review_level,
+            "promotion_grade": promotion_grade,
+            "dependency_prep": args.prepare_deps,
+            "dependency_auto_repair": False if args.prepare_deps == "none" else None,
+            "reused_dependency_trees": dependency_links,
+            "manifest_after_command": manifest_after_command,
+            "outcome": outcome,
+            "execution_reached_test_runner": reached_test_runner,
+        }
+        if dep_vuln_policy is not None:
+            payload["dependency_vulnerability_policy"] = dep_vuln_policy
+        if outcome == "passed":
+            log.append("milestone_runner_passed", payload)
+            code = 0
+            print(f"Milestone runner passed: {milestone_id}")
+        elif outcome == "infrastructure_unavailable":
+            log.append("milestone_runner_unavailable", {**payload, "error": error})
+            code = 3
+            print(f"Milestone runner unavailable: {milestone_id}")
+            print(f"Reason: {error}")
+            print((stderr or stdout)[-2000:])
+        else:
+            log.append("milestone_runner_failed", {**payload, "error": error})
+            code = 2
+            print(f"Milestone runner failed: {milestone_id}")
+            print(f"Reason: {error}")
+            print((stderr or stdout)[-2000:])
+
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        write_json(job_dir / "plan.json", plan)
+        write_state_snapshot(job_dir / "job.json", state)
+        write_handoff(job_dir, state_to_json(state), plan)
+        return code
+
+
+def job_run_next_main(args: argparse.Namespace) -> int:
+    project = args.project.expanduser().resolve()
+    if args.job_id:
+        job_dir = job_root(project) / args.job_id
+    else:
+        found = find_latest_incomplete_job(project)
+        if not found:
+            raise SystemExit(f"No incomplete Socra jobs found under {job_root(project)}")
+        job_dir = found
+
+    with JobLock(job_dir / ".lock"):
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        ready = ready_task_ids(plan)
+        if not ready:
+            raise SystemExit("No ready pending tasks.")
+        task_id = args.task_id or ready[0]
+        tasks = {str(task.get("id")): task for task in plan.get("tasks", [])}
+        task = tasks.get(task_id)
+        if not task:
+            raise SystemExit(f"Task not found: {task_id}")
+
+        log = JobEventLog(job_dir / "events.jsonl", state.job_id or job_dir.name)
+        creator = state.creator_config or {}
+        health = endpoint_health(str(creator.get("endpoint") or "http://127.0.0.1:11439/v1"))
+        expected_model = str(creator.get("expected_served_model_id") or Path(str(creator.get("model") or "")).name)
+        if expected_model:
+            served_ids = [str(item) for item in health.get("model_ids") or []]
+            health["expected_served_model_id"] = expected_model
+            health["model_identity_ok"] = expected_model in served_ids
+            health["served_model_ids"] = served_ids
+        log.append("creator_endpoint_health_checked", {"task_id": task_id, **health})
+        model_backed = task_id != "task-001"
+        if model_backed and (not health.get("ok") or not health.get("model_identity_ok")):
+            error = "creator_endpoint_unavailable" if not health.get("ok") else "creator_model_identity_mismatch"
+            log.append(
+                "task_blocked",
+                {
+                    "task_id": task_id,
+                    "error": error,
+                    "endpoint_health": health,
+                    "policy": "model_backed_tasks_require_live_endpoint_and_exact_model_identity",
+                },
+            )
+            events = read_events(job_dir / "events.jsonl")
+            state = replay(events)
+            plan = materialize_plan_from_events(events, load_plan(job_dir))
+            write_json(job_dir / "plan.json", plan)
+            write_state_snapshot(job_dir / "job.json", state)
+            write_handoff(job_dir, state_to_json(state), plan)
+            print(f"Blocked task: {task_id}")
+            print(f"Reason: {error}")
+            print(f"Endpoint: {health.get('url')}")
+            print(f"Error: {health.get('error')}")
+            print(f"Expected model: {health.get('expected_served_model_id')}")
+            print(f"Served models: {', '.join(health.get('served_model_ids') or []) or 'none'}")
+            return 2
+        if task_id != "task-001":
+            declared_paths = [str(path) for path in task.get("declared_files", [])]
+            if len(declared_paths) > MAX_JSON_CONTRACT_DECLARED_FILES:
+                log.append(
+                    "task_blocked",
+                    {
+                        "task_id": task_id,
+                        "error": "task_shape_requires_replan",
+                        "declared_file_count": len(declared_paths),
+                        "max_json_contract_declared_files": MAX_JSON_CONTRACT_DECLARED_FILES,
+                        "declared_files": declared_paths,
+                        "policy": "mumpix_admin_stress_v1_observed_three_file_json_contract_unreliable; split into <=2 file module tasks or single-file raw tasks",
+                    },
+                )
+                events = read_events(job_dir / "events.jsonl")
+                state = replay(events)
+                plan = materialize_plan_from_events(events, load_plan(job_dir))
+                write_json(job_dir / "plan.json", plan)
+                write_state_snapshot(job_dir / "job.json", state)
+                write_handoff(job_dir, state_to_json(state), plan)
+                print(f"Blocked task: {task_id}")
+                print("Reason: task_shape_requires_replan")
+                print(f"Declared files: {len(declared_paths)} > {MAX_JSON_CONTRACT_DECLARED_FILES}")
+                return 2
+            task_wall_start = time.monotonic()
+            attempt = int(task.get("attempt_count") or 0) + 1
+            log.append(
+                "task_started",
+                {
+                    "task_id": task_id,
+                    "attempt": attempt,
+                    "creator_config": creator,
+                    "execution_mode": "model_creator_json_contract_sandbox_only",
+                    "declared_files": task.get("declared_files", []),
+                    "prompt_layout": CREATOR_PROMPT_LAYOUT,
+                },
+            )
+            artifact_dir = job_dir / "artifacts" / "tasks" / task_id
+            artifact_dir.mkdir(parents=True, exist_ok=True)
+            effective_sources = latest_passed_artifacts_by_path(job_dir, plan)
+            file_context = read_declared_file_context(project, task, effective_sources)
+            retry_feedback = previous_attempt_feedback(job_dir, events, task_id)
+            context_sources = [
+                {
+                    "path": item.get("path"),
+                    "source": item.get("source"),
+                    "source_task_id": item.get("source_task_id"),
+                    "sandbox_path": item.get("sandbox_path"),
+                    "sha256": item.get("sha256"),
+                    "exists": item.get("exists"),
+                }
+                for item in file_context
+            ]
+            log.append(
+                "task_effective_context_resolved",
+                {
+                    "task_id": task_id,
+                    "declared_files": task.get("declared_files", []),
+                    "context_sources": context_sources,
+                    "policy": "latest_passed_sandbox_artifact_wins",
+                    "prompt_layout": CREATOR_PROMPT_LAYOUT,
+                },
+            )
+            retrieval_mode = str(task.get("retrieval_mode") or "exact")
+            if retrieval_mode == "disabled":
+                retrieval = {"status": "retrieval_disabled_control", "fired": False}
+            else:
+                retrieval = retrieve_validated_behavior(project, task)
+            recurrence = task.get("recurrence") if isinstance(task.get("recurrence"), dict) else {}
+            validated_behavior = None
+            retrieval_selection_sha256 = None
+            retrieval_fired_payload = None
+            context_budget_tokens = int(creator.get("context_budget_tokens") or 0)
+            reserved_output_tokens = int(creator.get("max_output_tokens") or 0)
+            output_contract = select_creator_output_contract(task, file_context, reserved_output_tokens)
+            log.append("creator_output_contract_selected", {"task_id": task_id, **output_contract})
+            base_messages = build_creator_messages(
+                job_dir, project, task, file_context, retry_feedback, None, output_contract
+            )
+            base_input_tokens_estimate = (len(json.dumps(base_messages, ensure_ascii=True)) + 3) // 4
+            injection_tokens_estimate = 0
+            if retrieval.get("fired"):
+                gene = retrieval.get("gene") if isinstance(retrieval.get("gene"), dict) else {}
+                validated_behavior = gene.get("preference") if isinstance(gene.get("preference"), dict) else None
+                if validated_behavior is None:
+                    raise RuntimeError("retrieval_fired_without_behavior_preference")
+                injection_tokens_estimate = (len(recurrence_canonical_json(validated_behavior)) + 3) // 4
+                budget_decision = injection_budget_decision(
+                    context_budget_tokens,
+                    reserved_output_tokens,
+                    base_input_tokens_estimate,
+                    injection_tokens_estimate,
+                )
+                if not budget_decision["fits"]:
+                    retrieval = {
+                        **retrieval,
+                        "status": "injection_budget_unavailable",
+                        "fired": False,
+                        "available_injection_tokens": budget_decision["available_injection_tokens"],
+                    }
+                    validated_behavior = None
+                else:
+                    selection = {
+                        "schema_version": 1,
+                        "task_id": task_id,
+                        "mode": retrieval_mode,
+                        "gene_id": gene.get("gene_id"),
+                        "source_central_event_sha256": retrieval.get("source_central_event_sha256"),
+                        "recurrence_key_sha256": gene.get("recurrence_key_sha256"),
+                        "preference": validated_behavior,
+                        "preference_sha256": gene.get("preference_sha256"),
+                        "injection_policy": "prefer_behavior_only_no_patch_or_source",
+                        "paired_control": "rerun the same frozen task with --retrieval disabled",
+                    }
+                    selection_path = artifact_dir / "retrieval-selection.json"
+                    write_json(selection_path, selection)
+                    retrieval_selection_sha256 = sha256_file(selection_path)
+                    retrieval_fired_payload = {
+                            "task_id": task_id,
+                            "mode": retrieval_mode,
+                            "gene_id": gene.get("gene_id"),
+                            "source_central_event_sha256": retrieval.get("source_central_event_sha256"),
+                            "recurrence_key_sha256": gene.get("recurrence_key_sha256"),
+                            "preference_sha256": gene.get("preference_sha256"),
+                            "selection": str(selection_path.relative_to(job_dir)),
+                            "selection_sha256": retrieval_selection_sha256,
+                            "injected_chars": len(recurrence_canonical_json(validated_behavior)),
+                            "injected_tokens_estimate": injection_tokens_estimate,
+                            "base_input_tokens_estimate": base_input_tokens_estimate,
+                            "context_budget_tokens": context_budget_tokens,
+                            "reserved_output_tokens": reserved_output_tokens,
+                            "input_budget_only": True,
+                            "output_cap_unchanged": True,
+                            "paired_control_supported": True,
+                    }
+            log.append(
+                "retrieval_considered",
+                {
+                    "task_id": task_id,
+                    "mode": retrieval_mode,
+                    "status": retrieval.get("status"),
+                    "fired": bool(retrieval.get("fired")),
+                    "match_count": retrieval.get("match_count"),
+                    "project_scope_id": retrieval.get("project_scope_id"),
+                    "recurrence_key_sha256": recurrence.get("recurrence_key_sha256"),
+                    "base_input_tokens_estimate": base_input_tokens_estimate,
+                    "injection_tokens_estimate": injection_tokens_estimate,
+                    "context_budget_tokens": context_budget_tokens,
+                    "reserved_output_tokens": reserved_output_tokens,
+                    "policy": "exact_key_equality_or_abstain_no_approximate_fallback",
+                },
+            )
+            if retrieval_fired_payload:
+                log.append("retrieval_fired", retrieval_fired_payload)
+            messages = (
+                build_creator_messages(
+                    job_dir, project, task, file_context, retry_feedback, validated_behavior, output_contract
+                )
+                if validated_behavior
+                else base_messages
+            )
+            allowed = declared_file_set(task)
+            response_schema = (
+                anchored_edit_response_schema(allowed, int(output_contract.get("max_edits") or MAX_ANCHORED_EDITS))
+                if output_contract.get("mode") == "anchored_edits"
+                else None
+            )
+            response_schema_sha256 = recurrence_sha256_json(response_schema) if response_schema is not None else None
+            request_path = artifact_dir / "creator-request.json"
+            request_path.write_text(
+                json.dumps(
+                    {
+                        "messages": messages,
+                        "structured_output": (
+                            {
+                                "mode": "json_schema",
+                                "schema": response_schema,
+                                "schema_sha256": response_schema_sha256,
+                                "transport": "llama_cpp_response_format_json_object_schema",
+                                "thinking_disabled": True,
+                            }
+                            if response_schema is not None
+                            else None
+                        ),
+                    },
+                    indent=2,
+                )
+                + "\n",
+                encoding="utf-8",
+            )
+            log.append(
+                "creator_request_written",
+                {
+                    "task_id": task_id,
+                    "path": str(request_path.relative_to(job_dir)),
+                    "sha256": sha256_file(request_path),
+                    "declared_files": task.get("declared_files", []),
+                    "context_sources": context_sources,
+                    "retry_feedback_count": len(retry_feedback),
+                    "retrieval_status": retrieval.get("status"),
+                    "retrieval_fired": bool(retrieval.get("fired")),
+                    "retrieval_selection_sha256": retrieval_selection_sha256,
+                    "prompt_layout": CREATOR_PROMPT_LAYOUT,
+                    "structured_output_mode": "json_schema" if response_schema is not None else None,
+                    "structured_output_schema_sha256": response_schema_sha256,
+                    "structured_output_transport": (
+                        "llama_cpp_response_format_json_object_schema" if response_schema is not None else None
+                    ),
+                    "thinking_disabled_for_schema": response_schema is not None,
+                },
+            )
+
+            creator_call_ms = 0
+            creator_call_start = None
+            try:
+                creator_call_start = time.monotonic()
+                response = call_creator_model(
+                    creator,
+                    messages,
+                    json_mode=output_contract.get("mode") == "anchored_edits" or len(allowed) != 1,
+                    response_schema=response_schema,
+                )
+                creator_call_ms = elapsed_ms(creator_call_start)
+            except Exception as exc:  # noqa: BLE001 - local model failures are durable task failures.
+                if creator_call_start is not None:
+                    creator_call_ms = elapsed_ms(creator_call_start)
+                log.append(
+                    "task_failed",
+                    attempt_failure_payload(AttemptFailure.ENDPOINT_ERROR, **{
+                        "task_id": task_id,
+                        "error": "creator_call_failed",
+                        "message": str(exc),
+                        "attempt": attempt,
+                        "task_wall_ms": elapsed_ms(task_wall_start),
+                        "creator_call_ms": creator_call_ms,
+                    }),
+                )
+                events = read_events(job_dir / "events.jsonl")
+                state = replay(events)
+                plan = materialize_plan_from_events(events, load_plan(job_dir))
+                write_json(job_dir / "plan.json", plan)
+                write_state_snapshot(job_dir / "job.json", state)
+                write_handoff(job_dir, state_to_json(state), plan)
+                print(f"Failed task: {task_id}")
+                print(f"Reason: creator_call_failed")
+                print(str(exc))
+                return 2
+
+            response_path = artifact_dir / "creator-response.json"
+            response_path.write_text(json.dumps(response, indent=2) + "\n", encoding="utf-8")
+            allowed = declared_file_set(task)
+            parser_repair: dict[str, Any] | None = None
+            try:
+                creator_payload, parser_repair = parse_creator_json_with_repair(str(response.get("content") or ""))
+                if output_contract.get("mode") == "anchored_edits":
+                    anchored_payload = artifact_dir / "creator-anchored-edits.json"
+                    anchored_payload.write_text(json.dumps(creator_payload, indent=2) + "\n", encoding="utf-8")
+                    creator_payload, anchored_metadata = materialize_anchored_edits(creator_payload, file_context, allowed)
+                    output_mode = "anchored_edit_json"
+                    log.append(
+                        "creator_anchored_edits_materialized",
+                        {
+                            "task_id": task_id,
+                            "path": str(anchored_payload.relative_to(job_dir)),
+                            "sha256": sha256_file(anchored_payload),
+                            "edit_count": len(anchored_metadata),
+                            "edits": anchored_metadata,
+                            "policy": "exact_unique_nonoverlapping_anchors_fail_closed",
+                        },
+                    )
+                else:
+                    if "edits" in creator_payload and "files" not in creator_payload:
+                        raise ValueError("creator_output_contract_violation: full replacement mode requires files")
+                    output_mode = "json_contract"
+            except ValueError as exc:
+                repaired_payload = (
+                    coerce_single_file_creator_output(str(response.get("content") or ""), allowed)
+                    if output_contract.get("mode") != "anchored_edits"
+                    else None
+                )
+                if repaired_payload is not None:
+                    creator_payload, output_mode = repaired_payload
+                    parser_repair = {"applied": True, "types": ["single_declared_file_raw_code_output_wrapped_as_json"]}
+                    log.append(
+                        "creator_output_repaired",
+                        {
+                            "task_id": task_id,
+                            "attempt": attempt,
+                            "reason": "single_declared_file_raw_code_output_wrapped_as_json",
+                            "original_error": str(exc),
+                            "path": next(iter(allowed)),
+                            "output_mode": output_mode,
+                            "response_path": str(response_path.relative_to(job_dir)),
+                        },
+                    )
+                else:
+                    log.append(
+                        "creator_output_received",
+                        {
+                            "task_id": task_id,
+                            "path": str(response_path.relative_to(job_dir)),
+                            "sha256": sha256_file(response_path),
+                            "request_model": response.get("request_model"),
+                            "response_model": response.get("response_model"),
+                            "content_sha256": sha256_text(str(response.get("content") or "")),
+                            "content_chars": len(str(response.get("content") or "")),
+                            "reasoning_chars": len(str(response.get("reasoning_content") or "")),
+                            "finish_reason": response.get("finish_reason"),
+                            "usage": response.get("usage") if isinstance(response.get("usage"), dict) else {},
+                            "request_max_tokens": response.get("request_max_tokens"),
+                            "request_temperature": response.get("request_temperature"),
+                            "json_mode": response.get("json_mode"),
+                            "structured_output_mode": response.get("structured_output_mode"),
+                            "structured_output_schema_sha256": response.get("structured_output_schema_sha256"),
+                            "structured_output_transport": response.get("structured_output_transport"),
+                            "thinking_disabled_for_schema": response.get("thinking_disabled_for_schema"),
+                            "creator_call_ms": creator_call_ms,
+                            "prompt_layout": CREATOR_PROMPT_LAYOUT,
+                            "parser_repair_applied": False,
+                            "parser_repair": None,
+                        },
+                    )
+                    log.append(
+                        "task_failed",
+                        attempt_failure_payload(
+                            classify_creator_finish(str(response.get("finish_reason") or "")) or AttemptFailure.MALFORMED_OUTPUT,
+                            **{
+                            "task_id": task_id,
+                            "error": "creator_output_malformed",
+                            "message": str(exc),
+                            "attempt": attempt,
+                            "response_path": str(response_path.relative_to(job_dir)),
+                            "content_chars": len(str(response.get("content") or "")),
+                            "reasoning_chars": len(str(response.get("reasoning_content") or "")),
+                            "finish_reason": response.get("finish_reason"),
+                            "task_wall_ms": elapsed_ms(task_wall_start),
+                            "creator_call_ms": creator_call_ms,
+                            },
+                        ),
+                    )
+                    events = read_events(job_dir / "events.jsonl")
+                    state = replay(events)
+                    plan = materialize_plan_from_events(events, load_plan(job_dir))
+                    write_json(job_dir / "plan.json", plan)
+                    write_state_snapshot(job_dir / "job.json", state)
+                    write_handoff(job_dir, state_to_json(state), plan)
+                    print(f"Failed task: {task_id}")
+                    print("Reason: creator_output_malformed")
+                    print(str(exc))
+                    return 2
+
+            log.append(
+                "creator_output_received",
+                {
+                    "task_id": task_id,
+                    "path": str(response_path.relative_to(job_dir)),
+                    "sha256": sha256_file(response_path),
+                    "request_model": response.get("request_model"),
+                    "response_model": response.get("response_model"),
+                    "content_sha256": sha256_text(str(response.get("content") or "")),
+                    "content_chars": len(str(response.get("content") or "")),
+                    "reasoning_chars": len(str(response.get("reasoning_content") or "")),
+                    "finish_reason": response.get("finish_reason"),
+                    "usage": response.get("usage") if isinstance(response.get("usage"), dict) else {},
+                    "request_max_tokens": response.get("request_max_tokens"),
+                    "request_temperature": response.get("request_temperature"),
+                    "json_mode": response.get("json_mode"),
+                    "structured_output_mode": response.get("structured_output_mode"),
+                    "structured_output_schema_sha256": response.get("structured_output_schema_sha256"),
+                    "structured_output_transport": response.get("structured_output_transport"),
+                    "thinking_disabled_for_schema": response.get("thinking_disabled_for_schema"),
+                    "creator_call_ms": creator_call_ms,
+                    "prompt_layout": CREATOR_PROMPT_LAYOUT,
+                    "parser_repair_applied": bool(parser_repair),
+                    "parser_repair": parser_repair,
+                },
+            )
+
+            creator_payload, hygiene_changes = preserve_existing_final_newlines(creator_payload, file_context)
+            if hygiene_changes:
+                log.append(
+                    "creator_output_hygiene_normalized",
+                    {
+                        "task_id": task_id,
+                        "changes": hygiene_changes,
+                        "semantic_repair": False,
+                        "policy": "deterministic_existing_file_byte_hygiene_only",
+                    },
+                )
+
+            parsed_path = artifact_dir / "creator-output-parsed.json"
+            parsed_path.write_text(json.dumps(creator_payload, indent=2) + "\n", encoding="utf-8")
+            violations = validate_creator_declared_files(creator_payload, allowed)
+            if violations:
+                log.append(
+                    "declared_file_violation",
+                    {
+                        "task_id": task_id,
+                        "attempt": attempt,
+                        "violations": violations,
+                        "allowed_declared_files": sorted(allowed),
+                        "parsed_output": str(parsed_path.relative_to(job_dir)),
+                    },
+                )
+                log.append(
+                    "task_failed",
+                    attempt_failure_payload(AttemptFailure.MALFORMED_OUTPUT, **{
+                        "task_id": task_id,
+                        "error": "declared_file_violation",
+                        "violations": violations,
+                        "attempt": attempt,
+                        "task_wall_ms": elapsed_ms(task_wall_start),
+                        "creator_call_ms": creator_call_ms,
+                    }),
+                )
+                events = read_events(job_dir / "events.jsonl")
+                state = replay(events)
+                plan = materialize_plan_from_events(events, load_plan(job_dir))
+                write_json(job_dir / "plan.json", plan)
+                write_state_snapshot(job_dir / "job.json", state)
+                write_handoff(job_dir, state_to_json(state), plan)
+                print(f"Failed task: {task_id}")
+                print("Reason: declared_file_violation")
+                print(f"Violations: {', '.join(violations)}")
+                return 2
+
+            sandbox_dir, written = atomic_write_creator_sandbox(job_dir, task_id, creator_payload)
+            log.append(
+                "task_artifacts",
+                {
+                    "task_id": task_id,
+                    "artifacts": [
+                        {
+                            "sandbox_path": str((sandbox_dir / row["path"]).relative_to(job_dir)),
+                            **{key: value for key, value in row.items() if key != "absolute_path"},
+                        }
+                        for row in written
+                    ],
+                    "sandbox_dir": str(sandbox_dir.relative_to(job_dir)),
+                    "parsed_output": str(parsed_path.relative_to(job_dir)),
+                    "output_mode": output_mode,
+                    "parser_repair_applied": bool(parser_repair),
+                    "parser_repair": parser_repair,
+                },
+            )
+            review_ok, review_errors, review_level, regression_checks, infrastructure_errors = review_creator_sandbox(
+                project, task, written, output_mode, file_context, job_dir
+            )
+            log.append(
+                "review_completed",
+                {
+                    "task_id": task_id,
+                    "ok": review_ok,
+                    "errors": review_errors,
+                    "reviewer": "static_sandbox_artifact_contract_v1",
+                    "review_level": review_level,
+                    "output_mode": output_mode,
+                    "regression_checks": regression_checks,
+                    "infrastructure_errors": infrastructure_errors,
+                    "outcome": "infrastructure_unavailable" if infrastructure_errors else ("passed" if review_ok else "failed"),
+                },
+            )
+            if infrastructure_errors:
+                log.append(
+                    "task_blocked",
+                    {
+                        "task_id": task_id,
+                        "error": "static_checker_unavailable",
+                        "infrastructure_errors": infrastructure_errors,
+                        "attempt": attempt,
+                        "task_wall_ms": elapsed_ms(task_wall_start),
+                        "creator_call_ms": creator_call_ms,
+                        "policy": "a checker that cannot run is infrastructure-unavailable, not evidence that the patch failed",
+                    },
+                )
+                events = read_events(job_dir / "events.jsonl")
+                state = replay(events)
+                plan = materialize_plan_from_events(events, load_plan(job_dir))
+                write_json(job_dir / "plan.json", plan)
+                write_state_snapshot(job_dir / "job.json", state)
+                write_handoff(job_dir, state_to_json(state), plan)
+                print(f"Blocked task: {task_id}")
+                print("Reason: static_checker_unavailable")
+                print("; ".join(infrastructure_errors))
+                return 2
+            if not review_ok:
+                log.append(
+                    "task_failed",
+                    attempt_failure_payload(AttemptFailure.GATE_FAILED, **{
+                        "task_id": task_id,
+                        "error": "review_failed",
+                        "review_errors": review_errors,
+                        "attempt": attempt,
+                        "task_wall_ms": elapsed_ms(task_wall_start),
+                        "creator_call_ms": creator_call_ms,
+                    }),
+                )
+                events = read_events(job_dir / "events.jsonl")
+                state = replay(events)
+                plan = materialize_plan_from_events(events, load_plan(job_dir))
+                write_json(job_dir / "plan.json", plan)
+                write_state_snapshot(job_dir / "job.json", state)
+                write_handoff(job_dir, state_to_json(state), plan)
+                print(f"Failed task: {task_id}")
+                print("Reason: review_failed")
+                print("; ".join(review_errors))
+                return 2
+
+            checkpoint_dir = job_dir / "checkpoints" / task_id
+            checkpoint_dir.mkdir(parents=True, exist_ok=True)
+            checkpoint_manifest = {
+                "task_id": task_id,
+                "mode": "model_creator_json_contract_sandbox_only",
+                "output_mode": output_mode,
+                "review_level": review_level,
+                "sandbox_dir": str(sandbox_dir.relative_to(job_dir)),
+                "declared_files": sorted(allowed),
+                "artifacts": [{key: value for key, value in row.items() if key != "absolute_path"} for row in written],
+                "creator_response": str(response_path.relative_to(job_dir)),
+                "creator_output": str(parsed_path.relative_to(job_dir)),
+                "parser_repair_applied": bool(parser_repair),
+                "parser_repair": parser_repair,
+            }
+            write_json(checkpoint_dir / "manifest.json", checkpoint_manifest)
+            log.append("checkpoint_written", {"task_id": task_id, "path": str((checkpoint_dir / "manifest.json").relative_to(job_dir)), "sha256": sha256_file(checkpoint_dir / "manifest.json")})
+            log.append(
+                "task_passed",
+                {
+                    "task_id": task_id,
+                    "acceptance": task.get("acceptance", []),
+                    "notes": "Creator output parsed or safely repaired, stayed within declared files, passed reviewer checks, and was written atomically to the job sandbox. No project source promotion was performed.",
+                    "output_mode": output_mode,
+                    "review_level": review_level,
+                    "sandbox_dir": str(sandbox_dir.relative_to(job_dir)),
+                    "task_wall_ms": elapsed_ms(task_wall_start),
+                    "creator_call_ms": creator_call_ms,
+                    "prompt_layout": CREATOR_PROMPT_LAYOUT,
+                    "parser_repair_applied": bool(parser_repair),
+                    "parser_repair": parser_repair,
+                },
+            )
+
+            events = read_events(job_dir / "events.jsonl")
+            state = replay(events)
+            plan = materialize_plan_from_events(events, load_plan(job_dir))
+            write_json(job_dir / "plan.json", plan)
+            write_state_snapshot(job_dir / "job.json", state)
+            write_handoff(job_dir, state_to_json(state), plan)
+
+            print(f"Ran task: {task_id}")
+            print("Execution mode: model_creator_json_contract_sandbox_only")
+            print(f"Endpoint health: {'ok' if health.get('ok') else 'unavailable'}")
+            print(f"Sandbox artifacts: {sandbox_dir}")
+            print(f"Files written: {len(written)}")
+            print(f"Ready tasks now: {', '.join(ready_task_ids(plan)[:8]) or 'none'}")
+            return 0
+
+        log.append(
+            "task_started",
+            {
+                "task_id": task_id,
+                "attempt": int(task.get("attempt_count") or 0) + 1,
+                "creator_config": creator,
+                "execution_mode": "deterministic_terminal_inventory_no_model_call",
+            },
+        )
+        artifact_dir = job_dir / "artifacts" / "tasks" / task_id
+        artifacts = inventory_declared_files(project, task, artifact_dir)
+        log.append("task_artifacts", {"task_id": task_id, "artifacts": artifacts})
+        checkpoint_dir = job_dir / "checkpoints" / task_id
+        checkpoint_dir.mkdir(parents=True, exist_ok=True)
+        checkpoint_manifest = {
+            "task_id": task_id,
+            "declared_files": [
+                {
+                    "path": rel,
+                    "sha256": sha256_file(project / rel) if (project / rel).exists() and (project / rel).is_file() else None,
+                }
+                for rel in task.get("declared_files", [])
+            ],
+            "artifacts": artifacts,
+        }
+        write_json(checkpoint_dir / "manifest.json", checkpoint_manifest)
+        log.append("checkpoint_written", {"task_id": task_id, "path": str((checkpoint_dir / "manifest.json").relative_to(job_dir)), "sha256": sha256_file(checkpoint_dir / "manifest.json")})
+        log.append(
+            "task_passed",
+            {
+                "task_id": task_id,
+                "acceptance": task.get("acceptance", []),
+                "notes": "Inventory completed from declared files. No project source edits were made.",
+            },
+        )
+
+        events = read_events(job_dir / "events.jsonl")
+        state = replay(events)
+        plan = materialize_plan_from_events(events, load_plan(job_dir))
+        write_json(job_dir / "plan.json", plan)
+        write_state_snapshot(job_dir / "job.json", state)
+        write_handoff(job_dir, state_to_json(state), plan)
+
+    print(f"Ran task: {task_id}")
+    print(f"Execution mode: deterministic_terminal_inventory_no_model_call")
+    print(f"Endpoint health: {'ok' if health.get('ok') else 'unavailable'}")
+    print(f"Artifacts: {artifact_dir}")
+    print(f"Ready tasks now: {', '.join(ready_task_ids(plan)[:8]) or 'none'}")
+    return 0