okstra 0.75.0 → 0.77.0

package/runtime/python/okstra_token_usage/gemini.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
-from .paths import GEMINI_TMP
+from .paths import GEMINI_TMP, ts_in_window
 
 
 def gemini_session_total(json_path: Path) -> dict:
@@ -40,9 +40,15 @@ def gemini_session_total(json_path: Path) -> dict:
 
 
 def find_gemini_session(project_root: Path, started_at: str, ended_at: str) -> Path | None:
-    """Find the gemini chat session whose first user message references the project."""
+    """Find the latest gemini chat session in the requested window."""
+    sessions = find_gemini_sessions(project_root, started_at, ended_at)
+    return sessions[-1] if sessions else None
+
+
+def find_gemini_sessions(project_root: Path, started_at: str, ended_at: str) -> list[Path]:
+    """Find gemini chat sessions whose first user message references the project."""
     if not GEMINI_TMP.is_dir() or not started_at or not ended_at:
-        return None
+        return []
     project_str = str(project_root)
     candidates: list[tuple[str, Path]] = []
     for p in GEMINI_TMP.glob("*/chats/session-*.json"):
@@ -51,7 +57,7 @@ def find_gemini_session(project_root: Path, started_at: str, ended_at: str) -> P
         except (OSError, json.JSONDecodeError):
             continue
         start = data.get("startTime") or ""
-        if not (started_at <= start <= ended_at):
+        if not ts_in_window(start, started_at, ended_at):
             continue
         # Match by content: first user message should mention project root or task path.
         msgs = data.get("messages") or []
@@ -71,7 +77,6 @@ def find_gemini_session(project_root: Path, started_at: str, ended_at: str) -> P
                 candidates.append((start, p))
             break
     if not candidates:
-        return None
+        return []
     candidates.sort()
-    return candidates[-1][1]
-
+    return [path for _start, path in candidates]

package/runtime/skills/okstra-setup/SKILL.md

@@ -251,7 +251,7 @@ back it up as `.bak.<timestamp>` rather than overwriting silently.
 
 `release-handoff` fills the PR body from a template. By default it uses the
 bundled skill template at
-`~/.claude/skills/okstra-run/templates/pr-body.template.md`. Most projects
+`~/.claude/skills/templates/prd/pr-body.template.md`. Most projects
 want their own — e.g. the repo's `.github/PULL_REQUEST_TEMPLATE.md` — to
 keep PRs consistent with what the team already merges manually.
 

package/runtime/validators/validate-run.py

