okstra 0.163.2 → 0.165.0

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

@@ -1,7 +1,7 @@
 ---
 name: okstra-inspect
 description: >-
-  Use this for everything that happens AFTER a single okstra task has already run — inspecting it or light bookkeeping on it, never launching new work. The tell is usually a named task id (PROD-1623, dev-9184), often dropped without the word "okstra." Reach for it when the user wants one task's: status, current/next phase, blockers, or approval gate; its final report — where it is or whether it passed (verdict / pass); its elapsed time or context/read cost; its run history, re-run, or resume; to mark it done / in-progress / blocked / todo; or a failed run's error logs gathered into a report (error report). Also turns cross-project okstra errors into an anonymized zip (error feedback) or GitHub issues (file okstra issues), and audits run health across tasks (run audit). NOT for starting a run (okstra-run), rollups/schedules (okstra-rollup / okstra-schedule-gen), a brief (okstra-brief-gen), setup (okstra-setup), or cross-project management (okstra-manager).
+  Use this for everything that happens AFTER a single okstra task has already run — inspecting it or light bookkeeping on it, never launching new work. The tell is usually a named task id (PROD-1623, dev-9184), often dropped without the word "okstra." Reach for it when the user wants one task's: status, current/next phase, blockers, or approval gate; its final report — where it is or whether it passed (verdict / pass); its elapsed time or context/read cost; its run history, re-run, or resume; to mark it done / in-progress / blocked / todo; or a failed run's error logs gathered into a report (error report). Also turns cross-project okstra errors into an anonymized zip (error feedback), and audits run health across tasks (run audit). NOT for starting a run (okstra-run), rollups/schedules (okstra-rollup / okstra-schedule-gen), a brief (okstra-brief-gen), setup (okstra-setup), or cross-project management (okstra-manager).
 ---
 
 # OKSTRA Inspect
@@ -18,7 +18,6 @@ Single read-side entry point for okstra runtime inspection plus the one status m
 | `cost` | `facets/cost.md` | Estimate file/read context cost for a task bundle. |
 | `errors` | `facets/errors.md` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
 | `error-zip` | `facets/error-zip.md` | Collect cross-project okstra error logs into an anonymized zip (report + raw) and summarize clusters. |
-| `error-issue` | `facets/error-issue.md` | Turn cross-project okstra anomalies into GitHub issue candidates; file the approved ones after explicit user approval. |
 | `run-audit` | `facets/run-audit.md` | Check every run's artifacts against progress invariants; report what went wrong without an error ever being logged. |
 | `recap` | `facets/recap.md` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`, and writes agent-authored notes to `notes/` for feeding into later runs. |
 

package/runtime/skills/okstra-inspect/facets/logs.md

@@ -6,17 +6,17 @@ Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step
 
 Trigger phrases: "okstra logs", "log status", "log files", "log size", "log cleanup".
 
-Read-only inventory of codex/antigravity wrapper log files written next to each prompt history file (`<prompt>.log`). Reports sizes, ages, totals, and suggests cleanup commands. **Does not delete** — the user runs whichever `find … -delete` line they like.
+Read-only inventory of the worker log files written next to each prompt history file (`<prompt>.log`). Reports sizes, ages, totals, and suggests cleanup commands. **Does not delete** — the user runs whichever `find … -delete` line they like.
 
-**Background:** codex/antigravity wrappers (`okstra-codex-exec.sh`, `okstra-antigravity-exec.sh`) write a sidecar log next to each prompt history file:
+**Background:** every CLI-worker dispatch writes a sidecar log next to its prompt history file. All five providers go through the same shared runner (`~/.okstra/lib/python/okstra_ctl/worker_runner.py`), so the file is there whichever provider ran:
 
 ```
 .okstra/tasks/<task-group>/<task-id>/runs/<phase>/prompts/
   <worker>-worker-prompt-<phase>-<seq>.md    <-- prompt (git-tracked)
