okstra 0.83.0 → 0.85.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.83.0",
+  "version": "0.85.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.83.0",
-  "builtAt": "2026-06-15T16:01:38.767Z",
+  "package": "0.85.0",
+  "builtAt": "2026-06-15T19:37:36.878Z",
   "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/coding-preflight/scripts/preedit-check.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# 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,
+# emits a `hookSpecificOutput.additionalContext` JSON payload that
+# reminds the agent to invoke the skill before writing.
+#
+# Fires at most once per session per language (marker file).
+# Exits 0 in every case — never blocks the tool call.
+
+set -euo pipefail
+
+input="$(cat)"
+
+tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')"
+case "$tool_name" in
+  Write|Edit|MultiEdit|NotebookEdit) ;;
+  *) exit 0 ;;
+esac
+
+file_path="$(printf '%s' "$input" \
+  | jq -r '.tool_input.file_path // .tool_input.notebook_path // empty')"
+[[ -z "$file_path" ]] && exit 0
+
+lang=""
+ref=""
+extra_hint=""
+case "$file_path" in
+  *.java)
+    lang="Java"
+    ref="languages/java.md"
+    ;;
+  *.kt|*.kts)
+    lang="Kotlin"
+    ref="languages/kotlin.md"
+    ;;
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs)
+    lang="JavaScript-TypeScript"
+    ref="languages/javascript-typescript.md"
+    extra_hint=" If this file is part of a Node.js server (Express/Fastify/Nest/etc.), also read languages/nodejs.md."
+    ;;
+  *.py)
+    lang="Python"
+    ref="languages/python.md"
+    ;;
+  *.sql)
+    lang="SQL"
+    ref="languages/sql.md"
+    ;;
+  *.rs)
+    lang="Rust"
+    ref="languages/rust.md"
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+session_id="$(printf '%s' "$input" | jq -r '.session_id // "no-session"')"
+marker_dir="${TMPDIR:-/tmp}/mcbsc"
+mkdir -p "$marker_dir"
+marker="${marker_dir}/${session_id}_${lang}"
+
+if [[ -f "$marker" ]]; then
+  exit 0
+fi
+
+: > "$marker"
+
+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" \
+  --arg ctx "$msg" \
+  '{hookSpecificOutput: {hookEventName: $event, additionalContext: $ctx}}'
+
+exit 0

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/python/okstra_ctl/run.py

