okstra 0.176.1 → 0.177.1

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -65,6 +65,7 @@ from .domain.worker_runtime import (
 from .ports.worker_runtime import WorkerRuntimePort
 from .execution_identity import Attempt, Invocation, RoleExecution, model_spec_digest
 from .execution_manifest import (
+    ExecutionManifestError,
     finish_attempt_mutation,
     read_execution_manifest,
     record_invocation_attempt,
@@ -107,7 +108,11 @@ from .worker_prompt_headers import (
     resolve_errors_log_path,
 )
 from .worker_artifact_paths import audit_sidecar_rel
-from .wrapper_status import read_wrapper_status, status_path_for_prompt
+from .wrapper_status import (
+    log_path_for_prompt,
+    read_wrapper_status,
+    status_path_for_prompt,
+)
 from .worker_request import verifier_extra_dirs
 from .write_policy import (
     WriteEnforcement,
@@ -204,11 +209,23 @@ def verify_served_model(
         return attestation
     if role_execution.model_ref is None or not attestation.normalized_model_ref:
         raise DispatchError("served model differs from selected model")
+    # An unregistered ref and a genuine substitution are different failures.
+    # Folding both into "differs from selected" hid which one happened, and a
+    # catalog gap reads as a provider swapping the model out from under us.
     try:
         selected = pool.resolve(role_execution.model_ref)
+    except ValueError as exc:
+        raise DispatchError(
+            f"selected model is not in the catalog: {role_execution.model_ref}"
+        ) from exc
+    try:
         observed = pool.resolve(attestation.normalized_model_ref)
     except ValueError as exc:
-        raise DispatchError("served model differs from selected model") from exc
+        raise DispatchError(
+            "served model is not in the catalog: "
+            f"{attestation.normalized_model_ref} "
+            f"(provider reported {attestation.observed_model!r})"
+        ) from exc
     expected_level = "channel" if observed.version_kind == "channel" else "exact"
     if attestation.level != expected_level:
         raise DispatchError("served model attestation level is inconsistent")
@@ -394,11 +411,38 @@ def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
             if result != 0:
                 return result
         return 0
-    handles = [_spawn_job(plan, job, 1) for job in plan.jobs]
+    round_artifact_paths = _round_artifact_paths(plan)
+    handles = [
+        _spawn_job(plan, job, 1, batch_artifact_paths=round_artifact_paths)
+        for job in plan.jobs
+    ]
     _record_dispatch_facts(plan.team_state_path, _mode_from_handles(handles))
     return 0
 
 
+def _round_artifact_paths(plan: DispatchPlan) -> tuple[Path, ...]:
+    """Every artifact this round's workers are entitled to write.
+
+    These jobs run concurrently into one shared artifact root, so each worker's
+    own result, audit sidecar, status sidecar and live log land inside every
+    sibling's audit window. Judged against one worker's policy alone, the
+    siblings' writes read as unauthorized artifact-root changes and failed a
+    whole round of otherwise clean verifiers.
+
+    They travel as orchestrator paths rather than as a widened policy union
+    because the snapshot carries orchestrator paths and the audit excuses them
+    without consulting a policy — while `_validate_snapshot_authority` compares
+    the recorded policy digests exactly, so a snapshot taken under a union can
+    no longer be closed by the per-job policy the awaiting process rebuilds.
+    Same effect on the verdict; no coupling between two processes' plans.
+    """
+    return tuple(
+        path
+        for job in plan.jobs
+        for path in _worker_artifact_paths(plan, job)
+    )
+
+
 def dispatch_cli_wrapper_plan(plan: DispatchPlan) -> int:
     """Start one dependency-free CLI batch before collecting any worker."""
     if any(job.backend != BACKEND_CLI_WRAPPER for job in plan.jobs):
@@ -1263,19 +1307,40 @@ def _jobs_from_file(
     )
 
 
-def _spawn_job(plan: DispatchPlan, job: WorkerJob, attempt: int) -> WorkerHandle:
+def _spawn_job(
+    plan: DispatchPlan,
+    job: WorkerJob,
+    attempt: int,
+    *,
+    batch_artifact_paths: Sequence[Path] = (),
+) -> WorkerHandle:
     job = _prepare_job_attempt(plan, job, attempt)
-    contract = _persisted_write_contract(plan, job)
-    policies = (contract[0],) if contract else ()
-    snapshot = None
-    if contract is not None and contract[1].mutation_audit == "batch":
-        snapshot_path = _mutation_snapshot_path(job)
-        if snapshot_path.is_file():
-            snapshot = MutationSnapshot.from_payload(
-                _load_json_object(snapshot_path, "mutation audit snapshot")
-            )
-        else:
-            snapshot = _mutation_snapshot(plan, policies, (job,))
+    # Everything between recording the attempt and starting the worker runs
+    # before any worker process exists. A failure here used to leave the attempt
+    # `started` forever: the manifest then refused attempt 1 again ("next
+    # attempt must be 2") and refused attempt 2 as well, because the prompt
+    # metadata still said attempt 1. The invocation had no way forward and the
+    # lead had to mint a new invocation id and prompt path to escape.
+    try:
+        contract = _persisted_write_contract(plan, job)
+        policies = (contract[0],) if contract else ()
+        snapshot = None
+        if contract is not None and contract[1].mutation_audit == "batch":
+            snapshot_path = _mutation_snapshot_path(job)
+            if snapshot_path.is_file():
+                snapshot = MutationSnapshot.from_payload(
+                    _load_json_object(snapshot_path, "mutation audit snapshot")
+                )
+            else:
+                snapshot = _mutation_snapshot(
+                    plan,
+                    policies,
+                    (job,),
+                    round_artifact_paths=batch_artifact_paths,
+                )
+    except Exception:
+        _abandon_unstarted_attempt(plan, job, attempt)
+        raise
     handle = replace(
         _start_job(plan, job),
         mutation_snapshot=snapshot,
@@ -1373,11 +1438,14 @@ def _mutation_snapshot(
     plan: DispatchPlan,
     policies: Sequence[WritePolicy],
     jobs: Sequence[WorkerJob],
+    round_artifact_paths: Sequence[Path] = (),
 ) -> MutationSnapshot:
     sidecars = tuple(_mutation_snapshot_path(job) for job in jobs)
     snapshot = ExecutionMutationAudit().snapshot(
         policies,
         orchestrator_paths=(
+            *round_artifact_paths,
+            *_run_errors_log_path(plan),
             plan.manifest_path,
             plan.team_state_path,
             Path(f"{plan.team_state_path}.lock"),
@@ -1478,7 +1546,13 @@ def _worker_artifact_paths(plan: DispatchPlan, job: WorkerJob) -> tuple[Path, ..
         *job.completion_paths,
         Path(audit_sidecar_rel(str(job.worker_result_path))),
         status_path_for_prompt(job.prompt_path),
-        job.prompt_path.with_suffix(job.prompt_path.suffix + ".log"),
+        log_path_for_prompt(job.prompt_path),
+        # The prompt's three derived files are written together and belong in
+        # one list. The audit snapshot used to be listed only for the job whose
+        # snapshot it was, so a sibling's snapshot — written by okstra as that
+        # sibling started — landed inside this worker's window as an
+        # unauthorized artifact-root change.
+        _mutation_snapshot_path(job),
     }
     error_logs = active_context.get("errorLogs")
     if isinstance(error_logs, Mapping):
@@ -1490,6 +1564,26 @@ def _worker_artifact_paths(plan: DispatchPlan, job: WorkerJob) -> tuple[Path, ..
     return tuple(sorted(paths, key=str))
 
 
+def _run_errors_log_path(plan: DispatchPlan) -> tuple[Path, ...]:
+    """The run-level errors log, which the lead appends to while workers run.
+
+    The lead contract requires it to record an observed worker failure as soon
+    as it happens, so a worker still running at that moment sees the write. It
+    is a lead-owned run artifact like the manifest and the lead events log, and
+    is listed for the same reason.
+    """
+    active_context = _load_optional_json(
+        plan.project_root, plan.manifest.get("activeRunContextPath")
+    )
+    error_logs = active_context.get("errorLogs")
+    if not isinstance(error_logs, Mapping):
+        return ()
+    value = _string_value(error_logs.get("runErrorsLogPath"))
+    if not value:
+        return ()
+    return (_resolve_project_path(plan.project_root, value),)
+
+
 
 
 def _job_for_attempt(job: WorkerJob, attempt: int) -> WorkerJob:
@@ -1840,6 +1934,35 @@ def _out_of_plan_edit_paths(result_path: Path) -> tuple[str, ...]:
     )
 
 
+def _abandon_unstarted_attempt(
+    plan: DispatchPlan, job: WorkerJob, attempt: int
+) -> None:
+    """Close an attempt whose worker never started, so a retry can follow it.
+
+    `failed-no-mutation` is the truthful status: the dispatch died before the
+    worker process existed, so nothing wrote anything. It is also the only
+    terminal status the manifest lets another attempt follow.
+    """
+    if not job.has_execution_identity:
+        return
+    try:
+        finish_attempt_mutation(
+            plan.manifest_path,
+            invocation_ref=job.invocation_ref,
+            attempt=attempt,
+            finished_at=_utc_now(),
+            status="failed-no-mutation",
+            result_path=None,
+            error_path=None,
+            change_summary={},
+            task_key=_require_string(plan.manifest, "taskKey"),
+        )
+    except (ExecutionManifestError, DispatchError, OSError):
+        # The original dispatch failure is what the caller needs to see; a
+        # manifest that cannot be closed here is reported by the next read.
+        return
+
+
 def _finish_manifest_attempt(
     plan: DispatchPlan,
     job: WorkerJob,
@@ -2171,7 +2294,7 @@ def _wrapper_log_tail(job: WorkerJob) -> str | None:
     some process exited 1. Capped well under the writer's own excerpt limit
     because a whole record must stay inside one atomic `PIPE_BUF` append.
     """
-    log_path = job.prompt_path.with_suffix(job.prompt_path.suffix + ".log")
+    log_path = log_path_for_prompt(job.prompt_path)
     try:
         with log_path.open("rb") as handle:
             handle.seek(0, 2)

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -31,6 +31,8 @@ from typing import Any, Callable, Mapping, Sequence
 from . import cmux
 from .agent_invocation import (
     AgentInvocationError,
+    AgentModelAssignment,
+    InvocationMetadataIdentity,
     agent_model_assignment_from_payload,
     invocation_metadata_identity,
     v2_role_assignment_authority_errors,
@@ -57,7 +59,7 @@ from .worker_prompt_contract import (
 from .worker_runner import LIVE, QUIET
 from .worker_request import verifier_extra_dirs
 from .worker_artifact_paths import audit_sidecar_rel
-from .wrapper_status import status_path_for_prompt
+from .wrapper_status import log_path_for_prompt, status_path_for_prompt
 from .write_policy import (
     build_invocation_write_contract,
     planned_paths_from_run_manifest,
@@ -104,6 +106,14 @@ WORKTREE_TASK_TYPES = frozenset({"implementation", "final-verification"})
 WORKER_STATUSES = frozenset(
     {"in-progress", "completed", "timeout", "error", "not-run"}
 )
+# Which of those mean the dispatch is still expected to produce something. Two
+# readers key off this split — `team reclaim` closes a finished dispatch's pane
+# and must never touch a live one, and the compact-reminder hook calls a run
+# in-flight when any dispatch is still here. Both restated the terminal four
+# locally before, so a sixth status would have read as finished in one place and
+# as live in the other.
+NON_TERMINAL_WORKER_STATUSES = frozenset({"in-progress"})
+TERMINAL_WORKER_STATUSES = WORKER_STATUSES - NON_TERMINAL_WORKER_STATUSES
 REASON_REQUIRED_STATUSES = frozenset({"timeout", "error", "not-run"})
 
 
@@ -564,6 +574,9 @@ def record_verified_agent_dispatch(
     if (
         enforcement_mode == "host-native-spec-link-gate"
         and assignment.runner != "native-session"
+        and not _is_current_session_lead(
+            run_manifest_path, execution_identity, assignment
+        )
     ):
         raise DispatchError(
             "host-native enforcement requires a native-session assignment"
@@ -718,6 +731,50 @@ def record_verified_agent_dispatch(
     return record
 
 
+def _is_current_session_lead(
+    manifest_path: Path,
+    execution_identity: InvocationMetadataIdentity | None,
+    assignment: AgentModelAssignment,
+) -> bool:
+    """Report whether this dispatch is the lead attesting its own session.
+
+    A current-session lead has no model binding, so the run manifest projects
+    its assignment as ``cli-wrapper`` while the execution manifest records the
+    participant as ``current-session``. It runs through no dispatch boundary at
+    all: the spec link is the lead associating the already-running session with
+    its verified invocation specification, which is what the host-native gate
+    records. Keyed on the execution manifest's own participant row rather than
+    on the projected runner string, so a genuine cli-wrapper worker never
+    reaches the native gate.
+    """
+    if execution_identity is None or assignment.runner == "native-session":
+        return False
+    manifest = read_execution_manifest(manifest_path)
+    if manifest.legacy:
+        return False
+    participant = next(
+        (
+            row for row in manifest.participant_assignments
+            if row.participant_ref == execution_identity.participant_ref
+        ),
+        None,
+    )
+    execution = next(
+        (
+            row for row in manifest.role_executions
+            if row.role_execution_ref == execution_identity.role_execution_ref
+        ),
+        None,
+    )
+    return (
+        participant is not None
+        and execution is not None
+        and execution.role == "leader"
+        and participant.runner == "current-session"
+        and participant.entry_mode == "current-session"
+    )
+
+
 def _agent_write_contract(
     project_root: Path,
     manifest_path: Path,
@@ -814,7 +871,7 @@ def _manifest_worker_write_paths(
         result,
         Path(audit_sidecar_rel(str(result))),
         status_path_for_prompt(prompt_path),
-        prompt_path.with_suffix(prompt_path.suffix + ".log"),
+        log_path_for_prompt(prompt_path),
     }
     active_value = authority.get("activeRunContextPath")
     active = (
@@ -871,7 +928,7 @@ def _prompt_write_paths(
         _project_or_absolute(project_root, value) for value in artifact_values
     }
     artifacts.add(status_path_for_prompt(prompt_path))
-    artifacts.add(prompt_path.with_suffix(prompt_path.suffix + ".log"))
+    artifacts.add(log_path_for_prompt(prompt_path))
     worktree_value = values.get("Worktree")
     worktree = (
         _project_or_absolute(project_root, worktree_value)

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -171,7 +171,10 @@ class ExecutionMutationAudit:
             before.scratch_digests, after.scratch_digests
         )
         source_changes = _source_changes(changed, rows, before)
-        git_changed = before.git_projection != after.git_projection
+        # Reported and, through `_retry_allowed`, load-bearing: a stat-cache
+        # refresh must not read as "this worker touched Git" and must not
+        # withhold the retry a worker that failed for another reason is owed.
+        git_changed = _stable_git_projection(before) != _stable_git_projection(after)
         violations = _policy_violations(
             before,
             after,
@@ -250,6 +253,22 @@ def _maximum_precision(policy: WritePolicy) -> str:
     return policy.maximum_boundary_precision
 
 
+_INSTALLED_DEPENDENCY_DIRS = frozenset({"node_modules"})
+"""Trees a package manager installs, which no worker authored and no policy can
+enumerate.
+
+Excluded for the same reason `.git` is: the audit asks whether the worker
+changed *source*, and these hold neither source nor run artifacts. What forced
+the entry is that the tools inside them write to themselves — a `final-verification`
+verifier running the Tier 1 / Tier 2 suites its own profile mandates had Vitest
+persist `node_modules/.vite/vitest/<hash>/results.json`, and that single cache
+file failed both acceptance verifiers of an otherwise clean stage.
+
+One ecosystem, because one is what has been observed. A second name belongs here
+when a run produces the same evidence for it, not before.
+"""
+
+
 def _content_snapshot(root: Path, generated: frozenset[str]) -> dict[str, str]:
     rows: dict[str, str] = {}
     for current, directories, filenames in os.walk(root, followlinks=False):
@@ -258,7 +277,11 @@ def _content_snapshot(root: Path, generated: frozenset[str]) -> dict[str, str]:
         for name in sorted(directories):
             path = current_path / name
             relative_path = path.relative_to(root)
-            if name == ".git" or _excluded(relative_path, generated):
+            if (
+                name == ".git"
+                or name in _INSTALLED_DEPENDENCY_DIRS
+                or _excluded(relative_path, generated)
+            ):
                 continue
             if path.is_symlink():
                 rows[relative_path.as_posix()] = _path_digest(path)
@@ -473,7 +496,7 @@ def _policy_violations(
 ) -> list[str]:
     if all(policy.source_mode == "source-readonly" for policy in policies):
         failures = ["readonly source changed"] if source_changes else []
-        if before.git_projection != after.git_projection:
+        if _stable_git_projection(before) != _stable_git_projection(after):
             failures.append("gitPolicy disabled but Git projection changed")
         return failures
     policy = next(row for row in policies if row.source_mode == "project-mutation")
@@ -482,6 +505,29 @@ def _policy_violations(
     return failures
 
 
+def _stable_git_projection(snapshot: MutationSnapshot) -> dict[str, Any]:
+    """The projection minus the one field a read-only reader moves on its own.
+
+    `indexDigest` is Git's stat cache, and Git rewrites it whenever a plain
+    read refreshes a stale entry — `git status --short`, which the
+    `final-verification` profile requires of every verifier, is enough. Nothing
+    about the worktree's content changed when it moves, so comparing it made a
+    read-only worker fail for doing what its own phase told it to do (observed:
+    both stage-1 acceptance verifiers, where `indexDigest` was the only key that
+    differed and `stagedPaths` was empty on both sides).
+
+    Every field that does witness a mutation stays compared: `head` and
+    `branchCommit` for a moved ref, `stagedPaths` for content added to the
+    index, `worktreeRegistration` for a re-registered worktree, `reflogDigest`
+    for a ref rewrite, and both Git directories for a redirected repository.
+    """
+    return {
+        key: value
+        for key, value in snapshot.git_projection.items()
+        if key != "indexDigest"
+    }
+
+
 def _source_policy_failures(
     policy: WritePolicy,
     changed: set[str],

package/runtime/python/okstra_ctl/handoff.py

@@ -15,6 +15,11 @@ from typing import Any, Callable, Dict, List, Optional, Tuple
 from . import consumers, stage_targets, worktree_registry
 from .final_report_paths import final_report_markdown_path
 from .paths import RunRef
+from .release_gate import (
+    blocking_condition_ids,
+    release_handoff_allowed,
+    verdict_token,
+)
 from .stage_map import StageMapError, parse_stage_map_file, stage_map_records
 from .worktree import (compute_branch_name, compute_worktree_path,
                        main_worktree_path, is_dirty_excluding_okstra,
@@ -52,12 +57,14 @@ def compute_eligibility(stage_map: List[Dict[str, Any]],
     ).handoff_eligibility()
 
 
-def latest_whole_task_fv_accepted(project_root, project_id: str,
-                                  task_group: str, task_id: str) -> str:
-    """accepted whole-task final-verification 보고서 경로. 없으면 ''.
+def latest_whole_task_fv_release_ready(project_root, project_id: str,
+                                       task_group: str, task_id: str) -> str:
+    """release-handoff 로 넘어가도 되는 whole-task 검증 보고서 경로. 없으면 ''.
 
     판정의 SSOT 는 final-report 의 data.json 이다 (record_verified 와 동일
-    필드: header.taskType / verificationScope / finalVerdict.verdictToken).
+    필드: header.taskType / verificationScope / finalVerdict). 통과 조건은
+    `release_gate.release_handoff_allowed` 한 곳이 소유한다 — `accepted`,
+    또는 모든 조건이 릴리스를 막지 않는다고 선언한 `conditional-accept`.
     whole-task run 산출물만 평면 reports/ 에 남으므로 stage-* 는 걸리지 않는다."""
     from okstra_project.state import find_task_root
     root = find_task_root(Path(project_root),
@@ -71,11 +78,9 @@ def latest_whole_task_fv_accepted(project_root, project_id: str,
             data = json.loads(dj.read_text(encoding="utf-8"))
         except (OSError, json.JSONDecodeError):
             continue
-        token = ((data.get("finalVerdict") or {}).get("verdictToken")
-                 or "").strip().lower()
         if ((data.get("header") or {}).get("taskType") == "final-verification"
                 and data.get("verificationScope") == "whole-task"
-                and token == "accepted"):
+                and release_handoff_allowed(data)):
             md = final_report_markdown_path(dj)
             return str(md if md.is_file() else dj)
     return ""
@@ -363,8 +368,10 @@ def _impl_task_key_for_any(rows: List[Dict[str, Any]], stages: List[int]) -> str
 
 def record_verified(*, plan_run_root, stage: int, report_path: str,
                     data_json) -> Dict[str, Any]:
-    """단독-stage accepted 만 기록. data.json 의 taskType/scope/verdict 를 검증해
-    lead 가 임의 보고서를 verified 로 올리는 것을 막는다."""
+    """릴리스로 넘어갈 수 있는 단독-stage 판정만 기록. data.json 의
+    taskType/scope/verdict 를 검증해 lead 가 임의 보고서를 verified 로 올리는 것을
+    막는다. 통과 조건은 whole-task 와 같고(`release_gate`), 기록되는 verdict 는
+    보고서가 실제로 실은 토큰이다."""
     try:
         data = json.loads(Path(data_json).read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError) as exc:
@@ -376,14 +383,20 @@ def record_verified(*, plan_run_root, stage: int, report_path: str,
         raise HandoffError(
             f"record-verified requires verificationScope single-stage, "
             f"got {scope!r}")
-    token = ((data.get("finalVerdict") or {}).get("verdictToken")
-             or "").strip().lower()
-    if token != "accepted":
-        raise HandoffError(f"verdict token must be `accepted`, got {token!r}")
+    token = verdict_token(data)
+    if not release_handoff_allowed(data):
+        blocking = blocking_condition_ids(data)
+        detail = (
+            f"condition(s) {blocking} declare `blocksReleaseHandoff: true`"
+            if blocking else f"got {token!r}"
+        )
+        raise HandoffError(
+            "verdict must be `accepted`, or `conditional-accept` whose every "
+            f"condition declares `blocksReleaseHandoff: false` — {detail}")
     rows = consumers.read_consumers(Path(plan_run_root))
     key = _impl_task_key_for(rows, stage)
     consumers.append_verified(Path(plan_run_root), impl_task_key=key,
-                              stage=stage, verdict="accepted",
+                              stage=stage, verdict=token,
                               report_path=report_path)
     return {"ok": True, "stage": stage, "report_path": report_path}
 

package/runtime/python/okstra_ctl/model_cli.py

@@ -158,8 +158,17 @@ def _catalog_row(model, adapter, role: str | None) -> dict[str, Any]:
             )
         )
     except HostModelBindingError as exc:
-        row["selectable"] = False
-        row["reason"] = str(exc)
+        # Not "unusable as a lead": the host cannot bind this model to a native
+        # session, so the lead runs through the provider CLI instead. Reporting
+        # it as unselectable made the listing disagree with what assignment
+        # resolution actually does — it accepts the model and falls back to
+        # `cli-wrapper` — leaving no way to find out why a lead was not native.
+        row["leaderRunner"] = "cli-wrapper"
+        row["reason"] = (
+            f"native-session unavailable ({exc}); the lead runs via cli-wrapper"
+        )
+    else:
+        row["leaderRunner"] = "native-session"
     return row
 
 

package/runtime/python/okstra_ctl/model_discovery.py

@@ -51,6 +51,18 @@ def _dispatch_effort(execution: str, role: str) -> str:
     return effort
 
 
+def dispatch_tier_suffixes() -> frozenset[str]:
+    """Every tier suffix dispatch can append to an agy execution value.
+
+    The provider serves back the suffixed identity it was given, so reading
+    that identity means undoing exactly this set — not guessing at whatever
+    trails the last hyphen. `low` is here because `_dispatch_effort` demotes
+    the untrusted high tier to it.
+    """
+    efforts = {value.lower() for value in (*ROLE_EFFORT.values(), _DEFAULT_EFFORT)}
+    return frozenset(efforts | {"low"})
+
+
 @lru_cache(maxsize=1)
 def agy_models(agy_bin: str = "agy") -> tuple[str, ...]:
     """Live `agy models` ids, or () when agy is unavailable (non-blocking).