-  <worker>-worker-prompt-<phase>-<seq>.log   <-- live stdout+stderr mirror
+  <worker>-worker-prompt-<phase>-<seq>.log   <-- the run's archive of what the worker did
 ```
 
-The log is truncated at each dispatch (`: > "$log_path"`) — only the latest run for a given seq is preserved. Different seqs keep separate files. Long-running implementation dispatches can produce multi-MB logs; analysis-phase dispatches are typically smaller.
+The log is rewritten from scratch at each dispatch — only the latest run for a given seq is preserved. Different seqs keep separate files. It holds one row per tool call and per tool result plus the worker's closing text, and drops thinking; a provider that emits plain text instead of an event stream has its progress copy capped at 5000 lines per run, with `[okstra log-cap] N progress line(s) elided` marking what was dropped. Long-running implementation dispatches can still produce multi-MB logs; analysis-phase dispatches are typically smaller.
 
 ### logs.1 — Inventory
 
@@ -29,7 +29,7 @@ Scans `<projectRoot>/.okstra/tasks/**/runs/*/prompts/*.log` and parses task/phas
 - `perTask[]` — `{taskKey, fileCount, totalBytes, oldestEpoch, newestEpoch}`, total-size desc
 - `totals` — `{fileCount, totalBytes, taskCount}`
 
-If `totals.fileCount` is 0, report `No wrapper log files found under <projectRoot>` and stop.
+If `totals.fileCount` is 0, report `No worker log files found under <projectRoot>` and stop.
 
 ### logs.2 — Summary tables
 

package/runtime/skills/okstra-inspect/facets/run-audit.md

@@ -28,7 +28,7 @@ Under each, list the affected `taskKey` values with their `detail` and `source`.
 State plainly which violations are this task's own state versus a repeated okstra defect:
 
 - an invariant broken in **one** task → that task's own state; tell the user what to do about that task
-- an invariant broken across **two or more** tasks → an okstra defect; point at `/okstra-inspect error-issue` to file it
-- `approval-not-forgotten` is the exception and never routes to `error-issue` no matter how far it spreads. It means a human has not approved yet, not that okstra did something wrong — `error_issue.NEVER_AN_ISSUE` drops it, so pointing the user at `error-issue` for it promises a filing that will never happen. Report it as a to-do list of tasks awaiting the user's approval instead.
+- an invariant broken across **two or more** tasks → a repeated okstra defect; say so and cite every affected `taskKey` so the user can decide what to do with it
+- `approval-not-forgotten` is the exception no matter how far it spreads. It means a human has not approved yet, not that okstra did something wrong. Report it as a to-do list of tasks awaiting the user's approval instead.
 
-Never file an issue from this facet. Filing is `error-issue`'s job and it has its own approval gate.
+This facet reports; it never files anything anywhere.

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

@@ -41,28 +41,29 @@ Every non-terminal `next` carries a `progress` object (`done` / `aborted` omit i
 
 On `ok: false`, re-prompt with the same `current.step` using the error message. The wizard never advances on validation failure; the user retries the same step. **`current` may be `null`** when the current step itself cannot render (e.g. the approved plan's Stage Map is corrupt) — that case is terminal: show `error` and stop, the user must fix the plan file before retrying. Never re-prompt off a `null` `current`.
 
-The wizard tells you *which UI to use* via `kind` (and the optional `multi` flag on `pick`):
-
-- `kind: "pick"` + `presentation: "numbered-text"` → do not call `AskUserQuestion`. Render every option as a numbered Markdown list in its original order, then consume the user's next message as the answer. Submit that message unchanged with `--answer`; the wizard accepts a 1-based number, an exact option value, or an exact option label and resolves it to the canonical value. An invalid, out-of-range, or ambiguous answer returns `ok: false` and must re-prompt the same complete list.
-- `kind: "pick"` + `multi: false` (default) → render `AskUserQuestion` with `label`, `options[].label`, and `multiSelect: false`. Use the chosen `options[].value` (single string) as the answer.
-- `kind: "pick"` + `multi: true` → render `AskUserQuestion` with `label`, `options[].label`, and `multiSelect: true`. Join the chosen `options[].value` entries with `,` into a single CSV string and submit that as `--answer "csv,values"`. If the user selects nothing, still submit `--answer ""` — the wizard will reply `ok: false` and re-prompt the same step (do not skip the call).
-- `kind: "pick_group"` → render a SINGLE `AskUserQuestion` whose questions array maps 1:1 to the wizard's `questions[]`. For each entry use `questions[].label`, `questions[].options[].label`, and `multiSelect: questions[].multi`. Collect the user's chosen `options[].value` per tab, build a JSON object keyed by each `questions[].step`, and submit it as a single literal `--answer '{"lead_model":"opus","claude_model":"default",...}'`. A tab the user leaves at its default still gets its `"default"`/`""` value in the JSON. Never split a `pick_group` into multiple `AskUserQuestion` calls — the wizard already capped it at 4 tabs and emits any remainder as the next prompt.
-- `kind: "text"` → write `label` as a plain text message and consume the user's NEXT message as the answer.
+The wizard tells you which relay operation to use via `next.interaction.kind`. Step 1 loads the current registered host's relay contract. Use the matching entry under its `interactions` object exactly; if the entry is absent, stop instead of inventing a host function or falling back silently. The only exception is the explicit `Legacy text relay compatibility` mapping selected in Step 1 when the preflight response has no `relayContract`.
+
+- `native-single` → use the current registered host's relay contract for its native single-select function. Pass every option in its original order and submit the selected `options[].value`.
+- `native-multi` → use the relay contract's native multi-select function. Pass every option in its original order and submit the selected values as one CSV answer; submit an empty selection as `--answer ""`.
+- `native-group` → use the relay contract's native grouped-question function once. Preserve every question and option, then submit one JSON object keyed by `questions[].step`; when a grouped question is multi-select, its step value is the selected option values joined as one CSV string, not a JSON array.
+- `numbered-single` → render every option as a 1-based numbered Markdown list and submit the user's next message unchanged.
+- `numbered-multi` → render every option as a 1-based numbered Markdown list and submit the user's comma-separated reply unchanged.
+- `sequential-group` → render every question in order, preserve each complete option list, collect every answer, and submit one JSON object keyed by `questions[].step`.
+- `plain-text` → write `label` as plain text and submit the user's next message unchanged.
 - `kind: "done"` → input collection finished; move to Step 5.
 - `kind: "aborted"` → the user picked abort; the wizard is terminally cancelled. Tell the user on one short line that the run setup was aborted, delete the state file (`rm` with the literal path), and stop this skill — do NOT call `render-args` or `render-bundle` (the wizard rejects `render-args` on an aborted state).
 
+Submit the answer shape required by `interaction.answerProtocol`; do not add normalization that the protocol does not request. Invalid, out-of-range, or ambiguous answers return `ok: false` and must re-render the same complete interaction.
+
 The final `confirm` step is a normal `pick` step with three options — `Proceed` / `Edit` / `Abort`(abort) — and is rendered the same way (no special handling). `Edit` rewinds to any earlier step (including `base-ref`); `Abort` terminally cancels the wizard. The branch/worktree decision the run will actually use (for `implementation`, the **stage worktree** — not the task-key directory) is folded into the Step 4 confirmation summary block as a `worktree` line, so there is no separate branch-confirm prompt.
 
-Never invent additional questions. Never reorder. **Never drop, hide, or merge a `pick` / `pick_group` option** — render every `options[]` entry, including entries that carry a `(default)` / `(recommended)` suffix. Use an `AskUserQuestion` choice unless the wizard explicitly sets `presentation: "numbered-text"`; that presentation preserves overflow choices as a numbered Markdown list. Do NOT collapse a multi-option pick into a "recommended + Enter directly / Other" shortlist: the wizard's `options[]` array IS the complete, authoritative choice set. Example: if a pick's `options[]` carries N entries, render all N — never abbreviate a multi-option step down to one recommended value. The run-prompt recommendation rule (1–2 recommendations + Enter directly) applies ONLY to prompts this skill authors itself (e.g. the conformance-waiver picker), never to wizard-provided `options[]`. Never use `AskUserQuestion` for `text` prompts — the wizard explicitly chose `text` to avoid the picker-Other re-render lag.
+Never invent additional questions. **Never drop, hide, merge, reorder, or truncate** a `pick` / `pick_group` option — relay every `options[]` entry, including entries that carry a `(default)` / `(recommended)` suffix. Do not collapse a multi-option pick into a "recommended + Enter directly / Other" shortlist. The wizard's arrays are the complete authoritative choice sets, regardless of the current host UI's usual option limit. The run-prompt recommendation rule (1–2 recommendations + Enter directly) applies only to prompts this skill authors itself, never to wizard-provided options.
 
 ## Step 1: Preflight
 
-Resolve `<host-runtime>` from the host that is executing this skill. This is a harness capability declaration, never a `which`/`PATH` inference and never a worker-provider choice:
+Use the launcher's `OKSTRA_RUNTIME_HOST` value when it is present. Otherwise use the registered host ID that the current harness declares for this session. This is a harness capability declaration, never a worker-provider choice. Do not infer it from an executable or `PATH`, and do not silently substitute another host.
 
-- Claude Code host → `claude-code`
-- Codex host → `codex`
-- Antigravity CLI host → `antigravity`
-- other host → `external`
+Record the semantic functions that the live harness can actually perform. Always include `plain_text_input`. Record `native_single_select`, `native_multi_select`, or `native_question_group` only when the current harness exposes that function. Do not infer functions from the host ID; the effective declaration is computed from the relay contract after preflight.
 
 The host-native provider runs as the current lead session when its role is supported. Other selected providers run through their registered CLI wrappers. Claude remains only the model-policy default; it is not the process owner.
 
@@ -72,15 +73,61 @@ Run one Bash tool call (Bash invocation rule from the top of this file applies):
 okstra preflight --runtime <host-runtime> --json
 ```
 
-Parse the stdout JSON. `ok: false` (or `okstra` not on `PATH` at all) → tell the user: "okstra not set up — run `/okstra-setup` first." Then stop. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary). Do **not** try to invoke `npx -y okstra@latest ...` as a fallback — `npx` is not on the literal-token allow-list and will force a confirmation prompt on every wizard call afterward. Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so never `export PYTHONPATH=...`.
+Parse the stdout JSON. If `ok: false` with `stage: runtime_readiness`, show `runtimeReadiness.status` and every readiness check, including each adapter-provided `action`, then stop before Step 2. Do not relabel a host login, license, daemon, trust, or other readiness failure as missing Okstra setup. Any other `ok: false` response (or `okstra` not on `PATH` at all) → tell the user: "okstra not set up — run `/okstra-setup` first." Then stop. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary). Do **not** try to invoke `npx -y okstra@latest ...` as a fallback — `npx` is not on the literal-token allow-list and will force a confirmation prompt on every wizard call afterward. Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so never `export PYTHONPATH=...`.
+
+When `runtimeReadiness` is present on an `ok: true` response, require `runtimeReadiness.status: ready` before Step 2. These checks come from the selected host adapter and are independent of worker-provider choices. A `blocked` or `unknown` status is a host readiness failure regardless of check IDs: show the status and checks, then stop before Step 2. Any other readiness status is unrecognized runtime output: show it and stop before Step 2 instead of guessing that the host is ready.
+
+For a ready response, read the absolute file path in `runtimeReadiness.relayContract` with the current host's file-read primitive. Do not derive the path from the host ID or search `PATH`. In that file, find the `Wizard interaction relay` JSON block, require `schemaVersion: 1` and `runtime` equal to `runtimeReadiness.runtime`, then take its `semanticFunctions` allowlist and intersect it with the functions the live harness exposes. Pass only that intersection to Step 2; `plain_text_input` must be present. Keep the parsed `interactions` object for Step 3's function/input/response conversion. An unreadable file, malformed block, runtime mismatch, absent `plain_text_input`, or later interaction kind missing from the object is a host relay contract failure: show the problem and stop rather than guessing.
+
+If `runtimeReadiness` is absent, preserve compatibility with an older preflight response: carry `projectRoot` and `projectId` into Step 2 and treat it as a response with no `relayContract`. If readiness exists but `relayContract` is absent, also enter the compatibility branch below. In that branch only, declare `plain_text_input` and keep its built-in `interactions` mapping for Step 3; do not assume a native tool from the host ID. The existing `unknown command: preflight` branch remains the authoritative stale-CLI failure.
 
-On `ok: true`, inspect `runtimeReadiness.checks` for the check whose `id` is `workspace-trust`. This check is host-specific and independent of the selected worker providers.
+### Legacy text relay compatibility
+
+Use this built-in mapping only when the successful preflight response omitted `relayContract`. It is not a fallback for an unreadable, malformed, mismatched, or incomplete relay contract. If a present relay contract omits the wizard's interaction kind, keep the fail-closed rule above and stop.
+
+```json
+{
+  "scope": "preflight-response-without-relayContract-only",
+  "semanticFunctions": ["plain_text_input"],
+  "interactions": {
+    "numbered-single": {
+      "function": "host-text",
+      "input": {
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "numbered-multi": {
+      "function": "host-text",
+      "input": {
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": { "source": "next-message", "submit": "raw" }
+    },
+    "sequential-group": {
+      "function": "host-text",
+      "input": {
+        "questions": "all-one-at-a-time-in-original-order",
+        "question": "label-with-progress",
+        "options": "all-in-original-order-as-numbered-markdown-label-and-description"
+      },
+      "response": {
+        "source": "next-message-by-question-position",
+        "submit": "compact-step-json-raw"
+      }
+    },
+    "plain-text": {
+      "function": "host-text",
+      "input": { "question": "label-with-progress" },
+      "response": { "source": "next-message", "submit": "raw" }
+    }
+  }
+}
+```
 
-- On `claude-code`, `status: required` with `action: restart-and-trust` → tell the user: "Claude Code must trust `<projectRoot>` before Okstra can dispatch workers. Close this session, reopen that project in Claude Code, choose `Yes, I trust this folder`, then run `/okstra-run` again." Then stop before Step 2. Never start the wizard or dispatch a worker from this session.
-- On `claude-code`, `status: unavailable` → tell the user that Claude Code workspace trust could not be verified, ask them to open `<projectRoot>` directly in Claude Code and complete any trust prompt, then run `/okstra-run` again. Then stop before Step 2.
-- `status: accepted` or `status: not-applicable` → carry `projectRoot` and `projectId` as literal strings into Step 2.
-- If `runtimeReadiness` is absent, preserve compatibility with an older preflight response: carry `projectRoot` and `projectId` into Step 2. The existing `unknown command: preflight` branch remains the authoritative stale-CLI failure.
-- Any other `workspace-trust` status is unrecognized runtime output: show the status and stop before Step 2 instead of guessing that trust exists.
+For numbered interactions, render every option as a 1-based Markdown item containing its label followed by its description verbatim, in original order. For `sequential-group`, ask every question in order and build one compact JSON object keyed by `questions[].step`. Submit each user message unchanged; the wizard owns numbered and grouped normalization.
 
 ## Step 2: Initialize the wizard
 
@@ -99,7 +146,10 @@ okstra wizard init \
   --state-file /var/folders/.../okstra-wizard.AbCd.json \
   --project-root /abs/path/to/project \
   --project-id   my-project-id \
-  --host-runtime <host-runtime>
+  --host-runtime <host-runtime> \
+  --entry-mode current-session \
+  --available-function plain_text_input \
+  --available-function <each-additional-function-in-the-effective-intersection>
 ```
 
 Output: the same `{ok, next}` JSON described above. The first `next` is always `step: "task_pick"`.
@@ -108,12 +158,7 @@ Output: the same `{ok, next}` JSON described above. The first `next` is always `
 
 Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How the wizard talks to you"):
 
-1. **Render** the prompt according to `kind` (and `multi` for pick). **Always append the progress marker to the rendered question label** (the `AskUserQuestion` question text, or the `text`-prompt message): suffix it with ` (<next.progress.label>)` — render `progress.label` exactly as the wizard sent it, never recompute it. Example: label `Step 8/11 · 3 steps remaining` → `Select a model (Step 8/11 · 3 steps remaining)`. Re-prompts after `ok: false` reuse `current.progress.label` the same way. The progress marker is presentation-only — never send it back to the wizard as part of an answer.
-   - `pick` + `presentation: "numbered-text"` → plain text containing `label`, followed by every option as a numbered Markdown list. Consume the user's next message verbatim as the answer string.
-   - `pick` + `multi: false` → `AskUserQuestion` with `multiSelect: false`, `label`, and `options`. The user's chosen option's `value` is the answer string.
-   - `pick` + `multi: true` → `AskUserQuestion` with `multiSelect: true`, `label`, and `options`. Join the selected `value`s with `,` into a single literal CSV string (e.g. `"claude,codex,grok,kimi"`) and submit it as one `--answer` value. Empty selection submits `--answer ""` and the wizard re-prompts.
-   - `pick_group` → one `AskUserQuestion` with one question per `questions[]` entry (tab). Map each tab's selected `value` back by `questions[].step`, assemble a JSON object, and submit it as a single literal `--answer '<json>'`.
-   - `text` → plain text message containing `label`. Consume the user's next reply verbatim as the answer string (empty reply = empty string).
+1. **Render** the prompt according to `next.interaction.kind` using the relay rules above. **Always append the progress marker to the rendered question label**: suffix it with ` (<next.progress.label>)` — render `progress.label` exactly as the wizard sent it, never recompute it. Example: label `Step 8/11 · 3 steps remaining` → `Select a model (Step 8/11 · 3 steps remaining)`. Re-prompts after `ok: false` reuse `current.progress.label` the same way. The progress marker is presentation-only — never send it back to the wizard as part of an answer.
 2. **Submit** the answer — call `okstra wizard step` with the literal state-file path from Step 2 and the literal user answer (no shell variables, no `$(...)`):
    ```bash
    okstra wizard step --state-file /var/folders/.../okstra-wizard.AbCd.json --answer preprod
@@ -138,7 +183,7 @@ That is the entire interactive flow. The wizard handles:
 - brief path — **asked only for entry task-types (requirements-discovery / error-analysis / improvement-discovery / project-analysis / feature-analysis / change-impact-analysis)** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, sorted by the newer of file-created/modified time and latest task-catalog use; direct input last; `Keep / Change` for existing entry tasks). `project-analysis`, `feature-analysis`, and `change-impact-analysis` are brief entry task types. A downstream lifecycle task-type auto carries in the manifest's brief, and when no registered brief exists a `brief_carry` 3-option prompt appears (recommend switching to entry / Enter directly / Abort). `release-handoff` has no brief step at all — prepare generates the input document that cites the verification report,
 - analysis-input sub-flow — `project-analysis` has no target or evidence step. `feature-analysis` runs `project_evidence_pick` / `project_evidence`, then `analysis_target_pick` / `analysis_target`; the target is required even when the user skips project evidence. `change-impact-analysis` runs `feature_evidence_pick` / `feature_evidence`, then `project_evidence_pick` / `project_evidence`. The evidence steps show accepted compatible reports first and retain direct-path entry; do not invent a different relation or reorder these steps,
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
-- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = the earliest incomplete stage whose dependencies are satisfied, or a specific stage number) + executor pick. When an approved plan is selected and a `## APPROVAL` sidecar exported from the report — matching the plan on source-report·seq — is detected in that run's sibling `user-responses/`, the approve-confirm step expands to 3 options (`yes_apply` recommended: approve + apply the option as exported / `yes` approve only / `no` abort) — `yes_apply` validates the option against the plan's `optionCandidates` before applying it via the existing approval·option path,
+- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = the earliest incomplete stage whose dependencies are satisfied, or a specific stage number) + executor pick. When an approved plan is selected and a `## PLAN DECISION` sidecar carrying `Status: approved`, exported from the report — matching the plan on source-report·seq — is detected in that run's sibling `user-responses/`, the approve-confirm step expands to 3 options (`yes_apply` recommended: approve + apply the option as exported / `yes` approve only / `no` abort) — `yes_apply` validates the option against the plan's `optionCandidates` before applying it via the existing approval·option path,
 - `release-handoff`-only sub-flow: after the approved plan auto-resolves, a `handoff_stage_pick` multi-select — choose an eligible stage bundle (stage-group) or the whole task (when an accepted whole-task verification report exists); the result goes out as render-args' `stages` key (csv, empty when whole-task),
 - `Use defaults / Customize` branch with profile-aware worker/model questions,
 - **resume-clarification (in-session equivalent)** — there is no separate mode or flag matching the shell's `okstra.sh --resume-clarification`; two steps of the standard flow carry out its substance. (1) `reuse_previous` (yes/no to reuse the previous run's settings — in `requirements-discovery` / `error-analysis` / `implementation-planning`, only when prior run-inputs exist): YES prefills workers·model·directive·related-tasks at once. (2) `clarification_pick`: if the **task-type's own** previous `final-report` exists it is auto-recommended as the carry-in input (falling back to the newest by mtime across all phases when absent), and the same run's `user-responses/` sidecar (answers the user filled in) is attached alongside. The chosen path is passed to prepare as `--clarification-response` — the user makes the sidecar via the report's `Export user response`, places it in `runs/<task-type>/user-responses/`, and re-runs the same phase,
@@ -217,7 +262,7 @@ okstra render-bundle \
 
 The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.lock`), writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
 
-You can delete the literal state-file path after this point — its job is done. Invoke `rm` with the literal path (e.g. `rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable.
+You can delete the literal state-file path after this point — its job is done. Invoke `command rm` with the literal path (e.g. `command rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable. `command` is what keeps a `rm='rm -i'` alias from turning this into a confirmation prompt nobody is there to answer.
 
 <!-- BEGIN FRAGMENT: host-orchestration-implementation -->
 ## Host orchestration rules — implementation

package/runtime/skills/okstra-user-response/SKILL.md

@@ -147,26 +147,36 @@ Once the loop has covered every open item, **before** calling `write`, **echo ba
 - If the user changes any item, show the echo-back again with the changed value and re-confirm.
 - Every `value` must be what the user picked or typed, never a wording you settled on for them — this gate guarantees that.
 
-## Step 5: (Optional) Record approval
+## Step 5: (Optional) Record the plan decision
 
-Record approval alongside only when the report's approval-blocking clarification items are **all filled with an answer** and the user explicitly said "approve with this option":
+Record a decision alongside the answers only when the user stated one outright. Never infer it from the tone of the conversation.
+
+Approval also requires that the report's approval-blocking clarification items are **all filled with an answer**:
 
 ```
---approval '{"approved":true,"implementationOption":"<the option the user chose>"}'
+--plan-decision '{"status":"approved","implementationOption":"<the option the user chose>"}'
 ```
 
 If any approval-target item is not filled with an answer, or is a reframe/hold, do not approve — tell the user the gate is still open.
 
+A user who turns the plan down gets the same treatment, and the reason is mandatory — the next planning run reads it to know what to change:
+
+```
+--plan-decision '{"status":"rejected","reason":"<the user's own words>"}'
+```
+
+Use `revision-requested` instead of `rejected` when the user wants the same plan reworked rather than dropped. Either way, quote the user's reason; do not summarise it into your own.
+
 ## Step 6: Write the sidecar
 
 Run only after the user has confirmed the echo-back with "confirmed":
 
 ```bash
-okstra user-response write --report <reportPath> --answers '<answers-json>' --approval '<approval-json>' --task-key <taskKey>
+okstra user-response write --report <reportPath> --answers '<answers-json>' --plan-decision '<plan-decision-json>' --task-key <taskKey>
 ```
 
 - `--answers` = the JSON array of `{id, kind, value, rationale?, disposition}` objects collected in Step 3.
-- `--approval` is attached only when recording approval in Step 5 (otherwise omit it).
+- `--plan-decision` is attached only when recording a decision in Step 5 (otherwise omit it).
 - `--task-key` is the value carried forward from Step 1/2.
 - Report the path from the returned JSON `{sidecar: <path>}` to the user. (`write` merges items when a sidecar already exists — the same `id` is overwritten with the new value.)
 

package/runtime/templates/implementation-worker-preamble.md

@@ -31,7 +31,7 @@ When `**Evidence ledger:** required-v1` is present, append one canonical row to
 
 - Evidence read: `<project-relative path without a line suffix>`
 
-Every file citation in the result MUST use backticks and a line suffix, for example `src/config/env.ts:1-22`. A cited path without a matching ledger row fails Phase 7 in `validators/validate-run.py` `validate_worker_results_audit()`. Do not add a row for a file you did not open.
+Every file citation in the result MUST use backticks, a line suffix, and the same project-relative path its ledger row carries — for example `src/config/env.ts:1-22`. A bare filename (`env.ts:1-22`) does not match its row and fails exactly like a file you never opened, however many times you cited the full path earlier. A cited path without a matching ledger row fails Phase 7 in `validators/validate-run.py` `validate_worker_results_audit()`. Do not add a row for a file you did not open.
 
 ## Anchor headers
 

package/runtime/templates/report-writer-prompt-preamble.md

@@ -25,6 +25,7 @@ Write `- PROGRESS: <stage> <ISO-8601-UTC>` there before reading and at least eve
 - Follow the task-type schema excerpt and Phase 6 report-writer contract. Do not perform independent analysis, edit source code, or load implementation coding-preflight resources.
 - Invoke `okstra render-final-report <Result Path>` after writing data.json and verify the markdown sibling exists before returning.
 - Preserve source item IDs, convergence classifications, round history, and unresolved dissent; do not recompute them from intuition.
+- Every `clarificationItems[]` row you leave `status: open` with `blocks: approval` carries `origin` and `userConfirmation`. `origin` is `worker-finding` only when an analyser or verifier reached it on its own evidence — when the lead's dispatch prompt told you to raise it, it is `lead-directed`, whatever the workers then agreed. `userConfirmation` is what the lead reports having done about it (`asked-and-answered` / `asked-awaiting` / `deferred-no-interactive-session`); if the dispatch does not say, write `asked-awaiting` and name the gap in your return message rather than guessing. An open approval blocker stops the whole task, so a row that misreports where it came from costs a re-run. **Enforced:** `validators/validate-run.py` `_validate_open_approval_blocker_provenance`.
 
 ## Anchor headers
 

package/runtime/templates/reports/final-report.template.md

@@ -380,10 +380,10 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 ### Stepwise Execution Order
 
-| step | action | files | command | expected |
-|------|--------|-------|---------|----------|
+| step | action | files | command | outcome | expected |
+|------|--------|-------|---------|---------|----------|
 {% for row in stage.stepwiseExecution -%}
-| {{ row.step | mdcell }} | {{ row.action | mdcell }} | `{{ row.files | mdcell }}` | `{{ row.command | mdcell }}` | {{ row.expected | mdcell }} |
+| {{ row.step | mdcell }} | {{ row.action | mdcell }} | `{{ row.files | mdcell }}` | `{{ row.command | mdcell }}` | {{ row.outcome | mdcell }} | {{ row.expectedDetail | mdcell }} |
 {% endfor %}
 
 ### Stage Exit Contract

package/runtime/templates/reports/html/assets/base.css

@@ -77,8 +77,9 @@ th, td { text-align: left; vertical-align: top; border-bottom: 1px solid color-m
 .ledger-key { display: flex; flex-wrap: wrap; gap: .6rem; font-weight: 600; }
 .ledger-kind { font-weight: 400; color: GrayText; }
 .ledger-text { max-width: 78ch; }
-.ledger-source { font-size: .9rem; color: GrayText; }
-.ledger-source > span:first-child::after { content: ":"; }
+.ledger-source, .ledger-confidence { font-size: .9rem; color: GrayText; }
+.ledger-source > span:first-child::after,
+.ledger-confidence > span:first-child::after { content: ":"; }
 .status { display: inline-block; white-space: nowrap; border-radius: 999px; padding: .1rem .5rem; background: color-mix(in srgb, GrayText 15%, Canvas); }
 .status-gap, .status-risk, .status-error, .status-timeout { background: color-mix(in srgb, #d94b4b 18%, Canvas); }
 /* Figures are read by comparing them down the column, which only works when
@@ -86,13 +87,16 @@ th, td { text-align: left; vertical-align: top; border-bottom: 1px solid color-m
    the right edge is the one they share. */
 .run-usage-lede { max-width: 78ch; }
 .figure { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; }