@@ -79,6 +79,7 @@ from .session import (
 from .pr_template import PrTemplateError, resolve_pr_template_path
 from .workers import (
     normalize_workers,
+    resolve_optional_workers,
     resolve_profile_workers,
     validate_workers_against_profile,
 )
@@ -1402,10 +1403,11 @@ def _resolve_roster(inp: PrepareInputs, profile_file: Path) -> tuple[list[str],
     if inp.task_type == "release-handoff":
         return [], ""
     profile_workers = resolve_profile_workers(profile_file)
+    optional_workers = resolve_optional_workers(profile_file)
     profile_workers_csv = ",".join(profile_workers)
     workers = normalize_workers(inp.workers_override or profile_workers_csv)
     if inp.workers_override.strip():
-        validate_workers_against_profile(workers, profile_workers)
+        validate_workers_against_profile(workers, profile_workers, optional_workers)
     if not workers:
         raise PrepareError(f"no workers resolved for profile: {inp.task_type}")
     return workers, ",".join(workers)

package/runtime/skills/okstra-brief/SKILL.md

@@ -145,7 +145,7 @@ If the user picked `Reporter input`, proceed to Step 1.A's sub-flow below — th
 - **Label**: "Source of this brief?"
 - **Options** (single-select):
   1. `File` — path to an existing markdown / txt / issue-export file
-  2. `Issue tracker ticket` — Linear / Jira / GitHub Issue / Notion key or URL
+  2. `Issue tracker ticket` — Linear URL/ Jira URL/ GitHub Issue URL/ Notion key or URL
   3. `Link URL` — general web page, blog, spec doc, design doc, etc.
   4. `User input` — synthesize from the current conversation context, or
      accept a short free-text from the user
@@ -678,7 +678,7 @@ Use the same template per brief file. In tracker mode producing a parent
 plus N children, you write **N+1 files** (each carries only its own Source
 Material).
 
-[`templates/reports/brief.template.md`](../../templates/reports/brief.template.md) is the byte-for-byte SSOT for the brief shape — frontmatter keys, top-header blockquote, section ordering, and inline `<!-- author guidance -->` HTML comments. Render that file with the per-brief values substituted; leave any section's body as `_(none)_` rather than fabricating content. Preserve the template's HTML comments verbatim (they are part of the contract) but do NOT promote them to body prose.
+The installed template `~/.okstra/templates/reports/brief.template.md` is the byte-for-byte SSOT for the brief shape — frontmatter keys, top-header blockquote, section ordering, and inline `<!-- author guidance -->` HTML comments. Render that file with the per-brief values substituted; leave any section's body as `_(none)_` rather than fabricating content. Preserve the template's HTML comments verbatim (they are part of the contract) but do NOT promote them to body prose.
 
 **Variant note:** The template file is the canonical reporter-input shape. For the codebase-scan variant (`scope: codebase` in frontmatter), OMIT the `## Source Material` and `## Problem / Symptom` headings entirely — do NOT include them with `_(none)_` bodies. Instead, KEEP the `## Scan Scope` and `## Priority Lenses` sections (already present in the template file, marked with HTML comments). The remaining sections (Context / Desired Outcome / Constraints / Related Artifacts / Open Questions / Reporter Confirmations / Augmentation) apply to both variants.
 
@@ -710,6 +710,22 @@ Material).
   frontmatter.
 - `ticket-id` is populated only for tracker sources; leave it as an empty
   string otherwise.
+- `source-type` records the input origin (`file | linear | jira | github |
+  notion | url | user-input`).
+- `task-group` echoes the Step 2a value.
+- `created` is the brief's creation date (`YYYY-MM-DD`).
+- `generator: okstra-brief` is a fixed value.
+- `reporter-confirmations` is set by Step 6.5 (`complete | partial | pending |
+  skipped`).
+- `scope` is `codebase` for the codebase-scan variant; omit it (⇒
+  `reporter-input`) for the reporter-input variant.
+
+The required-key set (`type`, `brief-id`, `parent-id`, `ticket-id`,
+`source-type`, `task-group`, `depth`, `created`, `generator`,
+`reporter-confirmations`) and every consistency rule above are enforced by
+`~/.okstra/lib/validators/validate-brief.py` — run in
+Step 6.6. The byte-for-byte field shape remains the job of
+`~/.okstra/templates/reports/brief.template.md`.
 
 Echo the file path back on one line. Show the rendered brief to the user
 inline and ask:
@@ -750,8 +766,17 @@ cannot resolve:
 - `intent-check:` (auto-mirrored from `intent-inference` augmentations)
 - `conversion-block:` (translation failed in Step 3c)
 
-If the resulting list is empty, set `reporter-confirmations: complete` in
-the brief's frontmatter and skip the rest of this step.
+**Re-run reseed (rebuild from disk).** A prior run may have left this brief at
+`reporter-confirmations: partial` with some rows already answered. Before
+building the pending list, exclude every `intent-check:` / `conversion-block:`
+row that already carries a `[CONFIRMED <date> → RC-N]` marker — those were
+resolved in an earlier run and their answers already live under `## Reporter
+Confirmations`. Only the unmarked rows are pending this run. This mirrors the
+visited-set rebuild rule in Step 1b: confirmation state lives on disk, not in
+memory.
+
+If the resulting pending list is empty, set `reporter-confirmations: complete`
+in the brief's frontmatter and skip the rest of this step.
 
 ### 6.5b. Ask once: collect now or later
 
@@ -839,6 +864,37 @@ rows (`complete` / `partial` with remainder in the same file) or an
 explicit `skipped` signal that downstream phases consume per the
 "Brief consumption" addendum in `_common-contract.md`.
 
+## Step 6.6: Self-validate before hand-off
+
+After every brief is written (Step 5) and its `reporter-confirmations` state
+is set (Step 6.5), and **before** printing the Step 7 hand-off message, you
+MUST validate every brief produced this run. The validator enforces the
+labelled-handoff contract — required frontmatter keys, Augmentation labels,
+`intent-inference ↔ intent-check:` auto-mirroring, `parent-id`/`depth`
+consistency, `reporter-confirmations` markers, and the codebase-scan
+`scope`/`Scan Scope`/`Priority Lenses` rules.
+
+1. Run the validator over the briefs directory:
+
+   ```bash
+   ~/.okstra/lib/validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
+   ```
+
+   If you are working from a repo checkout instead of an install, the dev
+   copy is at `validators/validate-brief.sh`.
+
+2. If it exits non-zero, **fix the offending brief(s) and re-run**. Do NOT
+   print the Step 7 message until the validator passes.
+
+3. If neither validator copy is present, fall back to a manual checklist:
+   confirm each brief has all ten required frontmatter keys (`type`,
+   `brief-id`, `parent-id`, `ticket-id`, `source-type`, `task-group`,
+   `depth`, `created`, `generator`, `reporter-confirmations`); every
+   Augmentation entry carries one of the four labels; every `intent-inference`
+   has a paired `intent-check:` row; `parent-id` is `self` at depth 0 and a
+   real parent id below; and for `scope: codebase` briefs, `Scan Scope` is
+   non-empty and `Priority Lenses` lists 1–4 whitelist lenses.
+
 ## Step 7: Hand off
 
 Single brief:
@@ -866,13 +922,10 @@ started.
 
 ## Output Rules
 
-- All okstra-generated artifacts live under
-  `<PROJECT_ROOT>/.okstra/`. This skill's brief files go
-  under `.okstra/briefs/`; its glossary writes go to
-  `.okstra/glossary.md` (Step 4.5 approval flow).
-- Paths outside `<PROJECT_ROOT>/.okstra/**` are read-only
-  source material only when explicitly cited by the reporter. This skill
-  never writes outside okstra's subtree.
+- **Artifact-home** (see the "Artifact-home rule" section above): every write
+  stays under `<PROJECT_ROOT>/.okstra/` — briefs in `.okstra/briefs/`, glossary
+  in `.okstra/glossary.md` (Step 4.5). Paths outside that subtree are read-only
+  source material, and only when the reporter cited them.
 - **Verbatim source**: never paraphrase, summarize, restructure, or reorder
   the Source Material section. Only format conversion (ADF → MD, HTML → MD)
   is allowed, and the conversion must be annotated in the `format:` meta.
@@ -910,3 +963,4 @@ started.
 | URL fetch fails or 401 / login wall | intranet, paywall, JS-rendered page | Ask the user to paste the core body. Never guess. |
 | Tracker body is in non-MD format (ADF / HTML) | Jira description, Notion blocks | Convert format only, preserve semantics. Annotate the conversion in the `format:` meta. |
 | Brief comes out skeletal after synthesis | source too thin AND user picked `User input` with little context | Switch to inline input mode and ask one or two targeted questions. |
+| `validate-brief` exits non-zero in Step 6.6 | missing frontmatter key, unlabelled augmentation, broken auto-mirroring, or codebase-scan lens out of whitelist | Read the validator's per-row message, fix the cited brief, re-run. Never print the Step 7 hand-off until it passes. |

package/runtime/skills/okstra-inspect/SKILL.md

@@ -360,7 +360,7 @@ If a run never reached Phase 7, its `team-state` lacks `durationMs`. Mark such r
 3. Multiple matches → list candidates (`taskKey`, `taskType`, `updatedAt`) and ask the user to pick.
 4. Read `historyTimelinePath` from the chosen entry.
 
-If `task-catalog.json` is missing: `No okstra history found. Run scripts/okstra.sh first.`
+If `task-catalog.json` is missing: `No okstra history found. Run /okstra-run first.`
 
 ### time.2 — Walk runs and collect durations
 

package/runtime/skills/okstra-schedule/SKILL.md

@@ -236,7 +236,7 @@ The validator rejects any of these patterns.
 
 ## Section Contract (required)
 
-The canonical template lives at `templates/reports/schedule.template.md`. **Read it before writing the schedule** and follow it byte-for-byte for headings.
+The canonical template lives at `~/.okstra/templates/reports/schedule.template.md`. **Read it before writing the schedule** and follow it byte-for-byte for headings.
 
 ### MUST — exact ordered heading list
 
@@ -441,14 +441,14 @@ After writing the file and before printing the completion message in Step 7, you
 1. **Re-read the file** you just wrote.
 2. **Run the validator**:
    ```bash
-   python3 validators/validate-schedule.py <output-path>
+   python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>
    ```
 3. If the validator exits non-zero, **fix the file and re-validate**. Do not print the completion message until the validator passes.
-4. If `validators/validate-schedule.py` is not present in the repo, fall back to a manual checklist: confirm each of the 11 mandatory headings from `### MUST — exact ordered heading list` (above) appears in the file with that exact spelling, the title ends with `— Work Schedule`, and the metadata `> Generated:` block is present.
+4. If `~/.okstra/lib/validators/validate-schedule.py` is not present, fall back to a manual checklist: confirm each of the 11 mandatory headings from `### MUST — exact ordered heading list` (above) appears in the file with that exact spelling, the title ends with `— Work Schedule`, and the metadata `> Generated:` block is present.
 
 ## Schedule Document Template
 
-[`templates/reports/schedule.template.md`](../../templates/reports/schedule.template.md) is the byte-for-byte SSOT for section ordering, heading spelling, table columns, and per-section HTML-comment guidance (Dependency Graph Shape A/B, Gantt rules, optional Glossary gate). Do not omit sections; if data is unavailable, render the section with `_없음_` rather than skipping it.
+The installed template `~/.okstra/templates/reports/schedule.template.md` is the byte-for-byte SSOT for section ordering, heading spelling, table columns, and per-section HTML-comment guidance (Dependency Graph Shape A/B, Gantt rules, optional Glossary gate). Do not omit sections; if data is unavailable, render the section with `_없음_` rather than skipping it.
 
 The two rules below complement the template — they encode COMPUTATION that the template scaffold cannot carry inline.
 

package/runtime/skills/okstra-setup/SKILL.md

@@ -250,8 +250,8 @@ back it up as `.bak.<timestamp>` rather than overwriting silently.
 ## Step 4.8 (optional, opt-in): register a project PR body template
 
 `release-handoff` fills the PR body from a template. By default it uses the
-bundled skill template at
-`~/.claude/skills/templates/prd/pr-body.template.md`. Most projects
+installed template at
+`~/.okstra/templates/prd/pr-body.template.md`. Most projects
 want their own — e.g. the repo's `.github/PULL_REQUEST_TEMPLATE.md` — to
 keep PRs consistent with what the team already merges manually.
 

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

@@ -14,140 +14,31 @@
       "WebFetch",
       "WebSearch",
       "TodoWrite",
-
-      "Bash(pwd)",
-      "Bash(cd)",
-      "Bash(cd:*)",
-
-      "Bash(ls)",
-      "Bash(ls:*)",
-      "Bash(cat:*)",
-      "Bash(head:*)",
-      "Bash(tail:*)",
-      "Bash(wc:*)",
-
-      "Bash(git)",
-      "Bash(git:*)",
-      "Bash(gh)",
-      "Bash(gh:*)",
-
-      "Bash(rg:*)",
-      "Bash(grep:*)",
-      "Bash(find:*)",
-      "Bash(diff:*)",
-
-      "Bash(jq:*)",
-      "Bash(yq:*)",
-      "Bash(awk:*)",
-      "Bash(sed:*)",
-      "Bash(tr:*)",
-      "Bash(sort:*)",
-      "Bash(uniq:*)",
-      "Bash(xargs:*)",
-
-      "Bash(mkdir:*)",
-      "Bash(cp:*)",
-      "Bash(mv:*)",
-      "Bash(rm:*)",
-      "Bash(chmod:*)",
-
-      "Bash(printf:*)",
-      "Bash(echo)",
-      "Bash(echo:*)",
-      "Bash(export:*)",
-      "Bash(env)",
-      "Bash(env:*)",
-      "Bash(test:*)",
-      "Bash(true)",
-      "Bash(true:*)",
-      "Bash(false)",
-      "Bash(false:*)",
-
-      "Bash(bash:*)",
-      "Bash(sh:*)",
-      "Bash(eval:*)",
-
-      "Bash(python)",
-      "Bash(python:*)",
-      "Bash(python3)",
-      "Bash(python3:*)",
-      "Bash(pip)",
-      "Bash(pip:*)",
-      "Bash(pip3)",
-      "Bash(pip3:*)",
-      "Bash(uv:*)",
-      "Bash(poetry:*)",
-      "Bash(pytest:*)",
-
-      "Bash(node)",
-      "Bash(node:*)",
-      "Bash(npm)",
-      "Bash(npm:*)",
-      "Bash(npx)",
-      "Bash(npx:*)",
-      "Bash(pnpm)",
-      "Bash(pnpm:*)",
-      "Bash(yarn)",
-      "Bash(yarn:*)",
-      "Bash(tsc)",
-      "Bash(tsc:*)",
-
-      "Bash(cargo)",
-      "Bash(cargo:*)",
-      "Bash(rustc)",
-      "Bash(rustc:*)",
-
-      "Bash(go)",
-      "Bash(go:*)",
-      "Bash(java)",
-      "Bash(java:*)",
-      "Bash(javac)",
-      "Bash(javac:*)",
-      "Bash(mvn)",
-      "Bash(mvn:*)",
-      "Bash(gradle)",
-      "Bash(gradle:*)",
-      "Bash(./gradlew)",
-      "Bash(./gradlew:*)",
-      "Bash(make)",
-      "Bash(make:*)",
-
-      "Bash(docker)",
-      "Bash(docker:*)",
-      "Bash(docker compose)",
-      "Bash(docker compose:*)",
-      "Bash(docker-compose)",
-      "Bash(docker-compose:*)",
-      "Bash(kubectl)",
-      "Bash(kubectl:*)",
-      "Bash(helm)",
-      "Bash(helm:*)",
-
-      "Bash(curl:*)",
-      "Bash(wget:*)",
-
-      "Bash(codex)",
-      "Bash(codex:*)",
-      "Bash(codex exec:*)",
       "Bash(okstra)",
       "Bash(okstra:*)",
       "Bash(npx okstra@latest:*)",
       "Bash(npx -y okstra@latest:*)",
       "Bash($HOME/.okstra/bin/:*)",
-      "Bash(STATE_FILE=:*)",
-      "Bash(ROOT=:*)",
-
+      "Bash(codex)",
+      "Bash(codex:*)",
       "Bash(gemini)",
       "Bash(gemini:*)",
-
       "Bash(claude)",
-      "Bash(claude:*)",
-
-      "mcp__test-context7__resolve-library-id",
-      "mcp__test-context7__query-docs"
+      "Bash(claude:*)"
     ]
   },
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$HOME/.okstra/prompts/coding-preflight/scripts/preedit-check.sh\""
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

