okstra 0.164.0 → 0.165.0

package/runtime/python/okstra_token_usage/report.py

@@ -24,6 +24,8 @@ from okstra_ctl.render_final_report import (  # noqa: E402
     render_to_file,
 )
 
+from .task_totals import task_cumulative_usage  # noqa: E402
+
 
 class SubstituteRefusedError(RuntimeError):
     """Raised when substitution would write zero-only token cells.
@@ -89,6 +91,8 @@ def _populate_execution_row(row: dict, source: dict) -> None:
         return
     if "totalTokens" in usage:
         row["totalTokens"] = usage["totalTokens"]
+    if "cacheReadTokens" in usage:
+        row["cacheReadTokens"] = usage["cacheReadTokens"]
     if "billableEquivalentTokens" in usage:
         row["billableTokens"] = usage["billableEquivalentTokens"]
     if "estimatedCostUsd" in usage:
@@ -114,6 +118,7 @@ def _worker_detail_row(label: str, usage: dict) -> dict:
         return {
             "label": label,
             "totalTokens": None,
+            "cacheReadTokens": None,
             "billableTokens": None,
             "costUsd": None,
             "cliTotalTokens": None,
@@ -122,6 +127,7 @@ def _worker_detail_row(label: str, usage: dict) -> dict:
     return {
         "label": label,
         "totalTokens": usage.get("totalTokens"),
+        "cacheReadTokens": usage.get("cacheReadTokens"),
         "billableTokens": usage.get("billableEquivalentTokens"),
         "costUsd": usage.get("estimatedCostUsd"),
         "cliTotalTokens": usage.get("cliTotalTokens"),
@@ -129,6 +135,35 @@ def _worker_detail_row(label: str, usage: dict) -> dict:
     }
 
 
+def _cache_reads(summary: dict, team_state: dict) -> dict[str, int]:
+    """Lead / worker / grand cache-read totals for this run.
+
+    The figure joined `usageSummary` after most team-states on disk were
+    written, and re-rendering one of those reports is exactly when the reader
+    goes looking for the corrected table — so a state without the summary keys
+    is added up from the usage blocks it does carry.
+    """
+    lead = summary.get("leadCacheReadTokens")
+    worker = summary.get("workerCacheReadTokens")
+    if isinstance(lead, int) and isinstance(worker, int):
+        return {"lead": lead, "worker": worker, "grand": lead + worker}
+    lead = _cache_read_tokens(team_state.get("leadUsage"))
+    worker = sum(
+        _cache_read_tokens(entry.get("usage"))
+        for entry in team_state.get("workers") or []
+        if isinstance(entry, dict)
+    )
+    worker += _cache_read_tokens(summary.get("unattributedWorkerUsage"))
+    return {"lead": lead, "worker": worker, "grand": lead + worker}
+
+
+def _cache_read_tokens(usage: object) -> int:
+    if not isinstance(usage, dict):
+        return 0
+    value = usage.get("cacheReadTokens")
+    return value if isinstance(value, int) else 0
+
+
 def _worker_detail_rows(team_state: dict) -> list[dict]:
     rows = []
     for worker in team_state.get("workers") or []:
@@ -178,19 +213,23 @@ def populate_data_token_cells(data_path: Path, team_state: dict) -> int:
     worker_cost = cost.get("claudeWorkers") or 0
     cli_cost = cost.get("cliWorkers") or 0
 
+    cache_reads = _cache_reads(summary, team_state)
     token_usage = data.setdefault("tokenUsage", {})
     token_usage.setdefault("lead", {}).update({
         "totalTokens": summary.get("leadTotalTokens"),
+        "cacheReadTokens": cache_reads["lead"],
         "billableTokens": summary.get("leadBillableEquivalentTokens"),
         "costUsd": lead_cost,
     })
     token_usage.setdefault("worker", {}).update({
         "totalTokens": summary.get("workerTotalTokens"),
+        "cacheReadTokens": cache_reads["worker"],
         "billableTokens": summary.get("workerBillableEquivalentTokens"),
         "costUsd": worker_cost,
     })
     token_usage.setdefault("grand", {}).update({
         "totalTokens": summary.get("grandTotalTokens"),
+        "cacheReadTokens": cache_reads["grand"],
         "billableTokens": summary.get("grandBillableEquivalentTokens"),
         # CLI tracked on its own row per the template — grand here means
         # lead + claudeWorkers, not lead + claudeWorkers + cli.
@@ -198,6 +237,9 @@ def populate_data_token_cells(data_path: Path, team_state: dict) -> int:
     })
     token_usage.setdefault("cli", {})["costUsd"] = cli_cost
     token_usage["workerDetails"] = _worker_detail_rows(team_state)
+    cumulative = task_cumulative_usage(data_path)
+    if cumulative is not None:
+        token_usage["taskCumulative"] = cumulative
     changes += 4
 
     # Execution Status by Agent — per-row token / cost / duration.

package/runtime/python/okstra_token_usage/task_totals.py

@@ -0,0 +1,88 @@
+"""What a whole task has spent, across every run of every phase.
+
+A report's own figures cover one run, but a task reaches its plan through
+several: the first pass, a clarification re-run, a conformance fix. Each of
+those bills separately, and a reader who only ever sees the last one has no way
+to learn what the task cost. The per-run team-states are the only record of the
+earlier passes, so the total is summed from them here rather than carried
+forward inside any single run's state.
+
+Every team-state is read directly rather than through its `usageSummary`: the
+summary predates the cache-read figure, so an older run would drop out of that
+column while still counting in the others.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+_TEAM_STATE_GLOB = "runs/*/state/team-state-*.json"
+_SUMMED_KEYS = (
+    ("totalTokens", "totalTokens"),
+    ("cacheReadTokens", "cacheReadTokens"),
+    ("billableTokens", "billableEquivalentTokens"),
+    ("costUsd", "estimatedCostUsd"),
+)
+
+
+def _task_root(data_path: Path) -> Path | None:
+    """The task-bundle directory a report lives under.
+
+    Report path shape: `<task-id>/runs/<task-type>/reports/<name>.data.json`.
+    A path that does not match is not inside a task bundle — a fixture under a
+    tmp dir, most often — and has no sibling runs to total.
+    """
+    parents = data_path.parents
+    if len(parents) < 4:
+        return None
+    if parents[0].name != "reports" or parents[2].name != "runs":
+        return None
+    return parents[3]
+
+
+def _usage_blocks(team_state: dict) -> list[dict]:
+    blocks = [team_state.get("leadUsage") or {}]
+    for worker in team_state.get("workers") or []:
+        if isinstance(worker, dict):
+            blocks.append(worker.get("usage") or {})
+    unattributed = (team_state.get("usageSummary") or {}).get("unattributedWorkerUsage")
+    if isinstance(unattributed, dict):
+        blocks.append(unattributed)
+    return [block for block in blocks if isinstance(block, dict)]
+
+
+def _number(value: object) -> int | float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return 0
+    return value
+
+
+def task_cumulative_usage(data_path: Path) -> dict | None:
+    """Sum every measured run of this report's task, or None when there is none.
+
+    A run whose collector found no session contributes zero tokens and is left
+    out of `runCount` — counting it would make the average per run look cheaper
+    than the runs that were actually measured.
+    """
+    root = _task_root(data_path)
+    if root is None:
+        return None
+    totals = {name: 0 for name, _ in _SUMMED_KEYS}
+    run_count = 0
+    for state_path in sorted(root.glob(_TEAM_STATE_GLOB)):
+        try:
+            team_state = json.loads(state_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        if not isinstance(team_state, dict):
+            continue
+        blocks = _usage_blocks(team_state)
+        measured = sum(_number(block.get("totalTokens")) for block in blocks)
+        if measured <= 0:
+            continue
+        run_count += 1
+        for name, source_key in _SUMMED_KEYS:
+            totals[name] += sum(_number(block.get(source_key)) for block in blocks)
+    if not run_count:
+        return None
+    return {**totals, "runCount": run_count}

package/runtime/schemas/final-report-v1.0.schema.json

@@ -398,6 +398,9 @@
               ]
             }
           }