-/* Four nowrap number columns need almost none of the width, and the default
+/* Five nowrap number columns need almost none of the width, and the default
    even split spent it on them while the agent names wrapped mid-word. */
-[data-report-section="run-usage"] .row-key { width: 45%; }
+[data-report-section="run-usage"] .row-key { width: 40%; }
 .cli-extra { display: block; color: GrayText; font-size: .85em; }
 tfoot th { font-weight: 600; }
 tfoot tr:first-child > * { border-top: 2px solid color-mix(in srgb, CanvasText 30%, transparent); }
 tfoot .grand-total > * { font-weight: 700; }
+/* The task total counts runs this report is not about, so it is ruled off from
+   the run's own figures rather than reading as one more line of them. */
+tfoot .task-cumulative > * { border-top: 1px solid color-mix(in srgb, CanvasText 20%, transparent); color: GrayText; }
 .human-report-footer { width: min(1120px, calc(100% - 2rem)); margin: 0 auto 2rem; display: flex; flex-wrap: wrap; gap: .6rem; }
 .human-report-footer pre { flex-basis: 100%; white-space: pre-wrap; max-height: 14em; overflow: auto; }
 fieldset, label { display: block; margin: .7rem 0; }

package/runtime/templates/reports/html/base.template.html

@@ -31,9 +31,11 @@
       <ol class="ledger">
         {% for row_id, row in evidenceIndex.items() %}
         <li class="ledger-item" id="id-{{ row_id }}">
