okstra 0.84.0 → 0.86.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.84.0",
+  "version": "0.86.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.84.0",
-  "builtAt": "2026-06-15T18:39:25.947Z",
+  "package": "0.86.0",
+  "builtAt": "2026-06-15T19:57:16.546Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/codex-worker.md

@@ -30,7 +30,7 @@ You are a Codex worker agent. Your job is to execute the OpenAI Codex CLI and re
 $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" [<absolute-worktree-path>] [<role>]
 ```
 
-The fifth argument `<role>` is folded into both the caller (worker) pane title `codex-<role>-<pid>` and the sibling trace-pane title `codex-<role>-<pid>-tail` (`<pid>` = the wrapper's PID, present so concurrent dispatches of the same role can be told apart). Pass the value of the dispatch prompt's `**Pane role:**` line verbatim — Lead injects `**Pane role:** executor` on an `implementation` Executor dispatch and `**Pane role:** verifier` on an `implementation` / `final-verification` verifier dispatch, so the trace pane names the actual job (`codex-executor-<pid>` / `codex-verifier-<pid>`). When the prompt carries no `**Pane role:**` line (analysis phases), pass the literal `worker`. The wrapper defaults to `worker` when the argument is omitted, but pass it explicitly so the pane title is self-describing.
+The fifth argument `<role>` is folded into both the caller (worker) pane title `codex-<role>` and the sibling trace-pane title `codex-<role>-tail`. `<role>` carries the dispatched Agent `name` minus the `codex-` prefix, so the pane title equals the FleetView teammate name (`codex-worker-reverify-r1`, `codex-executor`, …) instead of a generic `worker`. Pass the value of the dispatch prompt's `**Pane role:**` line verbatim — Lead injects it on every CLI dispatch: `**Pane role:** worker-reverify-r1` on a convergence reverify, `**Pane role:** worker-critic` on a critic pass, `**Pane role:** executor` on an `implementation` Executor dispatch, `**Pane role:** verifier` on an `implementation` / `final-verification` verifier dispatch, and `**Pane role:** worker` on a plain analysis dispatch. The wrapper defaults to `worker` when the argument is omitted, but pass it explicitly so the pane title is self-describing.
 
 The fourth argument is **mandatory for implementation phase** and optional otherwise. It must be the literal `EXECUTOR_WORKTREE_PATH` recorded in the run context; the wrapper forwards it to codex as `--add-dir`, which grants the codex sandbox write access to the worktree (where all implementation-phase mutations occur). Without it, codex's `workspace-write` sandbox is anchored only at `<project-root>` and rejects every Edit/Write that targets the worktree (EPERM), which is the failure pattern that originally motivated this argument.
 

package/runtime/agents/workers/gemini-worker.md

@@ -30,7 +30,7 @@ You are a Gemini worker agent. Your job is to execute the Google Gemini CLI and
 $HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" [<absolute-worktree-path>] [<role>]
 ```
 
