okstra 0.144.0 → 0.146.0

package/runtime/python/okstra_ctl/worker_liveness.py

@@ -15,10 +15,10 @@ Two probes, matching the two ways a pending worker goes quiet:
 * ``--audit`` — an in-process worker audit sidecar. Stale past the heartbeat
   cadence (or present with no heartbeat at all) means the worker hung. Uses
   the same line shape and budget the Phase 7 validator applies.
-* ``--prompt`` — a CLI-wrapper prompt-history path. Neither `<prompt>.log` nor
-  `<prompt>.status.json` past the launch grace means the wrapper never ran —
-  the dispatch itself failed, which no artifact otherwise distinguishes from a
-  worker that has merely not finished.
+* ``--team-state`` + ``--worker`` — a CLI-wrapper assignment. Neither the
+  worker's `<prompt>.log` nor `<prompt>.status.json` past the launch grace means
+  the wrapper never ran. The grace starts at the persisted dispatch timestamp,
+  not when the prompt was materialized.
 """
 from __future__ import annotations
 
@@ -28,6 +28,7 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
+from okstra_ctl.dispatch_state import DispatchError, load_json_object
 from okstra_ctl.worker_heartbeat import (
     HEARTBEAT_MAX_GAP_SECONDS,
     latest_heartbeat,
@@ -80,43 +81,97 @@ def probe_heartbeat(sidecar: Path, now: datetime, max_idle: float) -> dict:
     }
 
 
-def probe_launch(prompt: Path, now: datetime, grace: float) -> dict:
+def probe_launch(
+    prompt: Path, dispatched_at: datetime, now: datetime, grace: float
+) -> dict:
     """Whether the wrapper behind *prompt* ever started."""
     log, status = _log_path(prompt), Path(f"{prompt}.status.json")
     probe = {"kind": "launch", "path": str(prompt)}
     if log.exists() or status.exists():
         return {**probe, "state": "live", "reason": ""}
-    if not prompt.is_file():
-        return {**probe, "state": "pending", "reason": "prompt history not written yet"}
-    waited = now.timestamp() - prompt.stat().st_mtime
+    waited = (now - dispatched_at).total_seconds()
     if waited <= grace:
-        return {**probe, "state": "pending", "reason": "within launch grace"}
+        return {
+            **probe,
+            "state": "pending",
+            "waitedSeconds": int(waited),
+            "reason": "within launch grace",
+        }
     return {
         **probe,
         "state": "did-not-launch",
         "waitedSeconds": int(waited),
         "reason": (
             f"neither {log.name} nor {status.name} exists {int(waited)}s after the "
-            f"prompt was written (grace {int(grace)}s)"
+            f"dispatch started (grace {int(grace)}s)"
         ),
     }
 
 
 def probe_all(
     audits: list[str],
-    prompts: list[str],
+    launches: list[tuple[str, datetime]],
     *,
     now: datetime,
     max_idle: float,
     launch_grace: float,
 ) -> dict:
     probes = [probe_heartbeat(Path(p), now, max_idle) for p in audits]
-    probes += [probe_launch(Path(p), now, launch_grace) for p in prompts]
+    probes += [
+        probe_launch(Path(prompt), dispatched_at, now, launch_grace)
+        for prompt, dispatched_at in launches
+    ]
     unhealthy = [p for p in probes if p["state"] in ("stalled", "did-not-launch")]
     return {"ok": not unhealthy, "checkedAt": now.isoformat(), "probes": probes,
             "unhealthy": unhealthy}
 
 
+def _parse_utc(value: object, label: str) -> datetime:
+    if not isinstance(value, str) or not value:
+        raise DispatchError(f"{label} must be a UTC ISO timestamp")
+    try:
+        instant = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise DispatchError(f"{label} must be a UTC ISO timestamp") from exc
+    if instant.tzinfo is None or instant.utcoffset() != timezone.utc.utcoffset(instant):
+        raise DispatchError(f"{label} must be a UTC ISO timestamp")
+    return instant.astimezone(timezone.utc)
+
+
+def _project_root_for_team_state(team_state_path: Path) -> Path:
+    for parent in team_state_path.resolve().parents:
+        if parent.name == ".okstra":
+            return parent.parent
+    raise DispatchError(
+        f"team-state is outside a project .okstra directory: {team_state_path}"
+    )
+
+
+def _launch_target(team_state_value: str, worker_id: str) -> tuple[str, datetime]:
+    team_state_path = Path(team_state_value).resolve()
+    state = load_json_object(team_state_path, "team-state")
+    workers = state.get("workers")
+    if not isinstance(workers, list):
+        raise DispatchError(f"team-state workers must be an array: {team_state_path}")
+    worker = next(
+        (
+            row for row in workers
+            if isinstance(row, dict) and row.get("workerId") == worker_id
+        ),
+        None,
+    )
+    if worker is None:
+        raise DispatchError(f"team-state has no workerId={worker_id}: {team_state_path}")
+    prompt_value = worker.get("promptPath")
+    if not isinstance(prompt_value, str) or not prompt_value.strip():
+        raise DispatchError(f"worker {worker_id} has no promptPath")
+    prompt = Path(prompt_value)
+    if not prompt.is_absolute():
+        prompt = _project_root_for_team_state(team_state_path) / prompt
+    dispatched_at = _parse_utc(worker.get("startedAt"), f"worker {worker_id} startedAt")
+    return str(prompt), dispatched_at
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="okstra worker-liveness",
@@ -124,12 +179,10 @@ def main(argv: list[str] | None = None) -> int:
     )
     parser.add_argument("--audit", action="append", default=[],
                         help="in-process worker audit sidecar path (repeatable)")
-    parser.add_argument("--prompt", action="append", default=[],
-                        help="CLI-wrapper (codex/antigravity) prompt-history path "
-                             "(repeatable). Only the wrappers write the artifacts "
-                             "this probe looks for, so passing an in-process "
-                             "claude-worker path here always reports "
-                             "did-not-launch — probe those with --audit")
+    parser.add_argument("--team-state", action="append", default=[],
+                        help="team-state path for a CLI-wrapper assignment (repeatable)")
+    parser.add_argument("--worker", action="append", default=[],
+                        help="worker id paired with --team-state (repeatable)")
     parser.add_argument("--max-idle", type=float, default=HEARTBEAT_MAX_GAP_SECONDS,
                         help="heartbeat staleness budget in seconds")
     parser.add_argument("--launch-grace", type=float, default=DEFAULT_LAUNCH_GRACE_SECONDS,
@@ -137,12 +190,22 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
     args = parser.parse_args(argv)
 
-    if not args.audit and not args.prompt:
-        parser.error("pass at least one --audit or --prompt path")
+    if len(args.team_state) != len(args.worker):
+        parser.error("each --team-state must have one paired --worker")
+    if not args.audit and not args.team_state:
+        parser.error("pass at least one --audit or --team-state/--worker pair")
+
+    try:
+        launches = [
+            _launch_target(team_state, worker)
+            for team_state, worker in zip(args.team_state, args.worker, strict=True)
+        ]
+    except DispatchError as exc:
+        parser.error(str(exc))
 
     result = probe_all(
         args.audit,
-        args.prompt,
+        launches,
         now=datetime.now(timezone.utc),
         max_idle=args.max_idle,
         launch_grace=args.launch_grace,

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -90,8 +90,8 @@ def report_writer_prompt_body(
         "",
         "## Role",
         (
-            "You are the Report writer worker. Author the final-report data.json "
-            "and the worker-results audit file."
+            "You are the Report writer worker. Author the final-report data.json, "
+            "its rendered Markdown sibling, and the worker-result pointer."
         ),
         "",
         "## Task",
@@ -104,9 +104,15 @@ def report_writer_prompt_body(
         mcp_pointer_line(),
         "",
         "## Output Contract",
-        "You are the author of TWO files:",
+        "You are the author of THREE files:",
         "- The final-report data.json at Result Path.",
-        "- The worker-results audit file at Audit sidecar path.",
+        "- The rendered Markdown sibling produced through okstra render-final-report.",
+        "- The worker-result pointer at Worker Result Path.",
+        (
+            "Keep the pointer to three entries: the data.json path, rendered "
+            "Markdown path, and Convergence state input path."
+        ),
+        "Maintain the separate audit sidecar at Audit sidecar path.",
         (
             'After writing the data.json, invoke "okstra render-final-report '
             '<Result Path>" so the markdown sibling is rendered before you return.'
@@ -129,6 +135,7 @@ def report_writer_input_lines(
         ("Clarification response", instruction_path(manifest, active_context, "clarificationResponsePath")),
         ("Final report template", instruction_path(manifest, active_context, "finalReportTemplatePath")),
         ("Final report schema", instruction_path(manifest, active_context, "finalReportSchemaPath")),
+        ("Convergence state", run_path(manifest, active_context, "convergenceStatePath")),
         ("Worker results directory", _string_value(manifest.get("workerResultsDirectoryPath"))),
     ]
     lines = existing_input_lines(inputs)
@@ -171,6 +178,19 @@ def instruction_path(
     return _string_value(manifest.get(key))
 
 
+def run_path(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    key: str,
+) -> str:
+    run = active_context.get("run")
+    if isinstance(run, Mapping):
+        value = _string_value(run.get(key))
+        if value:
+            return value
+    return _string_value(manifest.get(key))
+
+
 def mcp_pointer_line() -> str:
     return (
         '**MCP servers:** follow the task brief\'s "## Available MCP Servers" '

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -19,6 +19,8 @@ MAX_FINAL_VERIFICATION_BODY_LINES = 96
 PROMPT_DELIVERY_MODE_HEADER = "**Prompt Delivery Mode:**"
 PROMPT_DELIVERY_MODES = frozenset({"eager-include", "lazy-path-reference"})
 MODEL_HEADER = "**Model:**"
+TASK_TYPE_HEADER = "**Task Type:**"
+FORBIDDEN_ACTIONS_HEADER = "**Forbidden actions:**"
 
 _DIRECTIVE_HEADING = "## Run-specific directive"
 _WORKER_ERROR_CONTRACT_HEADER = "**Worker Error Contract Path:**"
@@ -177,6 +179,61 @@ def validate_analysis_prompt_set(prompts: Mapping[str, str]) -> list[str]:
     return [f"normalized initial analysis prompts differ across workers: {workers}"]
 
 
+def validate_reverify_prompt(
+    text: str,
+    *,
+    task_type: str,
+    forbidden_actions: str,
+) -> list[str]:
+    """Require the active phase boundary in a lightweight reverify prompt."""
+    normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+    errors: list[str] = []
+    task_values = _header_values(normalized, TASK_TYPE_HEADER)
+    if task_values != [task_type]:
+        errors.append(
+            f"exactly one {TASK_TYPE_HEADER} {task_type} header is required"
+        )
+    action_blocks = _section_values(normalized, FORBIDDEN_ACTIONS_HEADER)
+    if len(action_blocks) != 1:
+        errors.append("exactly one **Forbidden actions:** block is required")
+    elif action_blocks[0] != forbidden_actions.strip():
+        errors.append(
+            "Forbidden actions block must exactly match active-run-context "
+            "workflow.forbiddenActions"
+        )
+
+    expected_task_header = f"{TASK_TYPE_HEADER} {task_type}"
+    boundary_position = normalized.find(expected_task_header)
+    read_scope_position = normalized.find("**Read scope:**")
+    if boundary_position >= 0 and (
+        read_scope_position < 0 or read_scope_position > boundary_position
+    ):
+        errors.append("phase boundary block must follow the reverify anchor headers")
+    first_heading = re.search(r"(?m)^##\s+", normalized)
+    if (
+        boundary_position >= 0
+        and first_heading is not None
+        and boundary_position > first_heading.start()
+    ):
+        errors.append("phase boundary block must precede reverify instructions")
+    return errors
+
+
+def _section_values(text: str, header: str) -> list[str]:
+    lines = text.splitlines()
+    values: list[str] = []
+    for index, line in enumerate(lines):
+        if line.strip() != header:
+            continue
+        body: list[str] = []
+        for candidate in lines[index + 1:]:
+            stripped = candidate.strip()
+            if stripped.startswith("## ") or re.match(r"^\*\*[^*]+:\*\*", stripped):
+                break
+            body.append(candidate)
+        values.append("\n".join(body).strip())
+    return values
+
 
 def validate_initial_prompt_records(
     *,

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Any, Literal, Mapping
 
+from .analysis_inputs import ANALYSIS_TASK_TYPES
+
 
 PromptAudience = Literal[
     "analysis",
@@ -41,6 +43,7 @@ SUPPORTED_TASK_TYPES = frozenset({
     "implementation",
     "final-verification",
     "release-handoff",
+    *ANALYSIS_TASK_TYPES,
 })
 WORKER_PREAMBLE_FILENAME_BY_AUDIENCE = {
     "analysis": "worker-prompt-preamble.md",

package/runtime/python/okstra_ctl/worker_state.py

@@ -0,0 +1,65 @@
+"""Authoritative worker status transitions for one persisted team-state."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .dispatch_state import DispatchError, WORKER_STATUSES, transition_worker_status
+
+
+def _validated_team_state_path(value: str) -> Path:
+    path = Path(value).resolve()
+    if not any(parent.name == ".okstra" for parent in (path.parent, *path.parents)):
+        raise DispatchError(
+            f"team-state is outside a project .okstra directory: {path}"
+        )
+    return path
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="okstra worker-state")
+    commands = parser.add_subparsers(dest="command", required=True)
+    transition = commands.add_parser(
+        "transition", help="atomically transition one worker status"
+    )
+    transition.add_argument("--team-state", required=True)
+    transition.add_argument("--worker", required=True)
+    transition.add_argument("--status", required=True, choices=sorted(WORKER_STATUSES))
+    transition.add_argument("--reason", default="")
+    transition.add_argument("--model", default="")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        team_state_path = _validated_team_state_path(args.team_state)
+        transition_worker_status(
+            team_state_path,
+            args.worker,
+            args.status,
+            args.reason,
+            model_execution_value=args.model,
+        )
+    except DispatchError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "teamStatePath": str(team_state_path),
+                "workerId": args.worker,
+                "status": args.status,
+            },
+            ensure_ascii=False,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/workflow.py