-          <p class="ledger-key"><span class="ledger-id">{{ row_id }}</span><span class="ledger-kind">{{ row.kind }}</span></p>
+          <p class="ledger-key"><span class="ledger-id">{{ row_id }}</span><span class="ledger-kind">{{ row.kind | enum_label('ledgerKind') }}</span></p>
           <p class="ledger-text">{{ row.text | inline_code }}</p>
-          <p class="ledger-source"><span>{{ t('base.source-confidence') }}</span> {% if row.codeEvidence %}{{ row.codeEvidence | code_evidence }}{% else %}{{ row.source | inline_code }}{% endif %}</p>
+          {% if row.codeEvidence %}<p class="ledger-source"><span>{{ t('base.source') }}</span> {{ row.codeEvidence | code_evidence }}</p>
+          {% elif row.source %}<p class="ledger-source"><span>{{ t('base.source') }}</span> {{ row.source | inline_code }}</p>{% endif %}
+          {% if row.confidence %}<p class="ledger-confidence"><span>{{ t('base.confidence') }}</span> {{ row.confidence | inline_code }}</p>{% endif %}
         </li>
         {% endfor %}
       </ol>
@@ -47,6 +49,7 @@
         <thead><tr>
           <th scope="col">{{ t('runUsage.agent') }}</th>
           <th scope="col" class="figure">{{ t('runUsage.raw-tokens') }}</th>