package/runtime/validators/validate-brief.py

@@ -25,7 +25,13 @@ Checks performed per brief file:
    own `brief-id`.
 9. `reporter-confirmations` consistency: when `complete`, every
    `intent-check:` and `conversion-block:` row in Open Questions MUST
-   carry a `[CONFIRMED YYYY-MM-DD → RC-N]` marker.
+   carry a `[CONFIRMED YYYY-MM-DD → RC-N]` marker; when `partial`, at
+   least one such row MUST carry the marker (use `skipped` when nothing
+   was answered).
+10. `scope` is one of {reporter-input, codebase} (absent ⇒ reporter-input).
+11. codebase-scan variant (`scope: codebase`): the Scan Scope section is
+    non-empty and Priority Lenses lists 1–4 values from the lens whitelist
+    (`scripts/okstra_ctl/improvement_lenses.py` SSOT).
 
 Exit code 0 on PASS, 1 on FAIL.
 """
@@ -38,6 +44,19 @@ import sys
 from pathlib import Path
 from typing import Iterable
 
+# scripts/ (repo) or python/ (installed under ~/.okstra/lib) is not a package;
+# insert whichever exists so okstra_ctl is importable for the lens whitelist.
+_VALIDATORS_DIR = Path(__file__).resolve().parent
+for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
+    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
+        sys.path.insert(0, str(_ssot_dir))
+
+from okstra_ctl.improvement_lenses import (
+    LENSES,
+    MAX_PRIORITY_LENSES,
+    MIN_PRIORITY_LENSES,
+)
+
 REQUIRED_FRONTMATTER_KEYS = {
     "type",
     "brief-id",
@@ -68,6 +87,8 @@ AUGMENTATION_LABELS = {
 
 REPORTER_CONFIRMATION_VALUES = {"complete", "partial", "pending", "skipped"}
 
+SCOPE_VALUES = {"reporter-input", "codebase"}
+
 
 def parse_frontmatter(text: str) -> tuple[dict[str, str], int]:
     """Return (frontmatter dict, line after closing `---`)."""
@@ -173,6 +194,68 @@ def parse_augmentation_label(entry: str) -> tuple[str | None, str]:
     return None, stripped
 
 
+def meaningful_bullets(text: str, heading: str) -> list[str]:
+    """Real `- ` bullets under a heading, excluding placeholders/template scaffold."""
+    body = section_body(text, heading)
+    out: list[str] = []
+    for line in body.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        content = stripped[2:].strip()
+        if is_placeholder(content) or is_template_example(content):
+            continue
+        out.append(content.strip("`"))
+    return out
+
+
+def priority_lens_values(text: str) -> list[str]:
+    """Lens tokens from the `## Priority Lenses` bullets (`- <lens>: <rationale>`)."""
+    return [
+        bullet.split(":", 1)[0].strip()
+        for bullet in meaningful_bullets(text, "Priority Lenses")
+    ]
+
+
+def check_codebase_scope(text: str, errors: list[str]) -> None:
+    """codebase-scan variant: Scan Scope non-empty, Priority Lenses ⊆ whitelist."""
+    if not meaningful_bullets(text, "Scan Scope"):
+        errors.append("scope is 'codebase' but the Scan Scope section has no entries")
+    lenses = priority_lens_values(text)
+    if not (MIN_PRIORITY_LENSES <= len(lenses) <= MAX_PRIORITY_LENSES):
+        errors.append(
+            f"Priority Lenses must list {MIN_PRIORITY_LENSES}–{MAX_PRIORITY_LENSES} "
+            f"lens(es), found {len(lenses)}"
+        )
+    unknown = [lens for lens in lenses if lens not in LENSES]
+    if unknown:
+        errors.append(
+            f"Priority Lenses contains values outside the lens whitelist: {unknown} "
+            f"(allowed: {sorted(LENSES)})"
+        )
+
+
+def check_reporter_confirmations(
+    rc_status: str | None, reporter_rows: list[str], errors: list[str]
+) -> None:
+    """`complete` ⇒ every reporter row confirmed; `partial` ⇒ at least one."""
+    confirmed = [row for row in reporter_rows if "[CONFIRMED" in row]
+    if rc_status == "complete":
+        unconfirmed = [row for row in reporter_rows if "[CONFIRMED" not in row]
+        if unconfirmed:
+            errors.append(
+                f"reporter-confirmations is 'complete' but {len(unconfirmed)} "
+                f"intent-check:/conversion-block: row(s) lack a [CONFIRMED …] "
+                f"marker (e.g. {unconfirmed[0]!r})"
+            )
+    elif rc_status == "partial" and reporter_rows and not confirmed:
+        errors.append(
+            "reporter-confirmations is 'partial' but no intent-check:/"
+            "conversion-block: row carries a [CONFIRMED …] marker "
+            "(use 'skipped' when nothing was answered)"
+        )
+
+
 def validate_brief(path: Path, briefs_root: Path) -> list[str]:
     text = path.read_text(encoding="utf-8")
     errors: list[str] = []
@@ -202,6 +285,15 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
             f"{fm.get('reporter-confirmations')!r}"
         )
 
+    scope = fm.get("scope", "reporter-input")
+    if scope not in SCOPE_VALUES:
+        errors.append(
+            f"frontmatter scope must be one of {sorted(SCOPE_VALUES)} "
+            f"(or absent ⇒ reporter-input), got {scope!r}"
+        )
+    if scope == "codebase":
+        check_codebase_scope(text, errors)
+
     # 2. brief-id matches filename stem
     stem = path.stem
     if fm.get("brief-id") and fm["brief-id"] != stem:
@@ -306,21 +398,12 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
                 f"({brief_id!r})"
             )
 
-    # 9. reporter-confirmations consistency
-    rc_status = fm.get("reporter-confirmations")
-    if rc_status == "complete":
-        unconfirmed = [
-            row
-            for row in (intent_check_rows + conversion_block_rows)
-            if "[CONFIRMED" not in row
-        ]
-        if unconfirmed:
-            sample = unconfirmed[0]
-            errors.append(
-                f"reporter-confirmations is 'complete' but {len(unconfirmed)} "
-                f"intent-check:/conversion-block: row(s) lack a [CONFIRMED …] "
-                f"marker (e.g. {sample!r})"
-            )
+    # 9. reporter-confirmations consistency (complete / partial)
+    check_reporter_confirmations(
+        fm.get("reporter-confirmations"),
+        intent_check_rows + conversion_block_rows,
+        errors,
+    )
 
     return errors
 

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 {