-The fifth argument `<role>` is folded into both the caller (worker) pane title `gemini-<role>-<pid>` and the sibling trace-pane title `gemini-<role>-<pid>-tail` (`<pid>` = the wrapper's PID, present so concurrent dispatches of the same role can be told apart). Pass the value of the dispatch prompt's `**Pane role:**` line verbatim — Lead injects `**Pane role:** executor` on an `implementation` Executor dispatch and `**Pane role:** verifier` on an `implementation` / `final-verification` verifier dispatch, so the trace pane names the actual job (`gemini-executor-<pid>` / `gemini-verifier-<pid>`). When the prompt carries no `**Pane role:**` line (analysis phases), pass the literal `worker`. The wrapper defaults to `worker` when the argument is omitted, but pass it explicitly so the pane title is self-describing.
+The fifth argument `<role>` is folded into both the caller (worker) pane title `gemini-<role>` and the sibling trace-pane title `gemini-<role>-tail`. `<role>` carries the dispatched Agent `name` minus the `gemini-` prefix, so the pane title equals the FleetView teammate name (`gemini-worker-reverify-r1`, `gemini-executor`, …) instead of a generic `worker`. Pass the value of the dispatch prompt's `**Pane role:**` line verbatim — Lead injects it on every CLI dispatch: `**Pane role:** worker-reverify-r1` on a convergence reverify, `**Pane role:** worker-critic` on a critic pass, `**Pane role:** executor` on an `implementation` Executor dispatch, `**Pane role:** verifier` on an `implementation` / `final-verification` verifier dispatch, and `**Pane role:** worker` on a plain analysis dispatch. The wrapper defaults to `worker` when the argument is omitted, but pass it explicitly so the pane title is self-describing.
 
 The fourth argument is **mandatory for implementation phase** and optional otherwise. It must be the literal `EXECUTOR_WORKTREE_PATH` recorded in the run context; the wrapper appends it to gemini's `--include-directories` list so the model can both read and operate on the worktree alongside project-root.
 

package/runtime/bin/okstra-claude-exec.sh

@@ -39,6 +39,25 @@ if ! command -v claude >/dev/null 2>&1; then
   exit 127
 fi
 
+# Grant tool access to the implementation worktree (and the main repo's shared
+# .git for linked-worktree commits) when one is supplied. The executor mutates
+# a git worktree that lives outside project-root; without --add-dir Claude
+# Code's Edit/Write tools cannot reach it. Mirrors okstra-codex-exec.sh.
+extra_args=()
+if [[ -n "$worktree_path" ]]; then
+  extra_args+=(--add-dir "$worktree_path")
+  if command -v git >/dev/null 2>&1; then
+    common_git_dir=$(git -C "$worktree_path" rev-parse --git-common-dir 2>/dev/null || true)
+    if [[ -n "$common_git_dir" ]]; then
+      [[ "$common_git_dir" != /* ]] && common_git_dir="$worktree_path/$common_git_dir"
+      if [[ -d "$common_git_dir" ]]; then
+        common_git_dir=$(cd "$common_git_dir" && pwd -P)
+        extra_args+=(--add-dir "$common_git_dir")
+      fi
+    fi
+  fi
+fi
+
 log_path="${prompt_path%.md}.log"
 [[ "$log_path" == "$prompt_path" ]] && log_path="${prompt_path}.log"
 : > "$log_path"
@@ -62,10 +81,50 @@ trap _okstra_status_finish EXIT
 
 cd "$project_root"
 set +e
-claude -p --model "$model" --output-format=stream-json < "$prompt_path" \
+claude -p --model "$model" ${extra_args[@]+"${extra_args[@]}"} --output-format=stream-json \
+  < "$prompt_path" \
   > >(tee -a "$log_path") \
-  2> >(tee -a "$log_path" >&2)
+  2> >(tee -a "$log_path" >&2) &
+claude_pid=$!
+
+# Idle watchdog: if the live log sees no write for $idle_timeout_secs, SIGTERM
+# claude (5s grace, then SIGKILL) and mark the status sidecar timed out, so a
+# silent hang is bounded instead of stalling the lead. Pass 0 to disable.
+watchdog_pid=""
+if (( idle_timeout_secs > 0 )); then
+  poll_interval=$(( idle_timeout_secs / 20 ))
+  (( poll_interval < 5 )) && poll_interval=5
+  (( poll_interval > 30 )) && poll_interval=30
+  (
+    while kill -0 "$claude_pid" 2>/dev/null; do
+      sleep "$poll_interval"
+      kill -0 "$claude_pid" 2>/dev/null || exit 0
+      last_mtime=$(stat -f %m "$log_path" 2>/dev/null || stat -c %Y "$log_path" 2>/dev/null || printf '0')
+      now=$(date +%s)
+      idle=$(( now - last_mtime ))
+      if (( idle >= idle_timeout_secs )); then
+        printf '\n[okstra wrapper] idle-watchdog: %ds without stdout — terminating claude (pid=%d)\n' \
+          "$idle" "$claude_pid" >> "$log_path" 2>&1 || true
+        python3 "$script_dir/okstra-wrapper-status.py" \
+          timeout "$status_path" "$now" "$idle" >>"$log_path" 2>&1 || true
+        kill -TERM "$claude_pid" 2>/dev/null || true
+        sleep 5
+        kill -KILL "$claude_pid" 2>/dev/null || true
+        exit 0
+      fi
+    done
+  ) &
+  watchdog_pid=$!
+fi
+
+wait "$claude_pid"
 claude_exit=$?
 set -e
 
+if [[ -n "$watchdog_pid" ]]; then
+  kill "$watchdog_pid" 2>/dev/null || true
+  wait "$watchdog_pid" 2>/dev/null || true
+fi
+wait 2>/dev/null || true
+
 exit "$claude_exit"

package/runtime/bin/okstra-codex-exec.sh

@@ -211,11 +211,12 @@ if type okstra_resolve_caller_pane >/dev/null 2>&1; then
   caller_pane="$(okstra_resolve_caller_pane)"
 fi
 
-# Pane titles: worker (caller) pane gets `codex-<role>-<pid>`; the sibling
-# trace pane is that same caller title with a `-tail` suffix, so the
-# operator can visually pair `<caller> ↔ <caller>-tail`. The wrapper PID in
-# the caller title disambiguates concurrent dispatches of the same role.
-pane_label="codex-${role}-$$"
+# Pane titles: the caller (worker) pane gets `codex-<role>`; the sibling trace
+# pane is that same caller title with a `-tail` suffix, so the operator can
+# visually pair `<caller> ↔ <caller>-tail`. `role` carries the dispatched Agent
+# name minus the `codex-` prefix (e.g. `worker-reverify-r1`, `executor`), so the
+# pane title equals the FleetView teammate name instead of a generic `worker`.
+pane_label="codex-${role}"
 trace_label="${pane_label}-tail"
 
 # Capture the caller pane's current title so the EXIT trap can restore it
@@ -251,13 +252,13 @@ fi
 # for the wrapper to exit. This fires in every phase the wrapper is invoked
 # from (analysis, error-analysis, implementation-planning, implementation,
 # …) — long-running codex dispatches are not implementation-specific. The
-# new pane carries the title `codex-<role>-<pid>-tail` so the operator can
-# pair it with its caller pane (`codex-<role>-<pid>`). The split is
+# new pane carries the title `codex-<role>-tail` so the operator can
+# pair it with its caller pane (`codex-<role>`). The split is
 # explicitly anchored to the caller pane (`-t "$caller_pane"`) to avoid
 # attaching to tmux's idle active pane. `role` is the optional 5th
 # positional arg (defaults to `worker`); callers that dispatch a different
-# role (e.g. `executor`) must pass it explicitly. The `<pid>` suffix is the
-# wrapper's PID and disambiguates concurrent dispatches of the same role.
+# role (e.g. `executor`, `worker-reverify-r1`) must pass it explicitly so the
+# pane title names the actual job.
 # The pane uses `tail -F` (follow-by-name) so it survives any truncation a
 # re-dispatch performs on the same log path. We gate on a resolved
 # `$caller_pane` (non-empty only when tmux is reachable) rather than the

package/runtime/bin/okstra-gemini-exec.sh

@@ -153,11 +153,12 @@ if type okstra_resolve_caller_pane >/dev/null 2>&1; then
   caller_pane="$(okstra_resolve_caller_pane)"
 fi
 
-# Pane titles: worker (caller) pane gets `gemini-<role>-<pid>`; the sibling
-# trace pane is that same caller title with a `-tail` suffix, so the
-# operator can visually pair `<caller> ↔ <caller>-tail`. The wrapper PID in
-# the caller title disambiguates concurrent dispatches of the same role.
-pane_label="gemini-${role}-$$"
+# Pane titles: the caller (worker) pane gets `gemini-<role>`; the sibling trace
+# pane is that same caller title with a `-tail` suffix, so the operator can
+# visually pair `<caller> ↔ <caller>-tail`. `role` carries the dispatched Agent
+# name minus the `gemini-` prefix (e.g. `worker-reverify-r1`, `executor`), so the
+# pane title equals the FleetView teammate name instead of a generic `worker`.
+pane_label="gemini-${role}"
 trace_label="${pane_label}-tail"
 
 # Capture the caller pane's current title so the EXIT trap can restore it
@@ -191,13 +192,13 @@ fi
 # When a tmux session is reachable, split a sibling pane tailing the log so
 # the operator can watch progress live. This fires in every phase the
 # wrapper is invoked from — long-running gemini dispatches are not
-# implementation-specific. Title `gemini-<role>-<pid>-tail` so the operator
-# can pair it with its caller pane (`gemini-<role>-<pid>`). The split is
+# implementation-specific. Title `gemini-<role>-tail` so the operator
+# can pair it with its caller pane (`gemini-<role>`). The split is
 # explicitly anchored to the caller pane to avoid attaching to tmux's idle
 # active pane. `role` is the optional 5th positional arg (defaults to
-# `worker`); callers that dispatch a different role must pass it explicitly.
-# The `<pid>` suffix is the wrapper's PID and disambiguates concurrent
-# dispatches of the same role. We gate on a resolved `$caller_pane`
+# `worker`); callers that dispatch a different role (e.g. `worker-reverify-r1`)
+# must pass it explicitly so the pane title names the actual job.
+# We gate on a resolved `$caller_pane`
 # (non-empty only when tmux is reachable) rather than the now-stripped
 # `$TMUX`. See the codex wrapper for the full design rationale and the
 # silent-degrade failure model.

package/runtime/prompts/{okstra-coding-preflight → coding-preflight}/scripts/preedit-check.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# PreToolUse hook for okstra-coding-preflight.
+# PreToolUse hook for coding-preflight.
 #
 # Inspects the target file path of a Write/Edit/MultiEdit/NotebookEdit
 # call. If the extension matches a language covered by this skill,
@@ -68,8 +68,8 @@ fi
 
 : > "$marker"
 
-skill_root="$HOME/.okstra/prompts/okstra-coding-preflight"
-msg="[okstra-coding-preflight] About to edit a ${lang} file (${file_path}). Before writing, you MUST Read ${skill_root}/${ref} plus ${skill_root}/clean-code.md (the skill is user-invocable:false — read the files directly).${extra_hint} If the project uses ports-and-adapters (domain/ + ports/ + adapters/, *.port.* files), also Read ${skill_root}/architecture/hexagonal.md. (Fires once per session per language.)"
+skill_root="$HOME/.okstra/prompts/coding-preflight"
+msg="[coding-preflight] About to edit a ${lang} file (${file_path}). Before writing, you MUST Read ${skill_root}/${ref} plus ${skill_root}/clean-code.md (the skill is user-invocable:false — read the files directly).${extra_hint} If the project uses ports-and-adapters (domain/ + ports/ + adapters/, *.port.* files), also Read ${skill_root}/architecture/hexagonal.md. (Fires once per session per language.)"
 
 jq -nc \
   --arg event "PreToolUse" \

package/runtime/prompts/lead/convergence.md

@@ -266,8 +266,9 @@ Agent(
 
 - Agent Teams mode: Spawn within an existing team
 - Fallback mode: Spawn with `run_in_background: true` and no `team_name`
+- CLI (Codex / Gemini) worker: inject `**Pane role:** worker-reverify-r<N>` (the Agent `name` minus the `<cli>-` prefix) into the reverify prompt body so the tmux trace pane reads `<cli>-worker-reverify-r<N>` per [okstra-lead-contract](./okstra-lead-contract.md) "Agent `name` on dispatch".
 
-For `tmux-pane` backend runs, do not use the Agent snippet. For each reverify round, write a jobs file at `runs/<task-type>/state/reverify-jobs-r<N>-<task-type>-<seq>.json` with `dispatchKind: "reverify-r<N>"` and worker entries containing `workerId`, `provider`, `role`, `modelExecutionValue`, `promptPath`, `resultPath`, `workerResultPath`, and `completionPaths`; then run `okstra team dispatch --project-root <dir> --run-manifest <path> --dispatch-kind reverify-r<N> --jobs-file <jobs-file>` followed by `okstra team await --project-root <dir> --run-manifest <path>`.
+For `tmux-pane` backend runs, do not use the Agent snippet. For each reverify round, write a jobs file at `runs/<task-type>/state/reverify-jobs-r<N>-<task-type>-<seq>.json` with `dispatchKind: "reverify-r<N>"` and worker entries containing `workerId`, `provider`, `role` (set to `worker-reverify-r<N>` for the pane title), `modelExecutionValue`, `promptPath`, `resultPath`, `workerResultPath`, and `completionPaths`; then run `okstra team dispatch --project-root <dir> --run-manifest <path> --dispatch-kind reverify-r<N> --jobs-file <jobs-file>` followed by `okstra team await --project-root <dir> --run-manifest <path>`.
 
 
 **Completion detection per round (BLOCKING).** Each round dispatches a variable set (1..N) of reverify workers asynchronously; the `Agent(... team_name ...)` calls return `Spawned successfully` immediately, which is NOT completion. Lead MUST detect each round's completion via the self-scheduled polling protocol in [team-contract](./team-contract.md) "Worker-completion detection (self-scheduled polling)", with the pending set reconstructed from that round's dispatched workers' Result Paths — do NOT restate the algorithm here. Lead MUST NOT treat the spawn ack as completion and MUST NOT end its turn with a prose "waiting" statement.
@@ -523,7 +524,7 @@ The critic input is the Round 0 consolidated finding list. Reverify rounds only
 - **Gap verification + merge**: only after BOTH the finding-convergence loop has exited AND the critic result is collected, and BEFORE the Phase 6 report-writer dispatch. If the loop exited `aborted-non-result`, do NOT dispatch a gap-verification round — surface the gaps as unverified `clarification` items per §"Gap verification" and record that fact.
 
 ### Dispatch (reused worker)
-Dispatch ONE pass to the `config.critic.provider`'s existing subagent (`claude-worker` / `codex-worker` / `gemini-worker`) with `model = config.critic.modelExecutionValue` — no new agent type. If `config.critic.modelExecutionValue` is null/empty (model could not be resolved), skip the critic pass and record `critic-skipped: model-unresolved` in the convergence state rather than dispatching with no model. Result path: `runs/<task-type>/worker-results/<provider>-critic-<task-type>-<seq>.md`. The critic prompt seeds the consolidated findings and asks ONLY for coverage gaps:
+Dispatch ONE pass to the `config.critic.provider`'s existing subagent (`claude-worker` / `codex-worker` / `gemini-worker`) with `model = config.critic.modelExecutionValue` — no new agent type, `name: "<provider>-worker-critic"`. If `config.critic.modelExecutionValue` is null/empty (model could not be resolved), skip the critic pass and record `critic-skipped: model-unresolved` in the convergence state rather than dispatching with no model. For a CLI (Codex / Gemini) critic dispatch, inject `**Pane role:** worker-critic` into the prompt body so the trace pane reads `<cli>-worker-critic` per [okstra-lead-contract](./okstra-lead-contract.md) "Agent `name` on dispatch". Result path: `runs/<task-type>/worker-results/<provider>-critic-<task-type>-<seq>.md`. The critic prompt seeds the consolidated findings and asks ONLY for coverage gaps:
 
 ```
 You are the coverage critic for <task-key>. Below are the consolidated findings

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -222,7 +222,7 @@ If the launch prompt contains `Tmux Worker Dispatch Gate`, Phase 3 is recorded a
 
 Spawn **analysis workers only** in the same turn (Phase 4 in Teams mode; Phase 5 with `run_in_background: true` and no `team_name` when Teams unavailable). Preserve exact roster, role labels, assigned models from the task bundle.
 
-**Agent `name` on dispatch (BLOCKING — token-usage attribution depends on it).** Every analysis-worker `Agent(...)` call MUST set `name: "<workerId>-worker"` — `name: "claude-worker"` / `name: "codex-worker"` / `name: "gemini-worker"` — exactly as the report-writer dispatch sets `name: "report-writer"` ([report-writer](./report-writer.md)). The Agent harness records this `name` as `agentName` in the subagent session jsonl, and the Phase 7 token collector matches each worker's session by that `agentName` (`okstra_token_usage/collect.py`). A worker dispatched **without** `name` produces a session with no `agentName`; the collector cannot attribute it and records the worker as `source: "unavailable"` even though the session exists and is team-tagged (observed in `dev-9692` error-analysis: `claude`/`codex` workers dispatched without `name` → both `unavailable`, while the named `report-writer` collected normally). Convergence reverify dispatches keep the prefix (`<workerId>-worker-reverify-r<N>`). For `implementation` and `final-verification` dispatches the `name` carries the **functional role** so the FleetView teammate pill and trace panes name the actual job instead of a generic `worker`: the Executor dispatch sets `name: "<workerId>-executor"` (e.g. `codex-executor`) and every verifier dispatch sets `name: "<workerId>-verifier"` (e.g. `claude-verifier`). These role suffixes still attribute correctly — the collector matches any `agentName` beginning `<workerId>-` (`okstra_token_usage/collect.py` `match_prefixes`). **For CLI (Codex / Gemini) executor/verifier dispatches, Lead MUST also inject a `**Pane role:** executor` (or `verifier`) line into the dispatched prompt body** — the wrapper subagent reads it and passes it as the wrapper's 5th `<role>` argument so the tmux trace pane title reads `<cli>-<role>-<pid>` instead of `<cli>-worker-<pid>` (see `agents/workers/_cli-wrapper-template.md`). Analysis-phase worker dispatches are unchanged: `name: "<workerId>-worker"`, no `**Pane role:**` line (the wrapper defaults to `worker`).
+**Agent `name` on dispatch (BLOCKING — token-usage attribution depends on it).** Every analysis-worker `Agent(...)` call MUST set `name: "<workerId>-worker"` — `name: "claude-worker"` / `name: "codex-worker"` / `name: "gemini-worker"` — exactly as the report-writer dispatch sets `name: "report-writer"` ([report-writer](./report-writer.md)). The Agent harness records this `name` as `agentName` in the subagent session jsonl, and the Phase 7 token collector matches each worker's session by that `agentName` (`okstra_token_usage/collect.py`). A worker dispatched **without** `name` produces a session with no `agentName`; the collector cannot attribute it and records the worker as `source: "unavailable"` even though the session exists and is team-tagged (observed in `dev-9692` error-analysis: `claude`/`codex` workers dispatched without `name` → both `unavailable`, while the named `report-writer` collected normally). Convergence reverify dispatches keep the prefix (`<workerId>-worker-reverify-r<N>`). For `implementation` and `final-verification` dispatches the `name` carries the **functional role** so the FleetView teammate pill and trace panes name the actual job instead of a generic `worker`: the Executor dispatch sets `name: "<workerId>-executor"` (e.g. `codex-executor`) and every verifier dispatch sets `name: "<workerId>-verifier"` (e.g. `claude-verifier`). These role suffixes still attribute correctly — the collector matches any `agentName` beginning `<workerId>-` (`okstra_token_usage/collect.py` `match_prefixes`). **For every CLI (Codex / Gemini) dispatch, Lead MUST inject a `**Pane role:**` line into the dispatched prompt body whose value is the Agent `name` with the leading `<cli>-` prefix removed** — the wrapper subagent reads it and passes it as the wrapper's 5th `<role>` argument so the tmux trace pane title reads `<cli>-<role>` (which equals the FleetView teammate name) instead of a generic `<cli>-worker` (see `agents/workers/_cli-wrapper-template.md`). So `name: "codex-worker"` → `**Pane role:** worker`, `name: "codex-worker-reverify-r1"` → `**Pane role:** worker-reverify-r1`, `name: "codex-executor"` → `**Pane role:** executor`, `name: "codex-verifier"` → `**Pane role:** verifier`. The wrapper defaults to `worker` when the line is absent, but always inject it so the pane names the actual job.
 
 **Agent `model:` on dispatch (BLOCKING — assignment is otherwise ignored).** The `Claude worker` `Agent(...)` call MUST set `model: "<family token of that role's modelExecutionValue>"` (`fable` / `opus` / `sonnet` / `haiku`), per [team-contract](./team-contract.md) "Model Assignment Rules" #3–#4. The claude-worker definition is `model: inherit`, so omitting this parameter makes the worker silently run on the lead's model instead of its manifest assignment — the assigned-vs-actual deviation. `Codex worker` / `Gemini worker` are exempt: their CLI model is applied via the wrapper's own `--model` argument, so leave their Agent `model:` at `inherit` (rule #5).
 

package/runtime/templates/reports/settings.template.json

@@ -34,7 +34,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash \"$HOME/.okstra/prompts/okstra-coding-preflight/scripts/preedit-check.sh\""
+            "command": "bash \"$HOME/.okstra/prompts/coding-preflight/scripts/preedit-check.sh\""
           }
         ]
       }

package/src/doctor.mjs

@@ -146,9 +146,14 @@ async function loadPhaseDiagnostics(phase, paths) {
     ")",
     "print(json.dumps(payload, ensure_ascii=False))",
   ].join("\n");
+  // `home` locates the agent install root (`<home>/.claude/agents`), which is
+  // the user home — NOT the okstra home (`paths.home` = ~/.okstra). Agents are
+  // installed under `homedir()/.claude/agents` (see install.mjs), so passing
+  // paths.home made every worker-agent phase check resolve to a path that
+  // never exists and report a false "missing agent".
   const result = await runPythonSnippet({
     script,
-    args: [phase, process.cwd(), paths.workspace, paths.home],
+    args: [phase, process.cwd(), paths.workspace, homedir()],
   });
   if (result.code !== 0 && !result.stdout.trim()) {
     return {