@@ -12,6 +12,8 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
+from okstra_ctl.analysis_inputs import ANALYSIS_TASK_TYPES
+
 PHASE_SEQUENCE = [
     "requirements-discovery",
     "error-analysis",
@@ -24,6 +26,7 @@ PHASE_SEQUENCE = [
 DEFAULT_NEXT_PHASE = {
     "requirements-discovery": "pending-routing-decision",
     "improvement-discovery": "pending-routing-decision",
+    **{task_type: "pending-routing-decision" for task_type in ANALYSIS_TASK_TYPES},
     "error-analysis": "implementation-planning",
     "implementation-planning": "implementation",
     "implementation": "final-verification",
@@ -56,6 +59,25 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - Phase 5.5 consensus classification (full / partial / contested / worker-unique)"
         ),
     },
+    "project-analysis": {
+        "allowed": (
+            "  - components, dependency directions, entry points, repositories, and external integrations\n"
+            "  - shallow feature index and scan scope\n"
+        ),
+    },
+    "feature-analysis": {
+        "allowed": (
+            "  - confirmed target and normal, alternate, and failure flows\n"
+            "  - rules, state transitions, external calls, and test coverage scope\n"
+        ),
+    },
+    "change-impact-analysis": {
+        "allowed": (
+            "  - preserved behavior, impacted items, and dependency propagation\n"
+            "  - test and operational impact\n"
+            "  - constraints and open decisions passed to implementation-planning\n"
+        ),
+    },
     "error-analysis": {
         "allowed": (
             "  - symptom and trigger evidence\n"

package/runtime/python/okstra_token_usage/antigravity.py

@@ -14,6 +14,9 @@ from __future__ import annotations
 from pathlib import Path
 
 
+PRINT_MODE_USAGE_NOTE = "N/A — print mode exposes no transcript"
+
+
 def antigravity_session_total(json_path: Path) -> dict:
     return {"totalTokens": 0, "available": False}
 

package/runtime/python/okstra_token_usage/codex.py

@@ -2,9 +2,13 @@
 from __future__ import annotations
 
 import json
+import os
 from pathlib import Path
 from .jsonl_io import iter_jsonl
-from .paths import CODEX_SESSIONS, ts_in_window
+from .paths import CODEX_SESSIONS, codex_session_roots, ts_in_window
+
+
+_DEFAULT_CODEX_SESSIONS = CODEX_SESSIONS
 
 
 def codex_session_total(jsonl_path: Path) -> dict:
@@ -52,33 +56,60 @@ def find_codex_session(cwd: Path, started_at: str, ended_at: str) -> Path | None
     return sessions[-1] if sessions else None
 
 
-def find_codex_sessions(cwd: Path, started_at: str, ended_at: str) -> list[Path]:
+def _session_metadata(path: Path) -> tuple[str, str] | None:
+    try:
+        with path.open() as fh:
+            first = fh.readline()
+    except OSError:
+        return None
+    if not first:
+        return None
+    try:
+        record = json.loads(first)
+    except json.JSONDecodeError:
+        return None
+    if record.get("type") != "session_meta":
+        return None
+    payload = record.get("payload") or {}
+    timestamp = payload.get("timestamp") or record.get("timestamp") or ""
+    return str(payload.get("cwd") or ""), timestamp
+
+
+def find_codex_sessions(
+    cwd: Path,
+    started_at: str,
+    ended_at: str,
+    *,
+    session_roots: tuple[Path, ...] | None = None,
+) -> list[Path]:
     """Find codex rollout jsonls whose meta.cwd matches the window."""
-    if not CODEX_SESSIONS.is_dir() or not started_at or not ended_at:
+    if not started_at or not ended_at:
         return []
+    if session_roots is None:
+        if CODEX_SESSIONS != _DEFAULT_CODEX_SESSIONS:
+            session_roots = (CODEX_SESSIONS,)
+        else:
+            session_roots = codex_session_roots(Path.home(), os.environ)
     target_cwd = str(cwd)
     candidates: list[tuple[str, Path]] = []
-    for p in CODEX_SESSIONS.rglob("rollout-*.jsonl"):
-        try:
-            with p.open() as fh:
-                first = fh.readline()
-        except OSError:
-            continue
-        if not first:
-            continue
-        try:
-            rec = json.loads(first)
-        except json.JSONDecodeError:
-            continue
-        if rec.get("type") != "session_meta":
-            continue
-        payload = rec.get("payload") or {}
-        if payload.get("cwd") != target_cwd:
-            continue
-        ts = payload.get("timestamp") or rec.get("timestamp") or ""
-        if not ts_in_window(ts, started_at, ended_at):
+    seen: set[Path] = set()
+    for root in session_roots:
+        if not root.is_dir():
             continue
-        candidates.append((ts, p))
+        for p in root.rglob("rollout-*.jsonl"):
+            identity = p.resolve()
+            if identity in seen:
+                continue
+            seen.add(identity)
+            metadata = _session_metadata(p)
+            if metadata is None:
+                continue
+            session_cwd, ts = metadata
+            if session_cwd != target_cwd:
+                continue
+            if not ts_in_window(ts, started_at, ended_at):
+                continue
+            candidates.append((ts, p))
     if not candidates:
         return []
     candidates.sort()