okstra 0.173.0 → 0.175.1

package/runtime/python/okstra_ctl/worker_audit_ledger.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import json
 import re
-from collections.abc import Mapping, Sequence
+from collections.abc import Mapping
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -45,25 +45,26 @@ _EVIDENCE_COMMAND_RE = re.compile(
     r"^- Evidence command:[ \t]*(?P<payload>.*)$", re.MULTILINE
 )
 _EVIDENCE_COMMAND_FIELDS = ("command", "cwd", "exitCode", "outputSummary")
-_EVIDENCE_COMMAND_STRING_FIELDS = ("command", "cwd", "outputSummary")
-_SENSITIVE_KEY_RE = re.compile(
-    r"(?i)(authorization|auth|credential|pass(?:wd|word)?|pwd|token|secret|"
-    r"api[_-]?key|access[_-]?key)"
-)
-_SENSITIVE_TEXT_RE = re.compile(
-    r"(?i)(authorization\s*:\s*\S+|"
-    r"\b(?:[A-Za-z_][A-Za-z0-9_-]*)?(?:auth|credential|pass(?:wd|word)?|pwd|"
-    r"token|secret|api[_-]?key|access[_-]?key)[A-Za-z0-9_-]*\s*=|"
-    r"--[\w-]*(?:auth|credential|pass(?:wd|word)?|pwd|token|secret|"
-    r"api[-_]?key|access[-_]?key)[\w-]*(?:[ =])\S+|"
-    r"\w+://[^\s:/@]+:[^\s@/]+@)"
-)
-_KNOWN_SECRET_RE = re.compile(
-    r"(?:AKIA|ASIA)[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9_]{8,}|"
-    r"github_pat_[A-Za-z0-9_]{8,}|xox[abprs]-[A-Za-z0-9-]{8,}|"
-    r"\bsk-[A-Za-z0-9_-]{8,}\b|"
-    r"\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b"
+_EVIDENCE_COMMAND_IDENTITY_FIELDS = (
+    "participantRef",
+    "roleExecutionRef",
+    "invocationRef",
+    "attempt",
+    "executionLabel",
 )
+_EVIDENCE_COMMAND_STRING_FIELDS = ("command", "cwd", "outputSummary")
+# There is deliberately no secret detector here.
+#
+# One lived on this path and only ever cost runs. It matched the *name* half of
+# an assignment, so `AUTH_MODE=off` and `TOKEN_TTL=60` were "sensitive material"
+# and the row was refused; a worker that cannot record the command it ran has no
+# way to satisfy the evidence ledger that demands it, and the run ends
+# `contract-violated` over a switch. Judging the value half instead only moves
+# the guesswork. What belongs in a row is the command's shape — the keys — and a
+# value that must not be written down is the worker's to leave out or pass as a
+# `$VAR` reference. A run does not need it: at execution time the value comes
+# from the environment or from the person running it, and if it is absent the
+# command fails then, where the failure is legible.
 _FILE_LINE_CITATION_RE = re.compile(
     r"`(?P<path>(?!https?://)[^`\n]+?):(?P<line>\d+(?:-\d+)?)`"
 )
@@ -116,34 +117,18 @@ class EvidenceCommand:
     cwd: str
     exit_code: int
     output_summary: str
+    identity: dict[str, object] | None = None
 
     def to_record(self) -> dict[str, object]:
-        return {
+        record: dict[str, object] = {
             "command": self.command,
             "cwd": self.cwd,
             "exitCode": self.exit_code,
             "outputSummary": self.output_summary,
         }
-
-
-def _contains_sensitive_material(value: object) -> bool:
-    if isinstance(value, Mapping):
-        return any(
-            (
-                _SENSITIVE_KEY_RE.search(str(key)) is not None
-                and nested not in (None, "", False)
-            )
-            or _contains_sensitive_material(nested)
-            for key, nested in value.items()
-        )
-    if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
-        return any(_contains_sensitive_material(item) for item in value)
-    if not isinstance(value, str):
-        return False
-    return (
-        _SENSITIVE_TEXT_RE.search(value) is not None
-        or _KNOWN_SECRET_RE.search(value) is not None
-    )
+        if self.identity:
+            record.update(self.identity)
+        return record
 
 
 def _evidence_command_contract_failures(
@@ -151,7 +136,9 @@ def _evidence_command_contract_failures(
 ) -> list[str]:
     failures: list[str] = []
     missing = [key for key in _EVIDENCE_COMMAND_FIELDS if key not in payload]
-    unexpected = sorted(set(payload) - set(_EVIDENCE_COMMAND_FIELDS))
+    unexpected = sorted(
+        set(payload) - set(_EVIDENCE_COMMAND_FIELDS) - set(_EVIDENCE_COMMAND_IDENTITY_FIELDS)
+    )
     if missing:
         failures.append(
             f"Evidence command row {row_number} is missing {', '.join(missing)}"
@@ -173,21 +160,15 @@ def _evidence_command_contract_failures(
     return failures
 
 
-def _evidence_command_from_payload(
-    payload: Mapping[str, object], sensitive: bool
-) -> EvidenceCommand:
-    if sensitive:
-        return EvidenceCommand(
-            command="[redacted: potential secret]",
-            cwd="[redacted: potential secret]",
-            exit_code=payload["exitCode"],
-            output_summary="omitted because potential secret material was detected",
-        )
+def _evidence_command_from_payload(payload: Mapping[str, object]) -> EvidenceCommand:
+    from okstra_ctl.execution_identity import stored_identity
+
     return EvidenceCommand(
         command=payload["command"],
         cwd=payload["cwd"],
         exit_code=payload["exitCode"],
         output_summary=payload["outputSummary"],
+        identity=stored_identity(payload) or None,
     )
 
 
@@ -209,16 +190,11 @@ def parse_evidence_commands(
                 f"Evidence command row {row_number} must be a JSON object"
             )
             continue
-        sensitive = _contains_sensitive_material(payload)
-        if sensitive:
-            failures.append(
-                f"Evidence command row {row_number} contains sensitive material"
-            )
         contract_failures = _evidence_command_contract_failures(payload, row_number)
         failures.extend(contract_failures)
         if contract_failures:
             continue
-        commands.append(_evidence_command_from_payload(payload, sensitive))
+        commands.append(_evidence_command_from_payload(payload))
     return tuple(commands), tuple(failures)
 
 
@@ -375,7 +351,26 @@ def check_worker_results_audit(
     *,
     worker: str | None = None,
 ) -> list[str]:
-    """Every audit-sidecar contract failure among this run's worker results.
+    """Every audit-sidecar contract finding among this run's worker results.
+
+    Blocking findings first, then the advisory citation-ledger ones. Mid-run
+    callers want both in one list: the worker session is still alive and can fix
+    either. Phase 7 separates them — see `worker_results_audit_findings`.
+    """
+    blocking, advisories = worker_results_audit_findings(
+        run_dir, task_type, seq, worker=worker
+    )
+    return blocking + advisories
+
+
+def worker_results_audit_findings(
+    run_dir: Path,
+    task_type: str,
+    seq: str | None,
+    *,
+    worker: str | None = None,
+) -> tuple[list[str], list[str]]:
+    """The same checks, split into `(blocking, advisory)`.
 
     *run_dir* is `runs/<task-type>/`; `worker-results/` and `prompts/` hang off
     it. *seq* scopes the check to one run — `worker-results/` accumulates every
@@ -383,16 +378,24 @@ def check_worker_results_audit(
     did not produce. Pass ``None`` only when the seq is genuinely unknown, which
     falls back to not filtering rather than silently checking nothing.
 
-    For each result file this checks that it carries no `## 0. Reading
-    Confirmation` heading (that block moved to the sidecar), that the matching
-    sidecar exists, and — for prompts carrying the required-v1 evidence-ledger
-    marker — that every backticked `path:line` citation has an Evidence read row.
+    Blocking: a result file that still carries the `## 0. Reading Confirmation`
+    heading (that block moved to the sidecar), a missing sidecar, and a
+    malformed Evidence command row. Each of those means the audit trail itself
+    is absent or unreadable.
+
+    Advisory: a `path:line` citation with no matching Evidence read row. The
+    ledger exists and is readable; what the check found is a citation whose
+    spelling does not match a row. That is worth reporting and not worth
+    voiding a finished run over — one unmatched citation among hundreds used to
+    take the whole phase to `contract-violated`, which stops the run without
+    telling anyone whether the finding itself was wrong.
     """
     failures: list[str] = []
+    advisories: list[str] = []
     if not (run_dir / "worker-results").is_dir():
         # No worker-results directory means no analysis workers ran (e.g.
         # `release-handoff`, which is single-lead). Nothing to enforce.
-        return failures
+        return failures, advisories
 
     for path, worker_role, result_seq in worker_result_files(run_dir, task_type, seq, worker):
         rel = path.name
@@ -426,7 +429,7 @@ def check_worker_results_audit(
 
         _, command_failures = read_evidence_commands(audit_path)
         failures.extend(command_failures)
-        failures.extend(_evidence_read_ledger_failures(
+        advisories.extend(_evidence_read_ledger_failures(
             run_dir=run_dir,
             worker_role=worker_role,
             task_type=task_type,
@@ -435,4 +438,4 @@ def check_worker_results_audit(
             result_content=content,
             audit_path=audit_path,
         ))
-    return failures
+    return failures, advisories

package/runtime/python/okstra_ctl/worker_request.py

@@ -14,6 +14,7 @@ from pathlib import Path
 
 from .domain.worker_exec import ExecutionPolicy, WorkerExecRequest
 from .domain.worker_role import role_spec
+from .write_policy import WriteEnforcement, WritePolicy
 
 # Carried over from the codex wrapper, where it was one provider's rule: cargo's
 # package-cache flock and its registry live outside every workspace, so a
@@ -35,6 +36,9 @@ def build_request(
     worktree_path: Path | None,
     role: str,
     idle_timeout_seconds: int,
+    session_id: str = "",
+    write_policy: WritePolicy | None = None,
+    write_enforcement: WriteEnforcement | None = None,
 ) -> WorkerExecRequest:
     """One dispatch, with every value the strategies will not re-derive.
 
@@ -52,9 +56,13 @@ def build_request(
         # Nobody is at the keyboard to answer an approval prompt, so the gate is
         # open and the boundary comes from the write scope instead.
         policy=ExecutionPolicy(
-            auto_approve=True, write_scope=write_scope(root, worktree, role)
+            auto_approve=True,
+            write_scope=write_scope(root, worktree, role),
+            write_policy=write_policy,
+            write_enforcement=write_enforcement,
         ),
         idle_timeout_seconds=idle_timeout_seconds,
+        session_id=session_id,
     )
 
 

package/runtime/python/okstra_ctl/worker_runner.py

@@ -21,7 +21,9 @@ from functools import partial
 from pathlib import Path
 from typing import Any, Callable, Mapping
 
+from .domain.provider import ServedModelAttestation, ServedModelNormalizer
 from .domain.worker_exec import (
+    SERVED_MODEL_MISMATCH_EXIT_CODE,
     STREAM_JSON,
     ExecCommand,
     ExecutionStrategy,
@@ -67,7 +69,11 @@ def run_worker(
     log_path: Path,
     status_path: Path,
     status_extra: Mapping[str, Any] = _NO_STATUS_EXTRA,
+    served_model_normalizer: ServedModelNormalizer | None = None,
+    served_model_verifier: Callable[[ServedModelAttestation], str] | None = None,
 ) -> int:
+    _validate_status_extra(status_extra)
+    _validate_request_write_contract(request, status_extra)
     command = strategy.build_command(request)
     started_monotonic = time.monotonic()
     status = _started_status(status_extra, log_path)
@@ -76,7 +82,7 @@ def run_worker(
 
     try:
         with guard:
-            exit_code, timed_out, idle_seconds = _launch(
+            exit_code, timed_out, idle_seconds, raw_model = _launch(
                 command,
                 log_path,
                 presentation=presentation,
@@ -94,6 +100,14 @@ def run_worker(
         raise
 
     status = _closed(status, started_monotonic)
+    if served_model_normalizer is not None:
+        attestation = served_model_normalizer(raw_model)
+        status["servedModelAttestation"] = _attestation_payload(attestation)
+        if served_model_verifier is not None:
+            failure = served_model_verifier(attestation)
+            if failure:
+                status["failure"] = failure
+                exit_code = SERVED_MODEL_MISMATCH_EXIT_CODE
     status["exit_code"] = exit_code
     if timed_out:
         status.update(
@@ -106,6 +120,57 @@ def run_worker(
     return exit_code
 
 
+def _validate_status_extra(status_extra: Mapping[str, Any]) -> None:
+    schema = status_extra.get("schemaVersion")
+    identity_version = status_extra.get("executionIdentityVersion")
+    identity_keys = {
+        "participantRef",
+        "roleExecutionRef",
+        "executionLabel",
+        "dutyId",
+        "invocationRef",
+    }
+    if schema is None and identity_version is None:
+        if set(status_extra) & (
+            identity_keys | {"attempt", "servedModelAttestation"}
+        ):
+            raise ValueError("worker status mixes v1 and v2 execution identity")
+        return
+    if schema != "2.0" or identity_version != 2:
+        raise ValueError("worker status mixes v1 and v2 execution identity")
+    if any(
+        not isinstance(status_extra.get(key), str) or not status_extra[key]
+        for key in identity_keys
+    ):
+        raise ValueError("worker status v2 execution identity is incomplete")
+    attempt = status_extra.get("attempt")
+    if not isinstance(attempt, int) or isinstance(attempt, bool) or attempt < 1:
+        raise ValueError("worker status v2 attempt must be positive")
+    attestation = status_extra.get("servedModelAttestation")
+    if not isinstance(attestation, Mapping) or set(attestation) != {
+        "observedModel",
+        "normalizedModelRef",
+        "level",
+        "source",
+    }:
+        raise ValueError("worker status served model attestation is invalid")
+
+
+def _validate_request_write_contract(
+    request: WorkerExecRequest, status_extra: Mapping[str, Any]
+) -> None:
+    if status_extra.get("executionIdentityVersion") != 2:
+        return
+    policy = request.policy.write_policy
+    enforcement = request.policy.write_enforcement
+    if policy is None or enforcement is None:
+        raise ValueError("v2 worker request has no write contract")
+    if status_extra.get("writePolicyDigest") != policy.digest:
+        raise ValueError("v2 worker request write policy digest changed")
+    if status_extra.get("writeEnforcement") != enforcement.to_payload():
+        raise ValueError("v2 worker request write enforcement changed")
+
+
 def _launch(
     command: ExecCommand,
     log_path: Path,
@@ -113,7 +178,7 @@ def _launch(
     presentation: str,
     idle_timeout_seconds: int,
     on_spawn: Callable[[subprocess.Popen[bytes]], None],
-) -> tuple[int, bool, int]:
+) -> tuple[int, bool, int, str | None]:
     log_path.parent.mkdir(parents=True, exist_ok=True)
     with log_path.open("w", encoding="utf-8") as log_file:
         # The strategy decided where this provider runs — some CLIs work in the
@@ -128,7 +193,8 @@ def _launch(
             env=_child_env(),
         )
         on_spawn(process)
-        return _pump(
+        observation = _ServedModelObservation()
+        exit_code, timed_out, idle_seconds = _pump(
             process,
             log_file,
             stream_format=command.stream_format,
@@ -136,7 +202,19 @@ def _launch(
             presentation=presentation,
             idle_timeout_seconds=idle_timeout_seconds,
             stdin_text=command.stdin_text,
+            observe_served_model=command.observe_served_model,
+            model_observation=observation,
         )
+        return exit_code, timed_out, idle_seconds, observation.raw_model
+
+
+class _ServedModelObservation:
+    def __init__(self) -> None:
+        self.raw_model: str | None = None
+
+    def record(self, raw_model: str | None) -> None:
+        if self.raw_model is None and isinstance(raw_model, str) and raw_model.strip():
+            self.raw_model = raw_model
 
 
 class _AbnormalExit:
@@ -253,6 +331,8 @@ def _pump(
     presentation: str,
     idle_timeout_seconds: int,
     stdin_text: str | None = None,
+    observe_served_model: Callable[[Mapping[str, Any]], str | None],
+    model_observation: _ServedModelObservation,
 ) -> tuple[int, bool, int]:
     selector = selectors.DefaultSelector()
     readers, finalize_log = _register_output(
@@ -261,6 +341,8 @@ def _pump(
         log_file,
         stream_format=stream_format,
         normalise=normalise,
+        observe_served_model=observe_served_model,
+        model_observation=model_observation,
         presentation=presentation,
     )
     outgoing = _register_prompt(selector, process, stdin_text)
@@ -357,6 +439,8 @@ def _register_output(
     *,
     stream_format: str,
     normalise: Normalise,
+    observe_served_model: Callable[[Mapping[str, Any]], str | None],
+    model_observation: _ServedModelObservation,
     presentation: str,
 ) -> tuple[dict[int, _LineReader], Callable[[], None]]:
     """Register every stream this child speaks, each with its own destination.
@@ -367,7 +451,17 @@ def _register_output(
     assert process.stdout is not None
     if stream_format == STREAM_JSON:
         sinks = [
-            (process.stdout, partial(_emit_event, log_file, presentation, normalise))
+            (
+                process.stdout,
+                partial(
+                    _emit_event,
+                    log_file,
+                    presentation,
+                    normalise,
+                    observe_served_model,
+                    model_observation,
+                ),
+            )
         ]
         finalize_log: Callable[[], None] = _nothing_to_finalize
     else:
@@ -519,7 +613,12 @@ class _ProgressSink:
 
 
 def _emit_event(
-    log_file, presentation: str, normalise: Normalise, line: str
+    log_file,
+    presentation: str,
+    normalise: Normalise,
+    observe_served_model: Callable[[Mapping[str, Any]], str | None],
+    model_observation: _ServedModelObservation,
+    line: str,
 ) -> str | None:
     """Write one line of a JSON stream out; return closing text if this is it.
 
@@ -542,6 +641,7 @@ def _emit_event(
         return None
     if not isinstance(event, dict):
         return None
+    model_observation.record(observe_served_model(event))
 
     closing: str | None = None
     for entry in normalise(event):
@@ -560,6 +660,15 @@ def _emit_event(
     return closing
 
 
+def _attestation_payload(attestation: ServedModelAttestation) -> dict[str, Any]:
+    return {
+        "observedModel": attestation.observed_model,
+        "normalizedModelRef": attestation.normalized_model_ref,
+        "level": attestation.level,
+        "source": attestation.source,
+    }
+
+
 def _write_log(log_file, lines) -> None:
     for line in lines:
         log_file.write(line + "\n")
@@ -605,6 +714,22 @@ def _child_env() -> dict[str, str]:
     return env
 
 
+def write_host_event(
+    path: Path,
+    *,
+    invocation_ref: str,
+    attempt: int,
+    event_type: str,
+    payload: Mapping[str, Any],
+) -> Mapping[str, Any]:
+    """Append one orchestrator-owned host event from the runner boundary."""
+    from .attempt_evidence import HostEventStreamWriter
+
+    return HostEventStreamWriter(
+        path, invocation_ref=invocation_ref, attempt=attempt
+    ).append(event_type, payload)
+
+
 def _write_status(path: Path, status: Mapping[str, Any]) -> None:
     """Best-effort status write; a sidecar failure must not break the run.
 

package/runtime/python/okstra_ctl/workers.py

@@ -1,4 +1,4 @@
-"""Worker roster resolution.
+"""V1 provider-worker roster compatibility parsing.
 
 Profile 파일에서 권장 worker 목록을 뽑고(`resolve_profile_workers`), 사용자
 오버라이드와 합쳐 정규화한다(`normalize_workers`). bash workers.sh 의
@@ -28,8 +28,10 @@ class WorkersError(Exception):
     """invalid worker selection — surface to user."""
 
 
-def _resolve_workers_under(profile_path: Path, headers: set[str]) -> list[str]:
-    """Generic parser: collect `  - <id> …` sub-bullets under any of `headers`
+def _resolve_v1_workers_under(profile_path: Path, headers: set[str]) -> list[str]:
+    """Read legacy provider-worker bullets without interpreting role YAML.
+
+    Collect `  - <id> …` sub-bullets under any of `headers`
     until the next top-level bullet. Returns first token (before any
     ` — ` / ` -- ` / whitespace) of each captured line.
     """
@@ -61,7 +63,7 @@ def resolve_profile_workers(profile_path: Path) -> list[str]:
     `- Workers:` / `- Reviewers:` / `- Analysers:`) 섹션 아래 sub-bullet 들을
     worker id 리스트로 돌려준다. profile 파일이 없거나 섹션이 없으면 빈 리스트.
     """
-    return _resolve_workers_under(profile_path, PROFILE_BULLET_HEADERS)
+    return _resolve_v1_workers_under(profile_path, PROFILE_BULLET_HEADERS)
 
 
 def resolve_optional_workers(profile_path: Path) -> list[str]:
@@ -69,7 +71,7 @@ def resolve_optional_workers(profile_path: Path) -> list[str]:
     들에서 worker id 만 추출한다. (`  - antigravity — when added …` → `antigravity`)
     Required 와 중복되는 항목은 제거. ALLOWED_WORKERS 밖 토큰도 제거.
     """
-    raw = _resolve_workers_under(profile_path, PROFILE_BULLET_HEADERS_OPTIONAL)
+    raw = _resolve_v1_workers_under(profile_path, PROFILE_BULLET_HEADERS_OPTIONAL)
     required = set(resolve_profile_workers(profile_path))
     seen: set[str] = set()
     out: list[str] = []

package/runtime/python/okstra_ctl/worktree.py

@@ -77,6 +77,27 @@ DEFAULT_WORKTREE_SYNC_DIRS: tuple[str, ...] = (
 )
 
 
+# Sync dirs materialised as a REAL directory whose children are symlinked one
+# by one, instead of a single symlink standing in for the whole directory.
+#
+# Why the split exists: git does not follow a symlink, so a symlinked directory
+# is one *file* to it. A project that ignores host config by its contents
+# (`.claude/*`) matches every child but never the bare `.claude` path, so the
+# symlink lands in `git status` as
+# `?? .claude` while the same directory is invisible in the main checkout. Any
+# plan step asserting a clean worktree then fails on okstra's own provisioning.
+# Linking the children instead reproduces the main checkout's shape, so
+# whatever the project's ignore rules do there, they do here too.
+#
+# Only `.claude` qualifies. The other sync dirs are shared okstra state that
+# okstra WRITES into, and a directory symlink is what makes a newly created
+# top-level entry land in the main checkout rather than diverging inside the
+# worktree. `.claude` is host configuration okstra reads; its one okstra write
+# is the fixed `settings.local.json` child seeded by
+# `_seed_worktree_settings_symlink`.
+CHILD_LINKED_SYNC_DIRS: tuple[str, ...] = (".claude",)
+
+
 # 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
@@ -522,16 +543,27 @@ def is_ancestor(cwd, commit: str, head: str) -> bool:
     return _git(Path(cwd), "merge-base", "--is-ancestor", commit, head).returncode == 0
 
 
-def is_dirty_excluding_okstra(cwd) -> bool:
-    """True iff the worktree has changes outside okstra-owned paths.
+def dirty_entries_excluding_okstra(cwd) -> list[str]:
+    """`git status --short` rows for changes outside okstra-owned paths.
 
     okstra-owned = `okstra_clean_gate_excludes` (e.g. `.okstra`, synced dirs)
     plus `nested_worktree_excludes` (stage worktrees nested under `cwd`).
+
+    This is the clean-worktree question every okstra gate asks, and the one a
+    plan step must ask through `okstra worktree-status` rather than through a
+    bare `git status --porcelain`: okstra provisions `.okstra` plus the synced
+    entries into every task worktree, so a bare status is never empty there and
+    an assertion built on it fails on okstra's own scaffolding.
     """
     owned = (*okstra_clean_gate_excludes(Path(cwd)), *nested_worktree_excludes(cwd))
     excludes = [f":(exclude){p}" for p in owned]
     out = _git(Path(cwd), "status", "--short", "--", ".", *excludes).stdout
-    return bool(out.strip())
+    return [line for line in out.splitlines() if line.strip()]
+
+
+def is_dirty_excluding_okstra(cwd) -> bool:
+    """True iff the worktree has changes outside okstra-owned paths."""
+    return bool(dirty_entries_excluding_okstra(cwd))
 
 
 class MergeError(RuntimeError):
@@ -580,6 +612,9 @@ def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
         version-controlled files.
       - Parent directories are created as needed for nested entries.
 
+    Entries listed in `CHILD_LINKED_SYNC_DIRS` are materialised as a real
+    directory of per-child symlinks instead (see that constant).
+
     Returns a list of human-readable notes (one per linked entry) so the
     caller can include them in the provisioning note.
     """
@@ -592,6 +627,10 @@ def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
         if dst.exists() or dst.is_symlink():
             continue
         dst.parent.mkdir(parents=True, exist_ok=True)
+        if rel in CHILD_LINKED_SYNC_DIRS and src.is_dir():
+            _link_dir_children(src, dst)
+            notes.append(rel)
+            continue
         try:
             os.symlink(src, dst)
         except FileExistsError:
@@ -600,6 +639,33 @@ def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
     return notes
 
 
+def _link_dir_children(src: Path, dst: Path) -> None:
+    """Create `dst` as a real directory whose entries symlink to `src`'s
+    children, so git sees the same directory shape it sees in the main
+    checkout (`CHILD_LINKED_SYNC_DIRS`).
+
+    Each link points at the MAIN checkout's child rather than its resolved
+    target, so a child that is itself a symlink (e.g. `.claude/settings.local.json`
+    → `~/.okstra/templates/settings.local.json`) keeps following whatever the
+    main checkout currently points at. An unreadable source or a child that
+    cannot be linked degrades to "that child is absent in this worktree" —
+    provisioning is not worth failing over host config.
+    """
+    dst.mkdir(parents=True, exist_ok=True)
+    try:
+        children = sorted(src.iterdir())
+    except OSError:
+        return
+    for child in children:
+        link = dst / child.name
+        if link.exists() or link.is_symlink():
+            continue
+        try:
+            os.symlink(child, link)
+        except OSError:
+            continue
+
+
 def _link_sync_files(source_root: Path, worktree_path: Path) -> list[str]:
     """File-level counterpart to `_link_sync_dirs` (FU-V2).