okstra 0.20.0 → 0.21.0

package/runtime/python/okstra_ctl/workflow.py

@@ -124,23 +124,24 @@ PHASE_RULES: dict[str, dict[str, str]] = {
     },
     "release-handoff": {
         "allowed": (
-            "  - entering this phase only when the cited final-verification report's verdict is exactly `accepted`\n"
-            "  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `commit only`, `commit + PR`, or `skip` (end the run)\n"
+            "  - entering this phase only when the cited final-verification report's `Verdict Token` is exactly `accepted`\n"
+            "  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `local only`, `push + PR`, or `skip` (end the run)\n"
             "  - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n"
-            "  - drafting commit message(s) and PR body **inline as the Claude lead** (no drafter worker, no `Agent` dispatch); the lead reviews its own draft with the user before any git command runs\n"
-            "  - local git operations: `git status`, `git diff`, `git log`, `git add`, `git commit -m`\n"
+            "  - drafting PR title and PR body **inline as the Claude lead** (no drafter worker, no `Agent` dispatch); the lead reviews its own draft with the user before any mutating git / gh command runs\n"
+            "  - read-only git inspection: `git status`, `git diff`, `git log`, `git rev-parse`\n"
             "  - pushing the current feature branch to its origin remote via `git push -u origin <current-branch>` (the feature branch only — NEVER the base branch)\n"
             "  - creating a pull request via `gh pr create --base <chosen-base> --head <current-branch>`; if a PR with the same head already exists, surface its URL and skip creation\n"
             "  - the lead writes the final report directly (no `Report writer worker` dispatch); the report still conforms to the standard final-report template"
         ),
         "forbidden": (
-            "  - entering this phase when the cited final-verification verdict is `conditional-accept` or `blocked`, or when no final-verification report is cited\n"
-            "  - any source-code edit, refactor, or scope expansion beyond what is strictly needed to author commit messages / PR descriptions (the changes themselves are inherited from prior `implementation` runs)\n"
+            "  - entering this phase when the cited final-verification `Verdict Token` is `conditional-accept` or `blocked`, or when no final-verification report is cited\n"
+            "  - any source-code edit, refactor, or scope expansion beyond what is strictly needed to author PR descriptions (the changes themselves are inherited from prior `implementation` runs)\n"
+            "  - local commit commands (`git add`, `git commit`, `git stash`, `git restore --staged`); commits are produced by `implementation`, not release-handoff\n"
             "  - `git push --force`, `git push --force-with-lease`, or any rewriting of remote history\n"
             "  - pushing directly to a base branch (`main`, `master`, `prod`, `preprod`, `staging`, `dev`, or any branch the user named as the PR base)\n"
             "  - bypassing git hooks (`--no-verify`, `-n`), bypassing GPG signing, or otherwise disabling repo-configured safeguards\n"
             "  - release-publishing commands: `gh release`, `npm publish`, `cargo publish`, `pip publish`, `docker push`, `terraform apply`, `kubectl apply` against non-local clusters\n"
-            "  - executing any command the user did NOT select (e.g. if the user picked `commit only`, opening a PR is forbidden; if the user picked `skip`, the run ends without git commands)\n"
+            "  - executing any command the user did NOT select (e.g. if the user picked `local only`, opening a PR is forbidden; if the user picked `skip`, the run ends without git commands)\n"
             "  - `TeamCreate`, `Agent(...)` worker dispatch, parallel sub-agent fan-out, or any team-mode orchestration — this phase runs single-lead\n"
             "  - silently retrying a failed git/gh command with weaker flags (e.g. retrying `git push` with `--force` after a non-fast-forward rejection)"
         ),

package/runtime/python/okstra_ctl/worktree.py

@@ -34,6 +34,8 @@ from __future__ import annotations
 
 import json
 import os
+import shutil
+import stat
 import subprocess
 from dataclasses import dataclass
 from pathlib import Path
@@ -43,9 +45,6 @@ from .ids import _safe_fs_segment
 from . import worktree_registry
 
 
-OKSTRA_WORKTREES_RELATIVE = Path(".okstra/worktrees")
-
-
 # Project-root directories that hold okstra task state, ignored by git, or
 # otherwise required for the executor to operate but NOT carried across by
 # `git worktree add`. Each is symlinked from the MAIN worktree into the new
@@ -71,6 +70,35 @@ DEFAULT_WORKTREE_SYNC_DIRS: tuple[str, ...] = (
 )
 
 
+# Project-root-relative FILES (not dirs) symlinked from MAIN → task worktree
+# at provision time. Same symlink semantics as `DEFAULT_WORKTREE_SYNC_DIRS`:
+# every task sees the live shared file. The split exists because the original
+# `_link_sync_dirs` helper only walked directories — a `.env` (or any
+# top-level file outside `.git`'s tracking) would otherwise be lost on every
+# new worktree, blocking verifier dispatches that depend on environment-
+# resolved secrets.
+#
+# Override precedence mirrors `DEFAULT_WORKTREE_SYNC_DIRS`:
+#   1. `OKSTRA_WORKTREE_SYNC_FILES` env var (colon-separated, REPLACES).
+#   2. `worktreeSyncFiles` array in `.project-docs/okstra/project.json`.
+#   3. The built-in `DEFAULT_WORKTREE_SYNC_FILES` below.
+DEFAULT_WORKTREE_SYNC_FILES: tuple[str, ...] = (
+    ".env",
+)
+
+
+# Project-root-relative files COPIED (not symlinked) from MAIN → task worktree
+# at provision time, then `chmod 0o444` so the task cannot mutate the
+# snapshot. Used for live-mutating fixtures (e.g. `classifications.db`)
+# where the verifier needs to reproduce accuracy SQL against the same rows
+# the executor saw, without sharing the writable handle that would corrupt
+# the main worktree's copy. Default is empty — okstra has no opinion about
+# which fixtures any given project relies on; opt in per-project via
+# `worktreeSnapshotFiles` in `project.json` (or `OKSTRA_WORKTREE_SNAPSHOT_FILES`
+# for one-off operator override).
+DEFAULT_WORKTREE_SNAPSHOT_FILES: tuple[str, ...] = ()
+
+
 # Work-category → short branch prefix. Mirrors the values accepted by
 # `--work-category` (bugfix / feature / refactor / ops / improvement) and
 # falls back to `task` when the category is unset or unrecognised.
@@ -190,14 +218,14 @@ def _main_worktree_path(project_root: Path) -> Path:
     return project_root
 
 
-def _read_project_json_sync_dirs(project_root: Path) -> Optional[tuple[str, ...]]:
-    """Read `worktreeSyncDirs` from `.project-docs/okstra/project.json`.
+def _read_project_json_field(project_root: Path, field: str) -> Optional[tuple[str, ...]]:
+    """Read a string-array field from `.project-docs/okstra/project.json`.
 
     Returns None if the field is absent or the file cannot be parsed (so
     the caller falls back to defaults). Returns an empty tuple if the
     field is explicitly an empty array (caller treats this as "disable").
     A non-list value is treated as missing — we do not raise here because
-    sync-dir resolution must never block worktree provisioning.
+    field resolution must never block worktree provisioning.
     """
     target = project_root / ".project-docs" / "okstra" / "project.json"
     if not target.is_file():
@@ -208,7 +236,7 @@ def _read_project_json_sync_dirs(project_root: Path) -> Optional[tuple[str, ...]
         return None
     if not isinstance(data, dict):
         return None
-    value = data.get("worktreeSyncDirs")
+    value = data.get(field)
     if not isinstance(value, list):
         return None
     cleaned = tuple(
@@ -218,22 +246,68 @@ def _read_project_json_sync_dirs(project_root: Path) -> Optional[tuple[str, ...]
     return cleaned
 
 
-def _resolve_sync_dirs(project_root: Optional[Path] = None) -> tuple[str, ...]:
-    """Return the list of project-root-relative dirs to symlink into the
-    new worktree. Precedence: env var → project.json → built-in default.
-    See the comment above `DEFAULT_WORKTREE_SYNC_DIRS` for full semantics.
+def _read_project_json_sync_dirs(project_root: Path) -> Optional[tuple[str, ...]]:
+    """Back-compat shim — preserves the old name used by external callers."""
+    return _read_project_json_field(project_root, "worktreeSyncDirs")
+
+
+def _resolve_entries(
+    *,
+    env_var: str,
+    project_field: str,
+    default: tuple[str, ...],
+    project_root: Optional[Path],
+) -> tuple[str, ...]:
+    """Generic resolver shared by sync-dirs / sync-files / snapshot-files.
+
+    Precedence: env var (colon-separated, REPLACES) → project.json field →
+    built-in default. An empty env value or empty JSON array disables the
+    feature (returns `()`).
     """
-    raw = os.environ.get("OKSTRA_WORKTREE_SYNC_DIRS")
+    raw = os.environ.get(env_var)
     if raw is not None:
         raw = raw.strip()
         if not raw:
             return ()
         return tuple(part for part in (p.strip() for p in raw.split(":")) if part)
     if project_root is not None:
-        from_project = _read_project_json_sync_dirs(project_root)
+        from_project = _read_project_json_field(project_root, project_field)
         if from_project is not None:
             return from_project
-    return DEFAULT_WORKTREE_SYNC_DIRS
+    return default
+
+
+def _resolve_sync_dirs(project_root: Optional[Path] = None) -> tuple[str, ...]:
+    """Return the list of project-root-relative dirs to symlink into the
+    new worktree. Precedence: env var → project.json → built-in default.
+    See the comment above `DEFAULT_WORKTREE_SYNC_DIRS` for full semantics.
+    """
+    return _resolve_entries(
+        env_var="OKSTRA_WORKTREE_SYNC_DIRS",
+        project_field="worktreeSyncDirs",
+        default=DEFAULT_WORKTREE_SYNC_DIRS,
+        project_root=project_root,
+    )
+
+
+def _resolve_sync_files(project_root: Optional[Path] = None) -> tuple[str, ...]:
+    """File-level counterpart to `_resolve_sync_dirs` (FU-V2)."""
+    return _resolve_entries(
+        env_var="OKSTRA_WORKTREE_SYNC_FILES",
+        project_field="worktreeSyncFiles",
+        default=DEFAULT_WORKTREE_SYNC_FILES,
+        project_root=project_root,
+    )
+
+
+def _resolve_snapshot_files(project_root: Optional[Path] = None) -> tuple[str, ...]:
+    """Read-only snapshot file list (FU-V3)."""
+    return _resolve_entries(
+        env_var="OKSTRA_WORKTREE_SNAPSHOT_FILES",
+        project_field="worktreeSnapshotFiles",
+        default=DEFAULT_WORKTREE_SNAPSHOT_FILES,
+        project_root=project_root,
+    )
 
 
 def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
@@ -264,6 +338,63 @@ def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
     return notes
 
 
+def _link_sync_files(source_root: Path, worktree_path: Path) -> list[str]:
+    """File-level counterpart to `_link_sync_dirs` (FU-V2).
+
+    Same skip rules: missing source → skipped silently; pre-existing dst
+    (tracked content checked out by `git worktree add`) → skipped to avoid
+    clobbering. Symlinks (not copies) keep secrets out of duplicate files —
+    the link points back to the MAIN worktree's `.env` so rotating the file
+    there is reflected in every active task without re-provisioning.
+    """
+    notes: list[str] = []
+    for rel in _resolve_sync_files(source_root):
+        src = (source_root / rel).resolve()
+        if not src.exists() or not src.is_file():
+            continue
+        dst = worktree_path / rel
+        if dst.exists() or dst.is_symlink():
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        os.symlink(src, dst)
+        notes.append(rel)
+    return notes
+
+
+def _copy_snapshot_files(source_root: Path, worktree_path: Path) -> list[str]:
+    """Copy fixture files from MAIN → task worktree as read-only snapshots
+    (FU-V3).
+
+    Unlike `_link_sync_files`, this materialises a fresh on-disk copy and
+    chmods it to `0o444` so the verifier can read the same rows the
+    executor saw without sharing a writable handle that would corrupt the
+    main worktree's copy. Skip rules mirror the symlink helpers (missing
+    source → skipped silently; pre-existing dst → skipped to avoid
+    clobbering tracked content).
+    """
+    notes: list[str] = []
+    for rel in _resolve_snapshot_files(source_root):
+        src = (source_root / rel).resolve()
+        if not src.exists() or not src.is_file():
+            continue
+        dst = worktree_path / rel
+        if dst.exists() or dst.is_symlink():
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dst)
+        try:
+            os.chmod(dst, stat.S_IRUSR | stat.S_IRGRP | stat.S_IROTH)
+        except OSError:
+            # chmod failure (exotic filesystems, root-squashed mounts) does
+            # not invalidate the snapshot itself — it just means the read-
+            # only contract is best-effort. Surface in notes so the operator
+            # can audit if a verifier later mutates the file.
+            notes.append(f"{rel} (rw-fallback)")
+            continue
+        notes.append(rel)
+    return notes
+
+
 def compute_worktree_path(
     *,
     project_id: str,
@@ -427,7 +558,16 @@ def provision_task_worktree(
     # Sync dirs sourced from the MAIN worktree so every task sees the
     # same shared state regardless of which checkout invoked okstra.
     linked = _link_sync_dirs(main_root, worktree_path)
-    linked_suffix = f"; linked {', '.join(linked)}" if linked else ""
+    linked_files = _link_sync_files(main_root, worktree_path)
+    snapshot_files = _copy_snapshot_files(main_root, worktree_path)
+    linked_parts: list[str] = []
+    if linked:
+        linked_parts.append(f"linked {', '.join(linked)}")
+    if linked_files:
+        linked_parts.append(f"linked-files {', '.join(linked_files)}")
+    if snapshot_files:
+        linked_parts.append(f"snapshot {', '.join(snapshot_files)}")
+    linked_suffix = ("; " + "; ".join(linked_parts)) if linked_parts else ""
 
     try:
         worktree_registry.reserve(

package/runtime/python/okstra_token_usage/blocks.py

@@ -5,8 +5,6 @@ from .paths import utc_now
 from .pricing import (
     claude_billable_equivalent,
     claude_cost_usd,
-    codex_cost_usd,
-    gemini_cost_usd,
 )
 
 

package/runtime/python/okstra_token_usage/claude.py

@@ -15,8 +15,6 @@ def claude_session_totals(jsonl_path: Path) -> dict:
     model: str | None = None
     first_ts: str | None = None
     last_ts: str | None = None
-    started_at: str | None = None
-    ended_at: str | None = None
     for rec in iter_jsonl(jsonl_path):
         if agent_name is None and rec.get("agentName"):
             agent_name = rec["agentName"]