+          <th scope="col" class="figure">{{ t('runUsage.cache-read-tokens') }}</th>
           <th scope="col" class="figure">{{ t('runUsage.billable-tokens') }}</th>
           <th scope="col" class="figure">{{ t('runUsage.cost') }}</th>
           <th scope="col" class="figure">{{ t('runUsage.duration') }}</th>
@@ -56,6 +59,7 @@
           <tr>
             {{ row_key(pairs=[(t('runUsage.agent'), row.agent), (t('runUsage.role'), row.role), (t('runUsage.model'), row.model)], status_name=t('runUsage.status'), status_raw=row.status, status_text=row.status | enum_label('workerStatus')) }}
             <td class="figure">{{ row.rawTokens }}{% if row.cliTokens %}<span class="cli-extra">{{ t('runUsage.cli') }} {{ row.cliTokens }}</span>{% endif %}</td>
+            <td class="figure">{{ row.cacheReadTokens }}</td>
             <td class="figure">{{ row.billableTokens }}</td>
             <td class="figure">{{ row.cost }}{% if row.cliCost %}<span class="cli-extra">+ {{ t('runUsage.cli') }} {{ row.cliCost }}</span>{% endif %}</td>
             <td class="figure">{{ row.duration }}</td>
@@ -65,6 +69,7 @@
           <tr>
             <td class="row-key">{{ t('runUsage.unaccounted') }}</td>
             <td class="figure">{{ runUsage.unaccounted.rawTokens }}</td>