+        },
+        "taskCumulative": {
+          "$ref": "#/$defs/TokenUsageTaskCumulative"
         }
       }
     },
@@ -3322,6 +3325,17 @@
             }
           ]
         },
+        "cacheReadTokens": {
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "billableTokens": {
           "oneOf": [
             {
@@ -3399,6 +3413,17 @@
             }
           ]
         },
+        "cacheReadTokens": {
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "billableTokens": {
           "oneOf": [
             {
@@ -3450,6 +3475,17 @@
             }
           ]
         },
+        "cacheReadTokens": {
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "billableTokens": {
           "oneOf": [
             {
@@ -6287,6 +6323,40 @@
           }
         }
       ]
+    },
+    "TokenUsageTaskCumulative": {
+      "type": "object",
+      "description": "Every measured run of this task added up — this report's run plus every earlier one. Written by the Phase 7 token-usage step from the per-run team-states.",
+      "required": [
+        "totalTokens",
+        "cacheReadTokens",
+        "billableTokens",
+        "costUsd",
+        "runCount"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "totalTokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "cacheReadTokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "billableTokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "costUsd": {
+          "type": "number",
+          "minimum": 0
+        },
+        "runCount": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
     }
   }
 }

package/runtime/schemas/final-report-v2.0.schema.json

