okstra 0.76.0 → 0.78.0

package/runtime/python/okstra_ctl/render.py

@@ -28,6 +28,7 @@ from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
 # render_task_manifest 가 동일한 리스트/딕셔너리를 로컬에 중복 정의했는데,
 # 이는 silent drift 위험이 있어 SSOT import 로 통합한다.
 from . import fix_cycles
+from .lead_runtime import lead_runtime_info
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
 
@@ -66,6 +67,30 @@ def _write_json(path: Path, payload: dict) -> None:
     _write_text(path, json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
 
 
+def _lead_runtime(ctx: dict) -> str:
+    return ctx.get("LEAD_RUNTIME", "") or "claude-code"
+
+
+def _lead_info(ctx: dict):
+    return lead_runtime_info(_lead_runtime(ctx))
+
+
+def _lead_agent(ctx: dict) -> str:
+    return _lead_info(ctx).agent
+
+
+def _lead_agent_label(ctx: dict) -> str:
+    return _lead_info(ctx).agent_label
+
+
+def _lead_role(ctx: dict) -> str:
+    return _lead_info(ctx).role
+
+
+def _lead_adapter(ctx: dict) -> dict:
+    return _lead_info(ctx).adapter_payload()
+
+
 _PHASE_BLOCK_RE = re.compile(
     r"\{% if header\.taskType == '(implementation-planning|release-handoff|implementation|final-verification)' %\}\n(.*?)\{% endif %\}\n",
     re.DOTALL,
@@ -415,11 +440,14 @@ def render_team_state(team_state_path: str, ctx: dict) -> None:
         "schemaVersion": "1.0",
         "taskKey": ctx.get("TASK_KEY", ""),
         "taskType": ctx.get("TASK_TYPE", ""),
+        "leadRuntime": _lead_runtime(ctx),
+        "leadAdapter": _lead_adapter(ctx),
+        "leadEventsPath": ctx.get("LEAD_EVENTS_RELATIVE_PATH", ""),
         "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
         "workflowState": ctx.get("CURRENT_RUN_STATUS", ""),
         "lead": {
-            "role": "Claude lead",
-            "agent": "claude",
+            "role": _lead_role(ctx),
+            "agent": _lead_agent(ctx),
             "model": ctx.get("LEAD_MODEL", ""),
             "modelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
             "status": ctx.get("CURRENT_RUN_STATUS", ""),
@@ -876,7 +904,9 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
     catalog = _worker_catalog(ctx)
     required_worker_roles = _required_worker_roles(ctx, reviewers)
     worker_prompt_paths = {item: catalog[item]["promptPath"] for item in reviewers}
-    required_agent_status_entries = ["Claude lead"] + [
+    lead_agent = _lead_agent(ctx)
+    lead_role = _lead_role(ctx)
+    required_agent_status_entries = [lead_role] + [
         catalog[item]["role"] for item in reviewers
     ]
     related_tasks = json.loads(ctx.get("RELATED_TASKS_JSON", "[]"))
@@ -925,6 +955,8 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "taskIdPathSegment": ctx.get("TASK_ID_SEGMENT", ""),
         "projectRoot": ctx.get("PROJECT_ROOT", ""),
         "taskType": ctx.get("TASK_TYPE", ""),
+        "leadRuntime": _lead_runtime(ctx),
+        "leadAdapter": _lead_adapter(ctx),
         "workCategory": work_category,
         "taskBriefPath": ctx.get("BRIEF_RELATIVE_PATH", ""),
         "recommendedWorkers": reviewers,
@@ -984,16 +1016,17 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
             "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
             "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
             "activeRunContextPath": ctx.get("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", ""),
+            "leadEventsPath": ctx.get("LEAD_EVENTS_RELATIVE_PATH", ""),
             "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
             "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
         },
         "resultContract": {
-            "leadAgent": "claude",
-            "leadRole": "Claude lead",
+            "leadAgent": lead_agent,
+            "leadRole": lead_role,
             "leadModel": ctx.get("LEAD_MODEL", ""),
             "leadModelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
             "leadExecutionMode": "synthesis-only",
-            "finalSynthesisOwner": "Claude lead",
+            "finalSynthesisOwner": lead_role,
             "artifactFirst": True,
             "resultCollectionMode": "claude-managed",
             "finalReportFormat": "markdown",
@@ -1127,6 +1160,8 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
     catalog = _worker_catalog(ctx)
     required_worker_roles = _required_worker_roles(ctx, reviewers)
     worker_prompt_paths = {item: catalog[item]["promptPath"] for item in reviewers}
+    lead_agent = _lead_agent(ctx)
+    lead_role = _lead_role(ctx)
     related_tasks = json.loads(ctx.get("RELATED_TASKS_JSON", "[]"))
     workflow = (
         task_manifest.get("workflow", {})
@@ -1149,6 +1184,8 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "taskId": ctx.get("TASK_ID", ""),
         "taskKey": ctx.get("TASK_KEY", ""),
         "taskType": ctx.get("TASK_TYPE", ""),
+        "leadRuntime": _lead_runtime(ctx),
+        "leadAdapter": _lead_adapter(ctx),
         "workCategory": task_manifest.get(
             "workCategory", ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")
         ),
@@ -1174,6 +1211,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             "workerResults": ctx.get("WORKER_RESULTS_SEQ", ""),
         },
         "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
+        "leadEventsPath": ctx.get("LEAD_EVENTS_RELATIVE_PATH", ""),
         "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
         "workerPromptsDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
         "workerPromptPathByWorkerId": worker_prompt_paths,
@@ -1216,15 +1254,15 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             "lastSafeCheckpoint": workflow.get("lastSafeCheckpoint", {}),
         },
         "teamContract": {
-            "leadAgent": "claude",
-            "leadRole": "Claude lead",
+            "leadAgent": lead_agent,
+            "leadRole": lead_role,
             "leadModel": ctx.get("LEAD_MODEL", ""),
             "leadModelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
             "leadExecutionMode": "synthesis-only",
-            "finalSynthesisOwner": "Claude lead",
+            "finalSynthesisOwner": lead_role,
             "requiredWorkerAttempts": reviewers,
             "requiredWorkerRoles": required_worker_roles,
-            "requiredAgentStatusEntries": ["Claude lead"]
+            "requiredAgentStatusEntries": [lead_role]
             + [catalog[item]["role"] for item in reviewers],
             "requireDistinctLeadFromClaudeWorker": True,
             "requireAllRequiredWorkerAttempts": True,
@@ -1425,6 +1463,12 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         if isinstance(task_manifest.get("artifacts"), dict)
         else {}
     )
+    lead_role = rc.get("leadRole", _lead_role(ctx))
+    latest_resume_command = (
+        task_manifest.get("latestResumeCommandPath")
+        or ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", "")
+        or "--"
+    )
     mapping = {
         "{{TASK_KEY}}": task_manifest.get("taskKey", ctx.get("TASK_KEY", "")),
         "{{TASK_TYPE}}": task_manifest.get("taskType", ctx.get("TASK_TYPE", "")),
@@ -1456,13 +1500,10 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         "{{VALIDATION_STATUS}}": cv.get(
             "status", ctx.get("VALIDATION_STATUS", "not-run")
         ),
-        "{{CLAUDE_RESUME_COMMAND_RELATIVE_PATH}}": task_manifest.get(
-            "latestResumeCommandPath",
-            ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
-        ),
+        "{{CLAUDE_RESUME_COMMAND_RELATIVE_PATH}}": latest_resume_command,
         "{{MODEL_ASSIGNMENT_LINES}}": "\n".join(
             [
-                f"- `Claude lead`: `{rc.get('leadModel', ctx.get('LEAD_MODEL', ''))}`",
+                f"- `{lead_role}`: `{rc.get('leadModel', ctx.get('LEAD_MODEL', ''))}`",
                 f"- `Claude worker`: `{ctx.get('CLAUDE_WORKER_MODEL', '')}`",
                 f"- `Codex worker`: `{ctx.get('CODEX_WORKER_MODEL', '')}`",
                 f"- `Gemini worker`: `{ctx.get('GEMINI_WORKER_MODEL', '')}`",
@@ -1597,22 +1638,22 @@ def build_available_mcp_servers_block(project_root: Path) -> str:
 
 
 def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
-    """Populate ctx in-place with the 9 derived lead-prompt tokens.
+    """Populate ctx in-place with derived lead-prompt tokens.
 
-    Tokens that are not 1:1 with a ctx key (TEAM_CREATION_GATE,
-    WORKER_RESULT_PATH_LINES, TEAM_ROLE_LINES, MODEL_ASSIGNMENT_LINES,
-    REQUIRED_WORKER_ROLE_SENTENCE, GEMINI_ATTEMPT_SENTENCE,
-    PREFERRED_WORKER_RESULTS_SENTENCE, EXECUTION_STATUS_EXACT_ENTRIES,
-    EXECUTION_STATUS_TABLE_ROWS) are computed deterministically from ctx
-    so the pure-lookup renderer (`render_template_with_ctx`) can resolve
-    them via plain `ctx[token]` lookup.
+    Tokens that are not 1:1 with a ctx key (TEAM_CREATION_GATE, lead identity
+    blocks, worker dispatch guidance, worker result/status summaries, etc.) are
+    computed deterministically from ctx so the pure-lookup renderer
+    (`render_template_with_ctx`) can resolve them via plain `ctx[token]` lookup.
 
-    Always overwrites — caller-supplied values for these 9 keys are replaced
+    Always overwrites — caller-supplied values for these computed keys are replaced
     on every call. For optional defaults (VALIDATION_STATUS etc.) use the
     companion `apply_lead_prompt_defaults` which preserves caller values.
     """
     selected = _resolve_workers(ctx)
     catalog = _worker_catalog(ctx)
+    lead_runtime = _lead_runtime(ctx)
+    lead_role = _lead_role(ctx)
+    lead_agent_label = _lead_agent_label(ctx)
     lead_model = ctx.get("LEAD_MODEL", "")
     lead_model_execution = ctx.get("LEAD_MODEL_EXECUTION_VALUE", "")
 
@@ -1622,16 +1663,16 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         return f"- `{role}`: `{model}`"
 
     worker_result_lines: list[str] = []
-    team_role_lines = [f"  1. `Claude lead` (assigned model: `{lead_model}`)"]
+    team_role_lines = [f"  1. `{lead_role}` (assigned model: `{lead_model}`)"]
     model_assignment_lines = [
-        fmt_assignment("Claude lead", lead_model, lead_model_execution)
+        fmt_assignment(lead_role, lead_model, lead_model_execution)
     ]
     worker_role_labels: list[str] = []
-    execution_status_entries = ["`Claude lead`"]
+    execution_status_entries = [f"`{lead_role}`"]
     execution_status_table_lines = [
         "| 에이전트 | 역할 | 모델 | 상태 | 핵심 발견 요약 |",
         "|----------|------|------|------|----------------|",
-        f"| Claude Code | Claude lead | {lead_model} | completed / timeout / error / not-run | 최종 synthesis 작성 상태와 핵심 판단 |",
+        f"| {lead_agent_label} | {lead_role} | {lead_model} | completed / timeout / error / not-run | 최종 synthesis 작성 상태와 핵심 판단 |",
     ]
     for index, worker in enumerate(selected, start=2):
         m = catalog[worker]
@@ -1682,18 +1723,81 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     # - All other phases keep the full team-creation contract.
     task_type = ctx.get("TASK_TYPE", "")
     concurrent_stages = str(ctx.get("CONCURRENT_RUN_STAGES", "") or "").strip()
+    codex_dispatch_command = (
+        "okstra codex-dispatch "
+        f"--project-root {ctx.get('PROJECT_ROOT', '')} "
+        f"--run-manifest {ctx.get('RUN_MANIFEST_RELATIVE_PATH', '')}"
+    )
+    team_dispatch_command = (
+        "okstra team dispatch "
+        f"--project-root {ctx.get('PROJECT_ROOT', '')} "
+        f"--run-manifest {ctx.get('RUN_MANIFEST_RELATIVE_PATH', '')}"
+    )
+    team_await_command = (
+        "okstra team await "
+        f"--project-root {ctx.get('PROJECT_ROOT', '')} "
+        f"--run-manifest {ctx.get('RUN_MANIFEST_RELATIVE_PATH', '')}"
+    )
     if task_type == "release-handoff" or not selected:
         team_creation_gate_block = (
             "## Single-Lead Phase (no team creation)\n"
             "\n"
             "This run is single-lead. There is no worker roster, no\n"
             "`TeamCreate` call, no `Agent(...)` worker dispatch, and no\n"
-            "convergence loop. The Claude lead performs every step inline\n"
+            f"convergence loop. The {lead_role} performs every step inline\n"
             "(reading inputs, drafting commit / PR text when applicable,\n"
             "asking the user, running git / gh, and writing the final\n"
             "report). Do NOT call `TeamCreate` or dispatch any sub-agent\n"
             "from this run — that would be a contract violation."
         )
+    elif lead_runtime == "codex":
+        team_creation_gate_block = (
+            "## Codex Dispatch Gate (BLOCKING)\n"
+            "\n"
+            "This run was prepared for `leadRuntime=codex`. Do NOT call\n"
+            "`TeamCreate`, do NOT call Claude Code `Agent(...)`, and do NOT\n"
+            "invoke Claude slash skills. Codex dispatch is artifact-first and\n"
+            "uses the prepared run manifest plus CLI-backed worker wrappers.\n"
+            "\n"
+            "Required actions, in order:\n"
+            "\n"
+            "1. Inspect the run manifest and team-state paths listed below.\n"
+            "2. Emit `PROGRESS: phase-3-team-create skipped (codex-dispatch)`;\n"
+            "   there is no Claude Teams surface in this adapter.\n"
+            "3. Plan worker execution with:\n"
+            f"   `{codex_dispatch_command} --dry-run`\n"
+            "4. Dispatch supported Codex-side workers with:\n"
+            f"   `{codex_dispatch_command}`\n"
+            "   When `--workers` is omitted, unsupported roster entries such as\n"
+            "   `claude` are skipped with explicit `not-run` reasons.\n"
+            "5. Run `report-writer` only with explicit opt-in:\n"
+            f"   `{codex_dispatch_command} --enable-codex-report-writer --report-writer-codex-model <model>`\n"
+            "\n"
+            "`okstra codex-dispatch` records `team-state.dispatchMode`, writes\n"
+            "worker prompt histories when missing, persists worker results, and\n"
+            "runs post-report validation for the Codex report-writer path."
+        )
+    elif lead_runtime == "external":
+        team_creation_gate_block = (
+            "## Tmux Worker Dispatch Gate (BLOCKING)\n"
+            "\n"
+            "This run was prepared for `leadRuntime=external`. Do NOT call "
+            "`TeamCreate`, do NOT call Claude Code `Agent(...)`, and do NOT call "
+            "`okstra codex-dispatch`. This adapter dispatches workers through "
+            "okstra-owned tmux panes.\n"
+            "\n"
+            "Required actions, in order:\n"
+            "1. Inspect the run manifest and team-state paths listed below.\n"
+            "2. Emit `PROGRESS: phase-3-team-create skipped (tmux-pane)`; there is no Claude Teams surface in this adapter.\n"
+            "3. Plan worker execution with:\n"
+            f"   `{team_dispatch_command} --dry-run`\n"
+            "4. Dispatch workers with:\n"
+            f"   `{team_dispatch_command}`\n"
+            "5. Arm one background wait using this harness's async shell primitive:\n"
+            f"   `{team_await_command}`\n"
+            "6. On wake, read team-state. Worker completion is valid only from "
+            "`workerDispatches[]` plus result files; pane creation alone is not completion."
+        )
     elif task_type == "implementation" and concurrent_stages:
         team_creation_gate_block = (
             "## Concurrent-run: no-team background (BLOCKING)\n"
@@ -1773,8 +1877,86 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "response is to go back to step 2 — NOT to strip `team_name` and retry."
         )
 
+    if lead_runtime == "external":
+        lead_intro_line = f"You are `{lead_role}` for project `{ctx.get('PROJECT_ID', '')}`."
+        lead_bootstrap_instruction = (
+            "Read the manifests below for all task metadata, paths, model "
+            "assignments, and worker roster. Use the tmux worker dispatch gate "
+            "in this prompt; do not invoke Claude Code skills."
+        )
+        lead_session_block = (
+            "## Session\n"
+            "\n"
+            "- Lead runtime: `external`\n"
+            "- Lead session accounting: artifact-only; this harness does not expose Claude Code jsonl session IDs."
+        )
+        worker_dispatch_guidance = (
+            "## Tmux Worker Dispatch\n"
+            "\n"
+            "- Worker prompt paths in `task-manifest.json` are assigned history "
+            "locations. `okstra team dispatch` materializes missing prompt files "
+            "from the run manifest and active-run-context; existing prompt files "
+            "are never overwritten.\n"
+            "- Do not call `TeamCreate`, `Agent(...)`, or `okstra codex-dispatch`. "
+            "Use `okstra team dispatch` and `okstra team await` from the gate "
+            "above for worker execution.\n"
+            "- File presence is not a signal to skip. Worker selection and skipped "
+            "statuses come from `team-state`, never from the prompts directory."
+        )
+    elif lead_runtime == "codex":
+        lead_intro_line = f"You are `{lead_role}` for project `{ctx.get('PROJECT_ID', '')}`."
+        lead_bootstrap_instruction = (
+            "Read the manifests below for all task metadata, paths, model "
+            "assignments, and worker roster. Use the Codex dispatch gate in this "
+            "prompt; do not invoke Claude Code skills."
+        )
+        lead_session_block = (
+            "## Session\n"
+            "\n"
+            "- Lead runtime: `codex`\n"
+            "- Codex run resume is artifact/checkpoint based; `okstra codex-run` "
+            "does not create a Claude session id."
+        )
+        worker_dispatch_guidance = (
+            "## Codex Worker Dispatch\n"
+            "\n"
+            "- Worker prompt paths in `task-manifest.json` are assigned history "
+            "locations. `okstra codex-dispatch` materializes missing prompt files "
+            "from the run manifest and active-run-context; existing prompt files "
+            "are never overwritten.\n"
+            "- Do not call `TeamCreate` or `Agent(...)`. Use the command in the "
+            "Codex Dispatch Gate above for worker execution.\n"
+            "- File presence is not a signal to skip. Worker selection and skipped "
+            "statuses come from `team-state`, never from the prompts directory."
+        )
+    else:
+        lead_intro_line = f"You are `{lead_role}` for project `{ctx.get('PROJECT_ID', '')}`."
+        lead_bootstrap_instruction = (
+            "Invoke the `okstra` skill now. Read the manifests below for all task "
+            "metadata, paths, model assignments, and worker roster."
+        )
+        lead_session_block = (
+            "## Session\n"
+            "\n"
+            f"- Session ID: `{ctx.get('CLAUDE_SESSION_ID', '')}`\n"
+            f"- Resume: `{ctx.get('CLAUDE_RESUME_COMMAND_RELATIVE_PATH', '')}`"
+        )
+        worker_dispatch_guidance = (
+            "## Worker Prompt Files (not pre-rendered)\n"
+            "\n"
+            "- The `runs/<phase>/prompts/<worker>-worker-prompt-*.md` files referenced in `task-manifest.json → artifacts.workerPromptPathByWorkerId` are **NOT** rendered by the okstra runtime. Those paths are the *assigned* locations where the prompt history MUST be written at dispatch time.\n"
+            "- Therefore: at the start of every phase the prompts/ directory is normally empty (or contains only previously-dispatched workers' files). This is expected. Do NOT narrate it as \"missing\", \"누락\", or \"not yet rendered\" — it just means dispatch has not happened yet.\n"
+            "- Before dispatching any required worker, **you (the lead) construct the worker prompt and persist it to the assigned absolute path using `Write`** (per `okstra-team-contract` rule 6). Only after persisting do you call the worker subagent (Agent tool / Codex / Gemini wrapper). The wrapper subagents will also re-write the same file on their end; the double-write is intentional and idempotent.\n"
+            "- Do not \"check if the file exists and skip dispatch\" — file presence is not a signal to skip. Worker selection and skipping rules come from team-state, never from prompts/ directory contents.\n"
+            f"- **Worker Preamble Path (single anchor — replaces inlined `[Required reading]` and `[Error reporting]` blocks).** Every worker prompt you construct MUST include the anchor header `**Worker Preamble Path:** {ctx.get('WORKER_PROMPT_PREAMBLE_PATH', str(Path.home() / '.okstra' / 'templates' / 'worker-prompt-preamble.md'))}`. The file at that path is the canonical SSOT for Required Reading + Error Reporting + Output sections; workers Read it end-to-end before producing output. Do NOT re-inline those blocks into worker prompt bodies — that is the legacy ~80-line dispatch boilerplate that this anchor is designed to replace."
+        )
+
     # Compute results (deterministic from ctx, 덮어쓰기)
+    ctx["LEAD_INTRO_LINE"] = lead_intro_line
+    ctx["LEAD_BOOTSTRAP_INSTRUCTION"] = lead_bootstrap_instruction
+    ctx["LEAD_SESSION_BLOCK"] = lead_session_block
     ctx["TEAM_CREATION_GATE"] = team_creation_gate_block
+    ctx["WORKER_DISPATCH_GUIDANCE"] = worker_dispatch_guidance
     ctx["WORKER_RESULT_PATH_LINES"] = "\n".join(worker_result_lines)
     ctx["MODEL_ASSIGNMENT_LINES"] = "\n".join(model_assignment_lines)
     ctx["TEAM_ROLE_LINES"] = "\n".join(team_role_lines)

package/runtime/python/okstra_ctl/run.py

@@ -39,6 +39,8 @@ from .material import (
     resolve_related_tasks,
 )
 from .final_report_schema import load_schema
+from .lead_events import LeadEvent, append_lead_event
+from .lead_runtime import ALLOWED_LEAD_RUNTIMES
 from .models import ModelAssignment, resolve_model_metadata
 from .schema_excerpt import build_schema_excerpt
 from .path_resolve import relative_to_project_root, resolve_user_file
@@ -80,7 +82,7 @@ from .workers import (
     resolve_profile_workers,
     validate_workers_against_profile,
 )
-from .workflow import compute_workflow_state
+from .workflow import compute_workflow_state, load_phase_forbidden
 from .locks import worktree_provision_mutex
 from .worktree import (
     WorktreeProvision,
@@ -266,6 +268,17 @@ class PrepareError(Exception):
     """surface to caller — task bundle prepare failed."""
 
 
+_ALLOWED_LEAD_RUNTIMES = ALLOWED_LEAD_RUNTIMES
+
+
+def _normalize_lead_runtime(value: str) -> str:
+    runtime = (value or "claude-code").strip()
+    if runtime not in _ALLOWED_LEAD_RUNTIMES:
+        allowed = ", ".join(_ALLOWED_LEAD_RUNTIMES)
+        raise PrepareError(f"unsupported lead runtime: {runtime} (allowed: {allowed})")
+    return runtime
+
+
 @dataclass
 class PrepareInputs:
     workspace_root: Path
@@ -282,6 +295,7 @@ class PrepareInputs:
     codex_model: str = ""
     gemini_model: str = ""
     report_writer_model: str = ""
+    lead_runtime: str = "claude-code"
     executor: str = ""
     critic: str = ""
     related_tasks_raw: str = ""
@@ -932,6 +946,29 @@ def _brief_sha256(path: Path) -> str:
         return ""
 
 
+def _record_artifact_runtime_render_only_event(inp: PrepareInputs, ctx: dict) -> None:
+    if inp.lead_runtime not in ("codex", "external") or not inp.render_only:
+        return
+    append_lead_event(
+        Path(ctx["LEAD_EVENTS_PATH"]),
+        LeadEvent(
+            event_type="bundle-prepared",
+            lead_runtime=inp.lead_runtime,
+            task_key=ctx["TASK_KEY"],
+            task_type=ctx["TASK_TYPE"],
+            run_seq=ctx["RUN_MANIFESTS_SEQ"],
+            timestamp=ctx["RUN_TIMESTAMP_ISO"],
+            details={
+                "dispatchMode": "render-only",
+                "workerDispatch": "not-started",
+                "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
+                "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+                "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
+            },
+        ),
+    )
+
+
 def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
     """rerun 충실 재현을 위한 canonical argv 재구성."""
     workers = inp.workers_override or ctx.get("RECOMMENDED_ANALYSERS", "")
@@ -951,6 +988,7 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ("--codex-model", inp.codex_model or ctx.get("CODEX_WORKER_MODEL", "")),
         ("--gemini-model", inp.gemini_model or ctx.get("GEMINI_WORKER_MODEL", "")),
         ("--report-writer-model", inp.report_writer_model or ctx.get("REPORT_WRITER_MODEL", "")),
+        ("--lead-runtime", inp.lead_runtime if inp.lead_runtime != "claude-code" else ""),
         ("--executor", inp.executor or ctx.get("EXECUTOR_PROVIDER", "")),
         ("--critic", inp.critic or ctx.get("CRITIC_CHOICE", "")),
         ("--related-tasks", inp.related_tasks_raw),
@@ -1770,6 +1808,7 @@ def _write_instruction_set_sources(
         "EXECUTOR_WORKTREE_BASE_REF",
         "EXECUTOR_WORKTREE_STATUS",
         "EXECUTOR_WORKTREE_NOTE",
+        "PHASE_FORBIDDEN_ACTIONS",
     ):
         profile_rendered = profile_rendered.replace("{{" + key + "}}", ctx.get(key, ""))
     (instruction_set / "analysis-profile.md").write_text(profile_rendered, encoding="utf-8")
@@ -1960,7 +1999,8 @@ def _record_fix_cycle_events(inp: PrepareInputs, ctx: dict) -> str:
 
 
 def _finalize_status_and_render_manifests(
-    inp: PrepareInputs, ctx: dict, task_index_template: Path
+    inp: PrepareInputs, ctx: dict, task_index_template: Path,
+    forbidden_by_phase: dict[str, str],
 ) -> None:
     """최종 task/run status 를 확정하고 workflow state 를 재계산한 뒤 team-state,
     task-manifest, task-index, run-manifest, timeline, discovery 산출물을 렌더한다."""
@@ -1977,6 +2017,7 @@ def _finalize_status_and_render_manifests(
         current_run_status=ctx["CURRENT_RUN_STATUS"],
         current_task_status=ctx["CURRENT_TASK_STATUS"],
         render_only=inp.render_only,
+        forbidden_by_phase=forbidden_by_phase,
         work_category=inp.work_category,
     ))
     render_team_state(ctx["TEAM_STATE_PATH"], ctx)
@@ -2013,6 +2054,12 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     """Produce a complete okstra task bundle on disk. See module docstring."""
     workspace_root = Path(inp.workspace_root)
     project_root = Path(inp.project_root)
+    lead_runtime = _normalize_lead_runtime(inp.lead_runtime)
+    if lead_runtime != "claude-code" and not inp.render_only:
+        raise PrepareError(
+            f"lead runtime `{lead_runtime}` is currently render-only; "
+            "use --render-only until a dispatch backend is enabled for this lead runtime."
+        )
 
     # ---- input validation + asset resolution + roster/model 해소 ----
     # 각 단계는 명시적 입력/반환을 갖는 헬퍼로 분리되어 있다 (상단 phase 헬퍼
@@ -2186,17 +2233,20 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     # ---- initial workflow state (current_run_status not yet known) ----
     initial_task_status = "ready-for-claude"
     initial_run_status = "not-run"
+    forbidden_by_phase = load_phase_forbidden(workspace_root)
     workflow_state = compute_workflow_state(
         task_type=inp.task_type,
         current_run_status=initial_run_status,
         current_task_status=initial_task_status,
         render_only=inp.render_only,
+        forbidden_by_phase=forbidden_by_phase,
     )
 
     # ---- assemble full ctx (the values render functions expect) ----
     ctx.update({
         "ANALYSIS_PROFILE": inp.task_type,
         "RECOMMENDED_ANALYSERS": selected_reviewers,
+        "LEAD_RUNTIME": lead_runtime,
         "PR_TEMPLATE_PATH": pr_template_path_str,
         "PR_TEMPLATE_SOURCE": pr_template_source,
         **handoff_tokens,
@@ -2235,6 +2285,10 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "OKSTRA_VERSION": installed_version(),
         **workflow_state,
     })
+    if lead_runtime == "codex":
+        ctx["CLAUDE_RESUME_COMMAND_PATH"] = ""
+        ctx["CLAUDE_RESUME_COMMAND_RELATIVE_PATH"] = ""
+        ctx["CLAUDE_RESUME_COMMAND_FILENAME"] = ""
     if inp.task_type == "final-verification":
         _reserve_final_verification_target(inp, ctx, ctx_stage_map)
 
@@ -2244,21 +2298,23 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     cleanup_obsolete_generated_docs(
         project_root=project_root, instruction_set_dir=Path(ctx["INSTRUCTION_SET_PATH"]),
     )
-    # Always materialise the resume command script. Even in --render-only
-    # preparation flows the user (or a later non-interactive runner) may
-    # invoke it manually; deferring its creation until interactive launch
-    # leaves runs/<phase>/sessions/ empty and the manifest pointing at a
-    # path that does not exist.
-    write_claude_resume_command_file(
-        resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_PATH"]),
-        project_root=project_root,
-        claude_session_id=claude_session_id,
-        task_key=ctx["TASK_KEY"],
-        task_type=ctx["TASK_TYPE"],
-        phase_state=ctx["CURRENT_RUN_STATUS"],
-        worker_prompts_dir_relative=ctx["RUN_PROMPTS_RELATIVE_PATH"],
-        prompt_seq=ctx["RUN_PROMPTS_SEQ"],
-    )
+    if lead_runtime == "claude-code":
+        # Always materialise the resume command script for Claude Code. Even in
+        # --render-only preparation flows the user (or a later non-interactive
+        # runner) may invoke it manually; deferring its creation until
+        # interactive launch leaves runs/<phase>/sessions/ empty and the
+        # manifest pointing at a path that does not exist. Codex runs resume via
+        # artifacts/checkpoints instead, so they intentionally leave this empty.
+        write_claude_resume_command_file(
+            resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_PATH"]),
+            project_root=project_root,
+            claude_session_id=claude_session_id,
+            task_key=ctx["TASK_KEY"],
+            task_type=ctx["TASK_TYPE"],
+            phase_state=ctx["CURRENT_RUN_STATUS"],
+            worker_prompts_dir_relative=ctx["RUN_PROMPTS_RELATIVE_PATH"],
+            prompt_seq=ctx["RUN_PROMPTS_SEQ"],
+        )
 
     # ---- fix-cycle 기록 (manifest 재작성 전 디스크 값으로 lazy-close 판정) ----
     # instruction-set 빌드보다 *앞*에서 호출해 이번 run 에서 새로 open 되는
@@ -2279,7 +2335,10 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     _persist_run_inputs(inp, ctx, models, selected_reviewers, brief_relative)
 
     # ---- final status + manifest/discovery renders ----
-    _finalize_status_and_render_manifests(inp, ctx, task_index_template)
+    _finalize_status_and_render_manifests(
+        inp, ctx, task_index_template, forbidden_by_phase
+    )
+    _record_artifact_runtime_render_only_event(inp, ctx)
 
     # ---- central index ----
     initial_status = "prepared" if inp.render_only else "running"
@@ -2354,6 +2413,17 @@ def main(argv: list[str]) -> int:
     p.add_argument("--codex-model", default="")
     p.add_argument("--gemini-model", default="")
     p.add_argument("--report-writer-model", default="")
+    p.add_argument(
+        "--lead-runtime",
+        default="claude-code",
+        choices=list(_ALLOWED_LEAD_RUNTIMES),
+        dest="lead_runtime",
+        help=(
+            "Lead runtime adapter. Default: claude-code. `codex` renders "
+            "Codex CLI artifact bundles; `external` renders neutral bootstrap "
+            "bundles for manifest inspection until a dispatch backend is enabled."
+        ),
+    )
     p.add_argument("--executor", default="")
     p.add_argument("--critic", default="")
     p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
@@ -2490,6 +2560,7 @@ def main(argv: list[str]) -> int:
         codex_model=args.codex_model,
         gemini_model=args.gemini_model,
         report_writer_model=args.report_writer_model,
+        lead_runtime=args.lead_runtime,
         executor=args.executor,
         critic=args.critic,
         related_tasks_raw=args.related_tasks_raw,