+            <td class="figure">{{ runUsage.unaccounted.cacheReadTokens }}</td>
             <td class="figure">{{ runUsage.unaccounted.billableTokens }}</td>
             <td class="figure">{{ runUsage.unaccounted.cost }}</td>
             <td class="figure"></td>
@@ -72,10 +77,11 @@
           {% endif %}
         </tbody>
         <tfoot>
-          <tr><th scope="row">{{ t('runUsage.row-lead') }}</th><td class="figure">{{ runUsage.lead.rawTokens }}</td><td class="figure">{{ runUsage.lead.billableTokens }}</td><td class="figure">{{ runUsage.lead.cost }}</td><td class="figure"></td></tr>
-          <tr><th scope="row">{{ t('runUsage.row-workers') }}</th><td class="figure">{{ runUsage.worker.rawTokens }}</td><td class="figure">{{ runUsage.worker.billableTokens }}</td><td class="figure">{{ runUsage.worker.cost }}</td><td class="figure"></td></tr>
-          <tr class="grand-total"><th scope="row">{{ t('runUsage.row-total') }}</th><td class="figure">{{ runUsage.grand.rawTokens }}</td><td class="figure">{{ runUsage.grand.billableTokens }}</td><td class="figure">{{ runUsage.grand.cost }}</td><td class="figure"></td></tr>
-          {% if runUsage.cliCost %}<tr><th scope="row">{{ t('runUsage.row-cli') }}</th><td class="figure"></td><td class="figure"></td><td class="figure">{{ runUsage.cliCost }}</td><td class="figure"></td></tr>{% endif %}
+          <tr><th scope="row">{{ t('runUsage.row-lead') }}</th><td class="figure">{{ runUsage.lead.rawTokens }}</td><td class="figure">{{ runUsage.lead.cacheReadTokens }}</td><td class="figure">{{ runUsage.lead.billableTokens }}</td><td class="figure">{{ runUsage.lead.cost }}</td><td class="figure"></td></tr>
+          <tr><th scope="row">{{ t('runUsage.row-workers') }}</th><td class="figure">{{ runUsage.worker.rawTokens }}</td><td class="figure">{{ runUsage.worker.cacheReadTokens }}</td><td class="figure">{{ runUsage.worker.billableTokens }}</td><td class="figure">{{ runUsage.worker.cost }}</td><td class="figure"></td></tr>
+          <tr class="grand-total"><th scope="row">{{ t('runUsage.row-total') }}</th><td class="figure">{{ runUsage.grand.rawTokens }}</td><td class="figure">{{ runUsage.grand.cacheReadTokens }}</td><td class="figure">{{ runUsage.grand.billableTokens }}</td><td class="figure">{{ runUsage.grand.cost }}</td><td class="figure"></td></tr>
+          {% if runUsage.cliCost %}<tr><th scope="row">{{ t('runUsage.row-cli') }}</th><td class="figure"></td><td class="figure"></td><td class="figure"></td><td class="figure">{{ runUsage.cliCost }}</td><td class="figure"></td></tr>{% endif %}
+          {% if runUsage.taskCumulative %}<tr class="task-cumulative"><th scope="row">{{ t('runUsage.row-task-cumulative') | replace('{runs}', runUsage.taskCumulative.runCount) }}</th><td class="figure">{{ runUsage.taskCumulative.rawTokens }}</td><td class="figure">{{ runUsage.taskCumulative.cacheReadTokens }}</td><td class="figure">{{ runUsage.taskCumulative.billableTokens }}</td><td class="figure">{{ runUsage.taskCumulative.cost }}</td><td class="figure"></td></tr>{% endif %}
         </tfoot>
       </table>
     </section>

