okstra 0.1.0

package/runtime/python/okstra_ctl/run.py

@@ -0,0 +1,674 @@
+"""prepare_task_bundle — the single python entrypoint that materializes a
+complete okstra task bundle on disk.
+
+This function replaces the ~50-step wiring that previously lived in bash
+`okstra.sh`. It is called by:
+  - `okstra.sh` (thin wrapper: argv → prepare_task_bundle → optional exec claude)
+  - `okstra-run` skill (collects inputs via AskUserQuestion → calls this)
+  - okstra-ctl rerun (passes recorded invocation argv through)
+
+The function is read-modify-write on disk inside per-task mutex; it does not
+mutate the calling process environment or rely on inherited env values for
+any per-run identity. The only env vars honored are user-knob defaults
+(`OKSTRA_DEFAULT_*_MODEL`, `OKSTRA_HOME`) — these are intentional config, not
+state passing, and are read once at the start.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from okstra_project import upsert_project_json
+from .material import (
+    build_analysis_material,
+    related_tasks_bullets,
+    related_tasks_inline,
+    resolve_related_tasks,
+)
+from .models import resolve_model_metadata
+from .path_resolve import relative_to_project_root, resolve_user_file
+from .render import (
+    render_latest_task_discovery,
+    render_reference_expectations,
+    render_run_manifest,
+    render_task_catalog_discovery,
+    render_task_index,
+    render_task_manifest,
+    render_team_state,
+    render_template_file,
+    render_timeline,
+)
+from .run_context import compute_and_write_run_context, write_run_inputs
+from .seeding import (
+    cleanup_obsolete_generated_docs,
+    render_runtime_settings_file,
+    verify_installation,
+)
+from .session import generate_claude_session_id, write_claude_resume_command_file
+from .workers import normalize_workers, resolve_profile_workers
+from .workflow import compute_workflow_state
+
+APPROVED_PLAN_PATTERN = re.compile(
+    r"^[ \t]*(APPROVED([ \t]|:|$)|\[x\][ \t]*Approved|"
+    r"User[ \t]+Approval[ \t]*:[ \t]*(APPROVED|granted|yes))",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+
+class PrepareError(Exception):
+    """surface to caller — task bundle prepare failed."""
+
+
+@dataclass
+class PrepareInputs:
+    workspace_root: Path
+    project_root: Path
+    project_id: str
+    task_group: str
+    task_id: str
+    task_type: str
+    brief_path: Path  # absolute, already resolved
+    directive: str = ""
+    workers_override: str = ""
+    lead_model: str = ""
+    claude_model: str = ""
+    codex_model: str = ""
+    gemini_model: str = ""
+    report_writer_model: str = ""
+    related_tasks_raw: str = ""
+    approved_plan_path: str = ""
+    clarification_response_path: str = ""  # absolute or empty
+    render_only: bool = False
+    refresh_assets: bool = False
+
+
+@dataclass
+class PrepareOutputs:
+    ctx: dict
+    prompt_text: str
+    runtime_settings_path: Optional[Path]
+    extras: dict = field(default_factory=dict)
+
+
+def _default(name: str, fallback: str) -> str:
+    return os.environ.get(name, "") or fallback
+
+
+def _validate_approved_plan(path: str) -> None:
+    p = Path(path)
+    if not p.is_file():
+        raise PrepareError(f"approved plan file not found: {path}")
+    if not APPROVED_PLAN_PATTERN.search(p.read_text(encoding="utf-8", errors="replace")):
+        raise PrepareError(
+            f"approved plan has no recognised user-approval marker: {path}\n"
+            '  expected one of (case-insensitive, line-anchored): "APPROVED", '
+            '"[x] Approved", "User Approval: APPROVED|granted|yes"'
+        )
+
+
+def _ensure_task_directories(ctx: dict) -> None:
+    for key in (
+        "TASK_ROOT", "INSTRUCTION_SET_DIR", "RUNS_DIR", "HISTORY_DIR",
+        "RUN_DIR", "RUN_MANIFESTS_DIR", "RUN_STATE_DIR", "RUN_PROMPTS_DIR",
+        "RUN_REPORTS_DIR", "RUN_STATUS_DIR", "RUN_SESSIONS_DIR",
+        "RUN_LOGS_DIR", "WORKER_RESULTS_DIR", "OKSTRA_DISCOVERY_DIR",
+    ):
+        Path(ctx[key]).mkdir(parents=True, exist_ok=True)
+
+
+def _migrate_legacy_run_artifacts(ctx: dict) -> None:
+    """run/<task-type>/ 바로 아래에 남아 있을 수 있는 legacy 파일을 카테고리
+    하위 디렉터리(`manifests/`, `state/`, ...) 로 이동한다.
+    """
+    project_root = Path(ctx["PROJECT_ROOT"])
+    task_root = Path(ctx["TASK_ROOT"])
+    run_dir = Path(ctx["RUN_DIR"])
+    if not run_dir.is_dir():
+        return
+    legacy = [
+        ("run-manifest-", ".json", Path(ctx["RUN_MANIFESTS_DIR"])),
+        ("team-state-", ".json", Path(ctx["RUN_STATE_DIR"])),
+        ("claude-execution-prompt-", ".md", Path(ctx["RUN_PROMPTS_DIR"])),
+        ("final-report-", ".md", Path(ctx["RUN_REPORTS_DIR"])),
+        ("final-", ".status", Path(ctx["RUN_STATUS_DIR"])),
+        ("claude-resume-", ".sh", Path(ctx["RUN_SESSIONS_DIR"])),
+    ]
+    rewrites: dict[str, str] = {}
+    for entry in run_dir.iterdir():
+        if not entry.is_file():
+            continue
+        for prefix, suffix, target_dir in legacy:
+            if not (entry.name.startswith(prefix) and entry.name.endswith(suffix)):
+                continue
+            target_dir.mkdir(parents=True, exist_ok=True)
+            dest = target_dir / entry.name
+            old_rel = str(entry.relative_to(project_root))
+            new_rel = str(dest.relative_to(project_root))
+            if dest.exists():
+                try:
+                    if entry.read_bytes() == dest.read_bytes():
+                        entry.unlink()
+                        rewrites[old_rel] = new_rel
+                except Exception:
+                    pass
+                break
+            shutil.move(str(entry), str(dest))
+            rewrites[old_rel] = new_rel
+            break
+    if not rewrites:
+        return
+    for path in task_root.rglob("*"):
+        if not path.is_file() or path.suffix not in {".json", ".md", ".txt", ".sh"}:
+            continue
+        try:
+            original = path.read_text(encoding="utf-8")
+        except Exception:
+            continue
+        updated = original
+        for o, n in rewrites.items():
+            updated = updated.replace(o, n)
+        if updated != original:
+            path.write_text(updated, encoding="utf-8")
+
+
+def _record_start(
+    *,
+    workspace_root: Path,
+    ctx: dict,
+    initial_status: str,
+    canonical_argv: list[str],
+    cwd: str,
+    brief_sha256: str,
+) -> None:
+    """record_start hook 호출. okstra-central.sh 의 bash wrapper 와 같은 동작
+    이지만 python 직접 호출이라 환경 변수 의존 없음.
+    """
+    import fcntl
+    import json as _json
+    from datetime import datetime, timezone
+    from okstra_ctl import record_start
+    from okstra_ctl.run_context import _okstra_home  # type: ignore
+
+    home = _okstra_home()
+    home.mkdir(mode=0o700, parents=True, exist_ok=True)
+    os.chmod(home, 0o700)
+    # bootstrap (okstra_central_bootstrap 와 동등) — 디렉터리·jsonl 파일 보장.
+    for sub in ("archive", ".locks", "batches", "projects"):
+        (home / sub).mkdir(exist_ok=True)
+    for f in ("active.jsonl", "recent.jsonl"):
+        (home / f).touch(exist_ok=True)
+    state_file = home / "state.json"
+    if not state_file.exists():
+        state_file.write_text(_json.dumps({
+            "schemaVersion": "1",
+            "createdAt": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "backfilledAt": None,
+        }, indent=2) + "\n", encoding="utf-8")
+        os.chmod(state_file, 0o600)
+    lockfile = home / ".lock"
+    lockfile.touch()
+    with lockfile.open("r+") as lock:
+        fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+        record_start(
+            home,
+            project_id=ctx["PROJECT_ID"],
+            project_root=ctx["PROJECT_ROOT"],
+            task_group=ctx["TASK_GROUP"],
+            task_id=ctx["TASK_ID"],
+            task_type=ctx.get("ANALYSIS_TYPE", ""),
+            run_seq=int(ctx["RUN_MANIFESTS_SEQ"]),
+            when=ctx["RUN_TIMESTAMP_ISO"],
+            workers=[w for w in ctx.get("SELECTED_REVIEWERS", "").split(",") if w],
+            lead_model=ctx.get("LEAD_MODEL_DISPLAY", ""),
+            run_dir_rel=ctx.get("RUN_DIR_RELATIVE_PATH", ""),
+            final_report_rel=ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+            final_status_rel=ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
+            argv=canonical_argv,
+            cwd=cwd,
+            env_overrides={},
+            initial_status=initial_status,
+            brief_sha256=brief_sha256,
+        )
+
+
+def _brief_sha256(path: Path) -> str:
+    import hashlib
+
+    try:
+        with Path(path).open("rb") as f:
+            return hashlib.sha256(f.read()).hexdigest()
+    except OSError:
+        return ""
+
+
+def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
+    """rerun 충실 재현을 위한 canonical argv 재구성."""
+    workers = inp.workers_override or ctx.get("SELECTED_REVIEWERS", "")
+    pairs = [
+        ("--task-type", inp.task_type),
+        ("--project-id", inp.project_id),
+        ("--task-group", inp.task_group),
+        ("--task-id", inp.task_id),
+        ("--task-brief", str(inp.brief_path)),
+        ("--directive", inp.directive),
+        ("--approved-plan", inp.approved_plan_path),
+        ("--clarification-response", inp.clarification_response_path),
+        ("--workers", workers),
+        ("--lead-model", inp.lead_model or ctx.get("LEAD_MODEL_DISPLAY", "")),
+        ("--claude-model", inp.claude_model or ctx.get("CLAUDE_WORKER_MODEL_DISPLAY", "")),
+        ("--codex-model", inp.codex_model or ctx.get("CODEX_WORKER_MODEL_DISPLAY", "")),
+        ("--gemini-model", inp.gemini_model or ctx.get("GEMINI_WORKER_MODEL_DISPLAY", "")),
+        ("--report-writer-model", inp.report_writer_model or ctx.get("REPORT_WRITER_MODEL_DISPLAY", "")),
+        ("--related-tasks", inp.related_tasks_raw),
+    ]
+    argv: list[str] = []
+    for flag, val in pairs:
+        if val:
+            argv.extend([flag, val])
+    if inp.render_only:
+        argv.append("--render-only")
+    if inp.refresh_assets:
+        argv.append("--refresh-assets")
+    argv.append("--yes")
+    return argv
+
+
+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)
+
+    # ---- validate inputs ----
+    profile_dir = workspace_root / "prompts" / "profiles"
+    profile_file = profile_dir / f"{inp.task_type}.md"
+    if not profile_file.is_file():
+        raise PrepareError(
+            f"analysis profile file not found for task-type {inp.task_type}: {profile_file}"
+        )
+    prompt_template = workspace_root / "prompts" / "launch.template.md"
+    if not prompt_template.is_file():
+        raise PrepareError(f"okstra prompt template not found: {prompt_template}")
+    task_index_template = (
+        workspace_root / "templates" / "project-docs" / "task-index.template.md"
+    )
+    final_report_template = (
+        workspace_root / "templates" / "reports" / "final-report.template.md"
+    )
+    source_skill = workspace_root / "agents" / "SKILL.md"
+    run_validator = workspace_root / "validators" / "validate-run.py"
+    for required in (task_index_template, final_report_template, run_validator, source_skill):
+        if not required.is_file():
+            raise PrepareError(f"required okstra template or source skill missing: {required}")
+    if not project_root.is_dir():
+        raise PrepareError(f"project root not found: {project_root}")
+    if not inp.brief_path.is_file():
+        raise PrepareError(f"task brief not found: {inp.brief_path}")
+    if inp.task_type == "implementation":
+        if not inp.approved_plan_path:
+            raise PrepareError(
+                "task-type implementation requires --approved-plan <path-to-final-report.md>"
+            )
+        _validate_approved_plan(inp.approved_plan_path)
+    if inp.clarification_response_path and not Path(inp.clarification_response_path).is_file():
+        raise PrepareError(
+            f"clarification response file not found: {inp.clarification_response_path}"
+        )
+
+    # ---- installation check ----
+    verify_installation(workspace_root)
+
+    # ---- project.json upsert (self-registration) ----
+    from okstra_project import ResolverError
+
+    try:
+        upsert_project_json(project_root, inp.project_id)
+    except ResolverError as exc:
+        raise PrepareError(f"project.json upsert failed: {exc}") from exc
+
+    # ---- workers resolution ----
+    profile_workers_csv = ",".join(resolve_profile_workers(profile_file))
+    workers = normalize_workers(inp.workers_override or profile_workers_csv)
+    if not workers:
+        raise PrepareError(f"no workers resolved for profile: {inp.task_type}")
+    selected_reviewers = ",".join(workers)
+
+    # ---- model assignments ----
+    lead_default = _default("OKSTRA_DEFAULT_LEAD_MODEL", "opus")
+    claude_default = _default("OKSTRA_DEFAULT_CLAUDE_MODEL", "sonnet")
+    codex_default = _default("OKSTRA_DEFAULT_CODEX_MODEL", "gpt-5.5")
+    gemini_default = _default("OKSTRA_DEFAULT_GEMINI_MODEL", "auto")
+    report_writer_default = _default("OKSTRA_DEFAULT_REPORT_WRITER_MODEL", lead_default)
+    lead = resolve_model_metadata(
+        provider="claude", raw_value=inp.lead_model,
+        default_display=lead_default, default_execution=lead_default,
+    )
+    cw = resolve_model_metadata(
+        provider="claude", raw_value=inp.claude_model,
+        default_display=claude_default, default_execution=claude_default,
+    )
+    co = resolve_model_metadata(
+        provider="codex", raw_value=inp.codex_model,
+        default_display=codex_default, default_execution=codex_default,
+    )
+    ge = resolve_model_metadata(
+        provider="gemini", raw_value=inp.gemini_model,
+        default_display=gemini_default, default_execution=gemini_default,
+    )
+    rw = resolve_model_metadata(
+        provider="claude", raw_value=inp.report_writer_model,
+        default_display=report_writer_default, default_execution=report_writer_default,
+    )
+
+    # ---- paths under per-task mutex (writes run-context-*.json) ----
+    # OKSTRA_RUN_SEQ_OVERRIDE: okstra-ctl rerun / 테스트 hook 이 미리 reserve
+    # 한 seq 를 강제하는 user-knob 환경 변수.
+    raw_override = os.environ.get("OKSTRA_RUN_SEQ_OVERRIDE", "").strip()
+    run_seq_override = int(raw_override) if raw_override else None
+    ctx = compute_and_write_run_context(
+        workspace_root=workspace_root, project_root=project_root,
+        project_id=inp.project_id, task_group=inp.task_group, task_id=inp.task_id,
+        task_type=inp.task_type, run_seq_override=run_seq_override,
+    )
+
+    claude_session_id = "" if inp.render_only else generate_claude_session_id()
+
+    # ---- material + related-tasks ----
+    profile_content = profile_file.read_text(encoding="utf-8")
+    review_material = build_analysis_material(inp.brief_path, inp.directive)
+    related_items = resolve_related_tasks(
+        task_manifest_path=Path(ctx["TASK_MANIFEST_FILE"]),
+        raw_related=inp.related_tasks_raw,
+    )
+    related_tasks_json_str = json.dumps(related_items, ensure_ascii=False)
+    bullets = related_tasks_bullets(related_items)
+    inline = related_tasks_inline(related_items)
+
+    # ---- relative paths for brief + clarification ----
+    brief_relative = relative_to_project_root(inp.brief_path, project_root)
+    clarification_relative = (
+        relative_to_project_root(Path(inp.clarification_response_path), project_root)
+        if inp.clarification_response_path else ""
+    )
+
+    # ---- initial workflow state (current_run_status not yet known) ----
+    initial_task_status = "ready-for-claude"
+    initial_run_status = "not-run"
+    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,
+    )
+
+    # ---- assemble full ctx (the values render functions expect) ----
+    ctx.update({
+        "REVIEW_PROFILE": inp.task_type,
+        "SELECTED_REVIEWERS": selected_reviewers,
+        "CLAUDE_SESSION_ID": claude_session_id,
+        "CLARIFICATION_RESPONSE_PATH": inp.clarification_response_path,
+        "CLARIFICATION_RESPONSE_FILE": inp.clarification_response_path,
+        "CLARIFICATION_RESPONSE_RELATIVE_PATH": clarification_relative,
+        "BRIEF_FILE_PATH": str(inp.brief_path),
+        "BRIEF_RELATIVE_PATH": brief_relative,
+        "LEAD_MODEL_DISPLAY": lead.display,
+        "LEAD_MODEL_EXECUTION_VALUE": lead.execution,
+        "CLAUDE_WORKER_MODEL_DISPLAY": cw.display,
+        "CLAUDE_WORKER_MODEL_EXECUTION_VALUE": cw.execution,
+        "CODEX_WORKER_MODEL_DISPLAY": co.display,
+        "CODEX_WORKER_MODEL_EXECUTION_VALUE": co.execution,
+        "GEMINI_WORKER_MODEL_DISPLAY": ge.display,
+        "GEMINI_WORKER_MODEL_EXECUTION_VALUE": ge.execution,
+        "REPORT_WRITER_MODEL_DISPLAY": rw.display,
+        "REPORT_WRITER_MODEL_EXECUTION_VALUE": rw.execution,
+        "RELATED_TASKS_JSON": related_tasks_json_str,
+        "RELATED_TASKS_BULLETS": bullets,
+        "RELATED_TASKS_INLINE": inline,
+        "CURRENT_TASK_STATUS": initial_task_status,
+        "CURRENT_RUN_STATUS": initial_run_status,
+        "VALIDATION_STATUS": "not-run",
+        "VALIDATION_UPDATED_AT": "",
+        "VALIDATION_FAILURES_JSON": "[]",
+        "LATEST_REPORT_PATH": "",
+        "LATEST_REPORT_RELATIVE_PATH": "",
+        "RENDER_ONLY": "true" if inp.render_only else "false",
+        **workflow_state,
+    })
+
+    # ---- prepare directories + cleanup ----
+    _ensure_task_directories(ctx)
+    _migrate_legacy_run_artifacts(ctx)
+    cleanup_obsolete_generated_docs(
+        project_root=project_root, instruction_set_dir=Path(ctx["INSTRUCTION_SET_DIR"]),
+    )
+    if not inp.render_only:
+        write_claude_resume_command_file(
+            resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_FILE"]),
+            project_root=project_root, claude_session_id=claude_session_id,
+        )
+
+    # ---- write instruction-set scaffolding ----
+    instruction_set = Path(ctx["INSTRUCTION_SET_DIR"])
+    instruction_set.mkdir(parents=True, exist_ok=True)
+    (instruction_set / "analysis-profile.md").write_text(profile_content, encoding="utf-8")
+    (instruction_set / "analysis-material.md").write_text(review_material, encoding="utf-8")
+    shutil.copyfile(inp.brief_path, instruction_set / "task-brief.md")
+    if inp.clarification_response_path:
+        shutil.copyfile(
+            inp.clarification_response_path,
+            instruction_set / "clarification-response.md",
+        )
+    if inp.directive:
+        (instruction_set / "directive.txt").write_text(inp.directive + "\n", encoding="utf-8")
+    render_reference_expectations(
+        str(inp.brief_path), str(instruction_set / "reference-expectations.md"), ctx,
+    )
+    render_template_file(
+        str(final_report_template), ctx["FINAL_REPORT_TEMPLATE_FILE"], ctx,
+    )
+    render_template_file(
+        str(prompt_template), str(instruction_set / "claude-execution-prompt.md"), ctx,
+    )
+    prompt_text = (instruction_set / "claude-execution-prompt.md").read_text(encoding="utf-8")
+    Path(ctx["RUN_PROMPT_SNAPSHOT_FILE"]).parent.mkdir(parents=True, exist_ok=True)
+    Path(ctx["RUN_PROMPT_SNAPSHOT_FILE"]).write_text(prompt_text, encoding="utf-8")
+
+    # ---- run-inputs persistence ----
+    write_run_inputs(
+        project_root=project_root,
+        run_manifests_dir=Path(ctx["RUN_MANIFESTS_DIR"]),
+        task_type_segment=ctx["TASK_TYPE_SEGMENT"],
+        seq=ctx["RUN_MANIFESTS_SEQ"],
+        inputs={
+            "taskBriefPath": brief_relative,
+            "taskBriefAbsolutePath": str(inp.brief_path),
+            "directive": inp.directive,
+            "workers": selected_reviewers,
+            "leadModel": lead.display,
+            "claudeModel": cw.display,
+            "codexModel": co.display,
+            "geminiModel": ge.display,
+            "reportWriterModel": rw.display,
+            "relatedTasks": inp.related_tasks_raw,
+            "approvedPlanPath": inp.approved_plan_path,
+            "clarificationResponsePath": inp.clarification_response_path,
+            "renderOnly": inp.render_only,
+            "refreshAssets": inp.refresh_assets,
+        },
+    )
+
+    # ---- final status before manifest writes ----
+    if inp.render_only:
+        ctx["CURRENT_TASK_STATUS"] = "instruction-set-generated"
+        ctx["CURRENT_RUN_STATUS"] = "prepared"
+        ctx["LATEST_REPORT_PATH"] = ctx["FINAL_REPORT_FILE"]
+        ctx["LATEST_REPORT_RELATIVE_PATH"] = ctx["FINAL_REPORT_RELATIVE_PATH"]
+    else:
+        ctx["CURRENT_TASK_STATUS"] = "claude-session-started"
+        ctx["CURRENT_RUN_STATUS"] = "in-progress"
+        ctx["LATEST_REPORT_PATH"] = ctx["FINAL_REPORT_FILE"]
+        ctx["LATEST_REPORT_RELATIVE_PATH"] = ctx["FINAL_REPORT_RELATIVE_PATH"]
+    ctx.update(compute_workflow_state(
+        task_type=inp.task_type,
+        current_run_status=ctx["CURRENT_RUN_STATUS"],
+        current_task_status=ctx["CURRENT_TASK_STATUS"],
+        render_only=inp.render_only,
+    ))
+    render_team_state(ctx["TEAM_STATE_FILE"], ctx)
+    render_task_manifest(ctx["TASK_MANIFEST_FILE"], ctx)
+    render_task_index(str(task_index_template), ctx["TASK_INDEX_FILE"], ctx)
+    render_run_manifest(ctx["RUN_MANIFEST_FILE"], ctx)
+    render_timeline(ctx["TIMELINE_FILE"], ctx)
+    render_task_catalog_discovery(ctx["OKSTRA_TASK_CATALOG_FILE"], ctx)
+    render_latest_task_discovery(ctx["OKSTRA_LATEST_TASK_FILE"], ctx)
+
+    # ---- central index ----
+    initial_status = "prepared" if inp.render_only else "running"
+    canonical_argv = _canonical_argv(inp, ctx)
+    try:
+        _record_start(
+            workspace_root=workspace_root,
+            ctx=ctx,
+            initial_status=initial_status,
+            canonical_argv=canonical_argv,
+            cwd=os.getcwd(),
+            brief_sha256=_brief_sha256(inp.brief_path),
+        )
+    except Exception as exc:
+        print(
+            f"okstra-central: record_start failed; central index will be incomplete ({exc})",
+            file=__import__("sys").stderr,
+        )
+
+    runtime_settings_path = None
+    if not inp.render_only:
+        runtime_settings_path = render_runtime_settings_file(
+            workspace_root=workspace_root, run_dir=Path(ctx["RUN_DIR"]),
+        )
+
+    return PrepareOutputs(
+        ctx=ctx,
+        prompt_text=prompt_text,
+        runtime_settings_path=runtime_settings_path,
+        extras={"profile_content": profile_content},
+    )
+
+
+def claude_is_available() -> bool:
+    """`claude` CLI 가 PATH 에 있는지 확인."""
+    return shutil.which("claude") is not None
+
+
+def main(argv: list[str]) -> int:
+    """CLI dispatcher for bash thin-wrapper use. Parses a flat list of argv
+    (the same flags `okstra.sh` accepts), runs prepare_task_bundle, prints
+    summary lines + prompt to stdout."""
+    import argparse
+
+    p = argparse.ArgumentParser()
+    p.add_argument("--workspace-root", required=True)
+    p.add_argument("--project-root", required=True)
+    p.add_argument("--project-id", required=True)
+    p.add_argument("--task-group", required=True)
+    p.add_argument("--task-id", required=True)
+    p.add_argument("--task-type", required=True)
+    p.add_argument("--task-brief", required=True, dest="task_brief")
+    p.add_argument("--directive", default="")
+    p.add_argument("--workers", default="", dest="workers_override")
+    p.add_argument("--lead-model", default="")
+    p.add_argument("--claude-model", default="")
+    p.add_argument("--codex-model", default="")
+    p.add_argument("--gemini-model", default="")
+    p.add_argument("--report-writer-model", default="")
+    p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
+    p.add_argument("--approved-plan", default="", dest="approved_plan_path")
+    p.add_argument("--clarification-response", default="", dest="clarification_response_path")
+    p.add_argument("--render-only", action="store_true", dest="render_only")
+    p.add_argument("--refresh-assets", action="store_true", dest="refresh_assets")
+    args = p.parse_args(argv)
+
+    project_root = Path(args.project_root).expanduser().resolve()
+    brief_abs = resolve_user_file(args.task_brief, project_root)
+    if brief_abs is None:
+        print(f"task brief not found: {args.task_brief}", file=__import__("sys").stderr)
+        return 1
+    clarification_abs = ""
+    if args.clarification_response_path:
+        cr = resolve_user_file(args.clarification_response_path, project_root)
+        if cr is None:
+            print(
+                f"clarification response file not found: {args.clarification_response_path}",
+                file=__import__("sys").stderr,
+            )
+            return 1
+        clarification_abs = str(cr)
+
+    inputs = PrepareInputs(
+        workspace_root=Path(args.workspace_root).resolve(),
+        project_root=project_root,
+        project_id=args.project_id,
+        task_group=args.task_group,
+        task_id=args.task_id,
+        task_type=args.task_type,
+        brief_path=brief_abs,
+        directive=args.directive,
+        workers_override=args.workers_override,
+        lead_model=args.lead_model,
+        claude_model=args.claude_model,
+        codex_model=args.codex_model,
+        gemini_model=args.gemini_model,
+        report_writer_model=args.report_writer_model,
+        related_tasks_raw=args.related_tasks_raw,
+        approved_plan_path=args.approved_plan_path,
+        clarification_response_path=clarification_abs,
+        render_only=args.render_only,
+        refresh_assets=args.refresh_assets,
+    )
+    try:
+        out = prepare_task_bundle(inputs)
+    except PrepareError as exc:
+        print(str(exc), file=__import__("sys").stderr)
+        return 1
+
+    ctx = out.ctx
+    # summary block — bash wrapper consumes (and may pipe to user).
+    print(f"okstra task key: {ctx['TASK_KEY']}")
+    print(f"okstra task root: {ctx['TASK_ROOT']}")
+    print(f"okstra latest task discovery file: {ctx['OKSTRA_LATEST_TASK_FILE']}")
+    print(f"okstra task catalog file: {ctx['OKSTRA_TASK_CATALOG_FILE']}")
+    print(f"okstra instruction-set: {ctx['INSTRUCTION_SET_DIR']}")
+    print(f"okstra reference expectations: {ctx['REFERENCE_EXPECTATIONS_FILE']}")
+    print(f"okstra final report template: {ctx['FINAL_REPORT_TEMPLATE_FILE']}")
+    if inputs.render_only:
+        print()
+        print(out.prompt_text, end="")
+    else:
+        print(f"okstra current run dir: {ctx['RUN_DIR']}")
+        print(f"final report path: {ctx['FINAL_REPORT_FILE']}")
+        print(f"lead model: {ctx['LEAD_MODEL_DISPLAY']}")
+        print(f"claude session id: {ctx['CLAUDE_SESSION_ID']}")
+        print(f"resume command file: {ctx['CLAUDE_RESUME_COMMAND_FILE']}")
+        print("launch mode: interactive Claude handoff")
+        print(f"claude working directory: {ctx['PROJECT_ROOT']}")
+        print()
+        # In non-render-only mode emit a small JSON the bash wrapper can parse
+        # to build the `claude` exec command. Wrapper exec's; we don't.
+        machine = {
+            "claudeSessionId": ctx["CLAUDE_SESSION_ID"],
+            "leadModelExecutionValue": ctx["LEAD_MODEL_EXECUTION_VALUE"],
+            "projectRoot": ctx["PROJECT_ROOT"],
+            "runtimeSettingsFile": str(out.runtime_settings_path) if out.runtime_settings_path else "",
+            "promptFile": str(Path(ctx["INSTRUCTION_SET_DIR"]) / "claude-execution-prompt.md"),
+        }
+        print(f"__OKSTRA_LAUNCH__ {json.dumps(machine)}")
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+    raise SystemExit(main(sys.argv[1:]))