okstra 0.20.1 → 0.21.1

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
@@ -68,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.
@@ -187,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():
@@ -205,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(
@@ -215,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]:
@@ -261,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,
@@ -424,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(