package/runtime/templates/reports/html/i18n/en.json

@@ -67,6 +67,21 @@
       "timeout": "Timed out",
       "not-run": "Not run",
       "synthesis-only": "Synthesis only"
+    },
+    "replanMode": {
+      "full": "Replanned in full",
+      "incremental": "Partly replanned"
+    },
+    "ledgerKind": {
+      "code-evidence": "Code evidence",
+      "hypothesis": "Hypothesis",
+      "confirmed-fact": "Confirmed fact",
+      "inference": "Inference",
+      "unknown": "Unknown",
+      "cross-check-consensus": "Agreed across workers",
+      "cross-check-dissent": "Workers disagreed",
+      "missing-information": "Missing information",
+      "follow-up": "Follow-up"
     }
   },
   "enumHint": {
@@ -85,7 +100,8 @@
     "written": "Written",
     "elapsed": "Elapsed",
     "evidence-ledger": "Evidence ledger",
-    "source-confidence": "Source · confidence",
+    "source": "Source",
+    "confidence": "Confidence",
     "export-my-answers": "Export my answers",
     "copy": "Copy",
     "dismiss": "Dismiss",
@@ -95,7 +111,7 @@
   },
   "runUsage": {
     "heading": "What this run cost",
-    "intro": "Every agent this run dispatched, with what it spent and how long it was working. Agents run alongside each other, so their durations do not add up to the elapsed time in the header. Raw tokens are the volume processed; billable tokens are that same work restated in input-price units, which is what the cost is computed from.",
+    "intro": "What each agent this run put in, and how long it worked. Agents overlap, so their working times do not add up to the elapsed time in the header. Raw tokens are what the run sent through the model once. Cache re-reads are the context read back on every turn — they are billed at a tenth of the input rate, which is why they sit outside the raw figure but inside the money. Billable tokens restate the whole run in base-input units, and the cost comes from that.",
     "agent": "Agent",
     "role": "Role",
     "model": "Model",
@@ -109,7 +125,9 @@
     "row-lead": "Lead",
     "row-workers": "Workers",
     "row-total": "Total",
-    "row-cli": "CLI calls (billed separately)"
+    "row-cli": "CLI calls (billed separately)",
+    "cache-read-tokens": "Cache re-reads",
+    "row-task-cumulative": "This task so far ({runs} runs)"
   },
   "macros": {
     "forms": {
@@ -122,7 +140,6 @@
       "why": "Why",
       "further-evidence": "Further evidence",
       "scope-change-requested": "Scope change requested",
-      "approve-this-plan": "Approve this plan",
       "implementation-option": "Implementation option",
       "i-approve-this-plan": "I approve this plan.",
       "approval-is-held": "Approval is held:",
@@ -136,7 +153,12 @@
       "recommended": "Recommended",
       "scope-impact": "Scope",
       "added-work": "Added work",
-      "direction-change": "Direction change"
+      "direction-change": "Direction change",
+      "decide-on-this-plan": "Decide on this plan",
+      "request-changes-to-this-plan": "Send it back for changes",
+      "reject-this-plan": "Reject this plan",
+      "why-required-for-changes-or-rejection": "Why — required when you send it back or reject it",
+      "answer-the-blockers-then-regenerate": "Answer {ids}, export your answers, then regenerate the report with the clarification resume command."
     },
     "visualizations": {
       "component": "Component",
@@ -285,7 +307,8 @@
       "statement-overturned": "Statement overturned",
       "replaced-with": "Replaced with",
       "no-answer-overturned-anything": "No answer overturned anything.",
-      "scope-restated": "Scope, restated",
+      "scope-restated": "How much of the plan was rewritten",
+      "scope-restated-lede": "This planning run started from an earlier plan. This is how much of it survived your answers.",
       "stages-verified-again": "Stages verified again",
       "stages-carried-over-as-they-were": "Stages carried over as they were",
       "decision-record-draft": "Decision record draft",
@@ -297,7 +320,9 @@
       "topic": "Topic",
       "why": "Why",
       "open-decisions-before-approval": "Open decisions before approval",
-      "no-open-decision-is-holding-approval": "No open decision is holding approval."
+      "no-open-decision-is-holding-approval": "No open decision is holding approval.",
+      "uniform-verifier-label": "Uniform verifier",
+      "uniform-verifier-legend": "This verifier answered the same verdict to every item it voted on, so this round's refutation signal came from its peers alone — the gate above reads as a wider cross-check than it was. A unanimous round is a legitimate outcome; confirm from the worker's audit sidecar that it actually opened the cited evidence."
     },
     "implementation": {
       "what-was-delivered": "What was delivered",