@@ -47,6 +47,7 @@ from okstra_ctl.md_table import (  # noqa: E402
 
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
+CODEX_DISPATCH_MODES = {"cli-wrapper", "mixed"}
 
 
 def utc_now() -> str:
@@ -401,27 +402,36 @@ def validate_team_state(
         for w in workers
     )
     if any_dispatched:
-        team_create = team_state.get("teamCreate")
-        if _is_legal_concurrent_run_skip(team_create, concurrent_run_authorized):
-            pass
-        elif not isinstance(team_create, dict) or not team_create.get("attempted"):
-            failures.append(
-                "team-state.teamCreate.attempted must be true once any worker has "
-                "been dispatched (status in completed/timeout/error/in-progress). "
-                "Phase 3 (TeamCreate) was skipped — workers ran in-process without "
-                "the Teams split-pane surface. See agents/SKILL.md Phase 3. "
-                "(The no-team concurrent-run path is legal ONLY when the "
-                "run-manifest carries prepare-recorded `concurrentRun.detected: "
-                'true` AND team-state records `teamCreate: { attempted: false, '
-                'status: "skipped", reason: "concurrent-run" }`.)'
-            )
+        if team_state.get("leadRuntime") == "codex":
+            dispatch_mode = str(team_state.get("dispatchMode", "")).strip()
+            if dispatch_mode not in CODEX_DISPATCH_MODES:
+                expected = ", ".join(sorted(CODEX_DISPATCH_MODES))
+                failures.append(
+                    "team-state.dispatchMode must be set for Codex worker dispatch "
+                    f"(expected one of: {expected})"
+                )
         else:
-            tc_status = str(team_create.get("status", "")).strip()
-            if tc_status not in {"ok", "error"}:
+            team_create = team_state.get("teamCreate")
+            if _is_legal_concurrent_run_skip(team_create, concurrent_run_authorized):
+                pass
+            elif not isinstance(team_create, dict) or not team_create.get("attempted"):
                 failures.append(
-                    "team-state.teamCreate.status must be `ok` or `error` once "
-                    f"workers have been dispatched (found: `{tc_status}`)."
+                    "team-state.teamCreate.attempted must be true once any worker has "
+                    "been dispatched (status in completed/timeout/error/in-progress). "
+                    "Phase 3 (TeamCreate) was skipped — workers ran in-process without "
+                    "the Teams split-pane surface. See agents/SKILL.md Phase 3. "
+                    "(The no-team concurrent-run path is legal ONLY when the "
+                    "run-manifest carries prepare-recorded `concurrentRun.detected: "
+                    'true` AND team-state records `teamCreate: { attempted: false, '
+                    'status: "skipped", reason: "concurrent-run" }`.)'
                 )
+            else:
+                tc_status = str(team_create.get("status", "")).strip()
+                if tc_status not in {"ok", "error"}:
+                    failures.append(
+                        "team-state.teamCreate.status must be `ok` or `error` once "
+                        f"workers have been dispatched (found: `{tc_status}`)."
+                    )
 
     by_role: dict[str, dict] = {}
     for worker in workers:
@@ -587,7 +597,12 @@ _TOKEN_USAGE_SENTINEL_VALUES = frozenset(
 _TOKEN_USAGE_ZERO_VALUES = frozenset({"0", "$0.00", "$0", "0.00"})
 
 
-def _scan_token_usage_summary(content: str, failures: list[str]) -> None:
+def _scan_token_usage_summary(
+    content: str,
+    failures: list[str],
+    *,
+    allow_unavailable_tokens: bool = False,
+) -> None:
     """Reject sentinel / zero values that workers typed into the Token
     Usage Summary table instead of leaving the `{{...}}` placeholders
     verbatim for Phase 7 substitution.
@@ -639,6 +654,8 @@ def _scan_token_usage_summary(content: str, failures: list[str]) -> None:
             for value in _TOKEN_USAGE_BACKTICK_CELL_RE.findall(raw_cell):
                 stripped = value.strip()
                 lowered = stripped.lower()
+                if allow_unavailable_tokens and stripped == "--":
+                    continue
                 if lowered in _TOKEN_USAGE_SENTINEL_VALUES:
                     failures.append(
                         "Token Usage Summary cell contains sentinel value "
@@ -883,7 +900,11 @@ def _validate_conformance(report_path: Path, failures: list[str],
 
 
 def validate_report(
-    report_path: Path, required_agent_status_entries: list[str], failures: list[str]
+    report_path: Path,
+    required_agent_status_entries: list[str],
+    failures: list[str],
+    *,
+    allow_unavailable_token_usage: bool = False,
 ) -> None:
     if not report_path.exists():
         failures.append(f"final report is missing: {report_path}")
@@ -905,7 +926,11 @@ def validate_report(
 
     # Catch the "workers typed `0` / `pending` instead of the placeholder"
     # failure mode that bypasses the placeholder check above.
-    _scan_token_usage_summary(content, failures)
+    _scan_token_usage_summary(
+        content,
+        failures,
+        allow_unavailable_tokens=allow_unavailable_token_usage,
+    )
 
     # Verdict Card is mandatory in every final-report (introduced with the
     # report-format readability pass). Missing card means the reader has no
@@ -1051,6 +1076,8 @@ def validate_worker_results_audit(
 
 
 def validate_team_state_usage(team_state: dict, failures: list[str]) -> None:
+    if team_state.get("leadRuntime") == "codex":
+        return
     summary = team_state.get("usageSummary") or {}
     if not summary or not summary.get("collectedAt"):
         failures.append(
@@ -1909,6 +1936,8 @@ def _import_token_usage():
 
 
 def _needs_token_autofix(team_state: dict, report_path: Path) -> bool:
+    if team_state.get("leadRuntime") == "codex":
+        return False
     summary = team_state.get("usageSummary") or {}
     if not summary or not summary.get("collectedAt"):
         return True
@@ -2187,7 +2216,12 @@ def main() -> int:
     _validate_fix_cycle(
         run_manifest, _load_final_report_data(report_path), failures
     )
-    validate_report(report_path, contract["required_agent_status_entries"], failures)
+    validate_report(
+        report_path,
+        contract["required_agent_status_entries"],
+        failures,
+        allow_unavailable_token_usage=team_state.get("leadRuntime") == "codex",
+    )
     validate_team_state_usage(team_state, failures)
 
     validate_phase_boundary(task_type, report_path, failures)

package/runtime/validators/validate_session_conformance.py

@@ -190,6 +190,117 @@ def _collect_lead_evidence(
     return evidence, None
 
 
+def _resolve_lead_events_path(
+    team_state: dict, project_root: Path
+) -> tuple[Path | None, str | None]:
+    raw = team_state.get("leadEventsPath") or (
+        (team_state.get("artifacts") or {}).get("leadEventsPath")
+        if isinstance(team_state.get("artifacts"), dict)
+        else ""
+    )
+    if not raw:
+        return None, (
+            "Codex lead event log path missing from team-state "
+            "(`leadEventsPath`) — leadRuntime=codex conformance cannot be verified."
+        )
+    path = Path(str(raw))
+    if not path.is_absolute():
+        path = project_root / path
+    if not path.is_file():
+        return None, (
+            f"Codex lead event log not found: {path} — leadRuntime=codex "
+            "conformance cannot be verified."
+        )
+    return path, None
+
+
+def _event_matches_run(event, team_state: dict, task_type: str, run_seq: str) -> bool:
+    task_key = str(team_state.get("taskKey", ""))
+    if event.lead_runtime != "codex":
+        return False
+    if task_key and event.task_key != task_key:
+        return False
+    return event.task_type == task_type and event.run_seq == run_seq
+
+
+def _progress_line_from_event(event) -> tuple[str, str, str] | None:
+    details = event.details
+    phase = details.get("phase")
+    if not isinstance(phase, str) or not phase:
+        line_candidate = details.get("line")
+        if isinstance(line_candidate, str):
+            match = _PROGRESS_LINE_RE.search(line_candidate)
+            if match:
+                phase = match.group("phase")
+        if not isinstance(phase, str) or not phase:
+            return None
+    line = details.get("line")
+    if not isinstance(line, str) or not line:
+        message = details.get("message")
+        tail = f" {message}" if isinstance(message, str) and message else ""
+        line = f"PROGRESS: {phase}{tail}"
+    return (event.timestamp, phase, line)
+
+
+def _sidecar_read_from_event(event) -> tuple[str, str] | None:
+    details = event.details
+    if event.event_type != "sidecar-read" and details.get("kind") != "implementation-sidecar":
+        return None
+    basename = details.get("basename")
+    if not isinstance(basename, str) or not basename:
+        raw_path = details.get("path") or details.get("filePath")
+        basename = Path(str(raw_path or "")).name
+    if basename not in _SIDECAR_BASENAMES:
+        return None
+    return (basename, event.timestamp)
+
+
+def _collect_codex_lead_evidence(
+    team_state: dict,
+    project_root: Path,
+    task_type: str,
+    suffix: str | None,
+) -> tuple[_LeadEvidence | None, str | None]:
+    if not suffix or "-" not in suffix:
+        return None, (
+            "Codex lead event log cannot be scoped because team-state filename "
+            "does not expose a run artifact suffix."
+        )
+    events_path, error = _resolve_lead_events_path(team_state, project_root)
+    if error:
+        return None, error
+
+    try:
+        from okstra_ctl.lead_events import LeadEventParseError, read_lead_events
+    except ImportError as exc:
+        return None, f"okstra_ctl.lead_events import failed — {exc}"
+
+    try:
+        events = read_lead_events(events_path)
+    except LeadEventParseError as exc:
+        return None, f"Codex lead event log is malformed — {exc}"
+
+    run_seq = suffix.rsplit("-", 1)[1]
+    evidence = _LeadEvidence(scanned_files=[events_path])
+    for event in events:
+        if not _event_matches_run(event, team_state, task_type, run_seq):
+            continue
+        if event.event_type in ("progress", "progress-checkpoint"):
+            progress = _progress_line_from_event(event)
+            if progress is not None:
+                evidence.progress.append(progress)
+        elif event.event_type in ("artifact-read", "sidecar-read"):
+            read = _sidecar_read_from_event(event)
+            if read is not None:
+                basename, timestamp = read
+                evidence.sidecar_reads.setdefault(basename, []).append(timestamp)
+
+    evidence.progress.sort()
+    for ts_list in evidence.sidecar_reads.values():
+        ts_list.sort()
+    return evidence, None
+
+
 def _convergence_rounds_ran(run_dir: Path, suffix: str | None) -> bool:
     """이 run 의 convergence state artifact 가 실제 round 를 1회 이상 돌았는지.
     auto-disable(`totalRounds: 0`)·artifact 부재는 phase-5.5 라인을 요구하지 않는다."""
@@ -422,14 +533,20 @@ def validate_session_conformance(
 
     run_dir = report_path.parent.parent  # reports/ 의 부모 = run 디렉터리
     _check_heartbeat_sidecars(run_dir, task_type, result.errors)
+    suffix = run_artifact_suffix(team_state_path)
 
-    evidence, error = _collect_lead_evidence(
-        team_state, team_state_path, project_root, claude_projects_dir
-    )
+    lead_runtime = team_state.get("leadRuntime", "") or "claude-code"
+    if lead_runtime == "codex":
+        evidence, error = _collect_codex_lead_evidence(
+            team_state, project_root, task_type, suffix
+        )
+    else:
+        evidence, error = _collect_lead_evidence(
+            team_state, team_state_path, project_root, claude_projects_dir
+        )
     if error:
         result.errors.append(error)
         return result
-    suffix = run_artifact_suffix(team_state_path)
     _check_progress_checkpoints(evidence, team_state, run_dir, suffix, result.errors)
     if task_type == "implementation":
         _check_implementation_sidecar_reads(evidence, result.errors)

package/src/codex-dispatch.mjs

@@ -0,0 +1,70 @@
+import { runPythonModule } from "./_python-helper.mjs";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra codex-dispatch — dispatch CLI-backed workers for a prepared Codex run
+
+Usage:
+  okstra codex-dispatch --project-root <dir> --run-manifest <path> \\
+    [--workers codex[,gemini[,report-writer]]] [--dry-run] \\
+    [--idle-timeout-seconds <n>] \\
+    [--enable-codex-report-writer --report-writer-codex-model <model>]
+
+This command reads an existing run manifest produced by 'okstra codex-run' and
+dispatches only Codex-side supported workers. When --workers is omitted, the
+command selects the supported subset of the run roster (codex/gemini, plus
+report-writer only when explicitly opted in). Codex and gemini use their
+existing wrappers. The report-writer role is available only through explicit
+Codex opt-in because the prepared manifest still records the Claude-side report
+writer model by default. Explicitly requesting unsupported workers such as
+claude fails.
+
+Missing worker prompt files are generated automatically from the run manifest
+and active-run-context. Existing prompt files are never overwritten.
+When the Codex report-writer path completes, this command also runs the
+idempotent post-report steps: token-usage substitution, render-views,
+spawn-followups, and validate-run.
+
+  --workspace-root and --okstra-bin are owned by this command.
+`;
+
+const OWNED_FLAGS = new Set(["--workspace-root", "--okstra-bin"]);
+
+function isOwnedFlag(arg) {
+  if (OWNED_FLAGS.has(arg)) return true;
+  return [...OWNED_FLAGS].some((flag) => arg.startsWith(`${flag}=`));
+}
+
+export function buildCodexDispatchArgs(args, paths) {
+  return [
+    "--workspace-root", paths.workspace,
+    "--okstra-bin", paths.bin,
+    ...args,
+  ];
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (args.length === 0) {
+    process.stdout.write(USAGE);
+    return 2;
+  }
+
+  const forbidden = args.find(isOwnedFlag);
+  if (forbidden) {
+    process.stderr.write(
+      `error: ${forbidden} is set by 'okstra codex-dispatch' itself — remove it from your args\n`,
+    );
+    return 2;
+  }
+
+  const paths = await resolvePaths();
+  const result = await runPythonModule({
+    module: "okstra_ctl.codex_dispatch",
+    args: buildCodexDispatchArgs(args, paths),
+    stdio: "inherit-stdout",
+  });
+  return result.code ?? 0;
+}

package/src/codex-run.mjs

@@ -0,0 +1,68 @@
+import { runPythonModule } from "./_python-helper.mjs";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra codex-run — prepare a render-only Codex lead task bundle
+
+This is the dry-run entry point for the Codex lead adapter. It forwards to
+\`python3 -m okstra_ctl.run --render-only --lead-runtime codex\`, materializes
+the normal okstra task bundle, and prints the rendered lead prompt without
+dispatching workers.
+
+Usage:
+  okstra codex-run --project-root <dir> --project-id <id> \\
+    --task-group <tg> --task-id <tid> --task-type <type> \\
+    --task-brief <path-or-rel> [--workers <list>] [--directive <text>] \\
+    [--lead-model <m>] [--claude-model <m>] [--codex-model <m>] \\
+    [--gemini-model <m>] [--report-writer-model <m>] \\
+    [--related-tasks <list>] [--base-ref <ref>] \\
+    [--clarification-response <path>] [--work-category <cat>] \\
+    [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>] \\
+    [--fix-cycle <yes|no>]
+
+  --render-only and --lead-runtime are owned by this command.
+  Worker dispatch is intentionally disabled here; use 'okstra codex-dispatch'
+  with the rendered run manifest for CLI-backed codex/gemini workers.
+`;
+
+const OWNED_FLAGS = new Set(["--workspace-root", "--render-only", "--lead-runtime"]);
+
+function isOwnedFlag(arg) {
+  if (OWNED_FLAGS.has(arg)) return true;
+  return [...OWNED_FLAGS].some((flag) => arg.startsWith(`${flag}=`));
+}
+
+export function buildCodexRunArgs(args, workspaceRoot) {
+  return [
+    "--workspace-root", workspaceRoot,
+    "--render-only",
+    "--lead-runtime", "codex",
+    ...args,
+  ];
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (args.length === 0) {
+    process.stdout.write(USAGE);
+    return 2;
+  }
+
+  const forbidden = args.find(isOwnedFlag);
+  if (forbidden) {
+    process.stderr.write(
+      `error: ${forbidden} is set by 'okstra codex-run' itself — remove it from your args\n`,
+    );
+    return 2;
+  }
+
+  const paths = await resolvePaths();
+  const result = await runPythonModule({
+    module: "okstra_ctl.run",
+    args: buildCodexRunArgs(args, paths.workspace),
+    stdio: "inherit-stdout",
+  });
+  return result.code ?? 0;
+}

package/src/doctor.mjs

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 import { fileExists, runProcess } from "./_proc.mjs";
+import { runtimeIncludesClaudeAssets, validateInstallRuntime } from "./install.mjs";
 
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
 const REQUIRED_SKILLS = ["okstra-setup", "okstra-run"];
@@ -11,6 +12,7 @@ const USAGE = `okstra doctor — diagnose the installed runtime
 
 Usage:
   okstra doctor               Run all checks and print a summary
+  okstra doctor --runtime <claude-code|codex|all>
   okstra doctor --json        Machine-readable result
 
 Checks:
@@ -20,9 +22,37 @@ Checks:
   - bash entrypoints present and executable in $HOME/.okstra/bin
   - agents/ directory exists inside the okstra package
   - canonical skills present at $HOME/.claude/skills/<name>/SKILL.md
+    (skipped with --runtime codex)
   - version stamp matches package version
 `;
 
+export function parseDoctorArgs(args) {
+  const result = {
+    jsonMode: false,
+    runtime: "claude-code",
+  };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--json") {
+      result.jsonMode = true;
+    } else if (arg === "--runtime" || arg.startsWith("--runtime=")) {
+      const value = arg.startsWith("--runtime=") ? arg.slice("--runtime=".length) : args[i + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--runtime requires one of: claude-code, codex, all");
+      }
+      result.runtime = validateInstallRuntime(value);
+      if (arg === "--runtime") i++;
+    } else {
+      throw new Error(`unknown argument '${arg}'`);
+    }
+  }
+  return result;
+}
+
+export function requiredSkillNamesForRuntime(runtime) {
+  return runtimeIncludesClaudeAssets(runtime) ? REQUIRED_SKILLS : [];
+}
+
 async function checkPython3() {
   const r = await runProcess("python3", ["--version"]);
   if (r.code !== 0) return { ok: false, detail: `python3 not found: ${r.stderr.trim() || "missing binary"}` };
@@ -74,7 +104,13 @@ export async function run(args) {
     process.stdout.write(USAGE);
     return 0;
   }
-  const jsonMode = args.includes("--json");
+  let opts;
+  try {
+    opts = parseDoctorArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n`);
+    return 2;
+  }
   const paths = await resolvePaths();
 
   const results = [
@@ -91,7 +127,7 @@ export async function run(args) {
     await check("bin: okstra-gemini-exec.sh", () => checkBashEntry(paths.bin, "okstra-gemini-exec.sh")),
     await check("bin: okstra-central.sh", () => checkBashEntry(paths.bin, "okstra-central.sh")),
     ...(await Promise.all(
-      REQUIRED_SKILLS.map((name) =>
+      requiredSkillNamesForRuntime(opts.runtime).map((name) =>
         check(`skill: ${name}`, async () => {
           const p = join(CLAUDE_SKILLS_DIR, name, "SKILL.md");
           return (await fileExists(p))
@@ -109,8 +145,8 @@ export async function run(args) {
 
   const allOk = results.every((r) => r.ok);
 
-  if (jsonMode) {
-    process.stdout.write(`${JSON.stringify({ ok: allOk, paths, checks: results }, null, 2)}\n`);
+  if (opts.jsonMode) {
+    process.stdout.write(`${JSON.stringify({ ok: allOk, runtime: opts.runtime, paths, checks: results }, null, 2)}\n`);
     return allOk ? 0 : 1;
   }