@@ -368,6 +368,9 @@
               ]
             }
           }
+        },
+        "taskCumulative": {
+          "$ref": "#/$defs/TokenUsageTaskCumulative"
         }
       }
     },
@@ -3435,6 +3438,20 @@
         "deferrable"
       ]
     },
+    "ClarificationOrigin": {
+      "enum": [
+        "worker-finding",
+        "material-gap",
+        "lead-directed"
+      ]
+    },
+    "ClarificationUserConfirmation": {
+      "enum": [
+        "asked-and-answered",
+        "asked-awaiting",
+        "deferred-no-interactive-session"
+      ]
+    },
     "ClarificationOption": {
       "type": "object",
       "required": [
@@ -5380,6 +5397,17 @@
             }
           ]
         },
+        "cacheReadTokens": {
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "billableTokens": {
           "oneOf": [
             {
@@ -5457,6 +5485,17 @@
             }
           ]
         },
+        "cacheReadTokens": {
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "billableTokens": {
           "oneOf": [
             {
@@ -5508,6 +5547,17 @@
             }
           ]
         },
+        "cacheReadTokens": {
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "billableTokens": {
           "oneOf": [
             {
@@ -8249,6 +8299,12 @@
         "userInput": {
           "type": "string"
         },
+        "origin": {
+          "$ref": "#/$defs/ClarificationOrigin"
+        },
+        "userConfirmation": {
+          "$ref": "#/$defs/ClarificationUserConfirmation"
+        },
         "options": {
           "type": "array",
           "minItems": 2,
@@ -8371,6 +8427,40 @@
           }
         }
       ]
+    },
+    "TokenUsageTaskCumulative": {
+      "type": "object",
+      "description": "Every measured run of this task added up — this report's run plus every earlier one. Written by the Phase 7 token-usage step from the per-run team-states.",
+      "required": [
+        "totalTokens",
+        "cacheReadTokens",
+        "billableTokens",
+        "costUsd",
+        "runCount"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "totalTokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "cacheReadTokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "billableTokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "costUsd": {
+          "type": "number",
+          "minimum": 0
+        },
+        "runCount": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
     }
   }
 }

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

@@ -183,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,

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/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/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; }