@staix/agent-hub 0.12.17 → 0.12.18

package/CHANGELOG.md

@@ -4,6 +4,12 @@ Issue and pull request numbers in the entries for 0.7.7 and earlier refer to the
 
 ## Unreleased
 
+## 0.12.18
+
+- Attribute token increments, provider usage and completed turns to task ids by delivery or a single open task; add `ahub report --by task` with task/class totals, explicit unknown counters, unattributed shares and a separate historical bucket. Preserve PII id-only exports and derive no prices (#200).
+- Add semantic colors to console stream headers, footer and panels with `--color=auto|always|never`; keep plain-text Unicode geometry, sanitize incoming controls before the fixed palette, and restore terminal attributes on exit. Tail, logs, JSON and polling remain unchanged (#201).
+- Control protocol stays 15 and events schema stays 1; a running 0.12.17 hub upgrades with the 0.12.18 coordinator.
+
 ## 0.12.17
 
 - Add an operator console with confirmed approvals, bounded status polling and optional peer, approval, task, queue and event panels; open it from interactive `up` and preserve the tail renderer (#190, #191).

package/README.md

@@ -4,7 +4,7 @@ Native multi-agent hub for one developer's machine: Claude Code, Codex, Kimi Cod
 hub-owned local-LLM worker collaborate as peers in independent project directories, with
 task-aware model routing (Switchyard) in front of a self-hosted gateway (OmniRoute).
 
-Status: 0.12.17, control protocol 15. Durable delivery records distinguish queued
+Status: 0.12.18, control protocol 15. Durable delivery records distinguish queued
 work from uncertain execution. The [smoke checklist](docs/smoke.md) records
 verified paths and remaining prerequisites.
 
@@ -28,7 +28,7 @@ cd <your project> && ahub init && ahub up
 Or install the same version from GitHub:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.12.17 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.12.18 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.

package/docs/events.md

@@ -30,9 +30,9 @@ marked `private: true`, and PII tasks `pii: true`.
 | `split` | `task`, `where` (`routing`: routing chose the first owner of a task overlapping another owner's task not started yet, not an escalation, relay or reassignment, the record calibration reads; `cohort`: an overlap formed or changed a cohort), `verdict` (`split`, `single`, `unknown`), `single` (the peer that would finish both units alone soonest), `splitS`, `singleS`, `reason` (for `unknown`), `trace` (the inputs and steps: peer names, their profiles of versions and coordination, and numbers only): a shadow split prediction; it never changes the assignment (issue #109) |
 | `state` | `peer`, `state` |
 | `turn_start` | `peer`, `turn` (`<peer>#<hub run>.<n>`, unique across restarts). A turn follows the adapter: pausing a busy peer does not end it |
-| `turn_end` | `peer`, `turn`, `ms`, `tokens` (when the adapter reported any during the turn), `files` and `snapshotMs` (when snapshots are on: how many files the turn changed, and the time both snapshots took) |
-| `tokens` | `peer`, `n` (tokens added since the previous report) |
-| `usage` | `peer`, `source`, opaque `id`, optional `measuredAt` (provider/source time), requested/served model and provider labels, and any provider-reported input/output/cache/total counters. Missing counters stay unknown. |
+| `turn_end` | `peer`, `turn`, `ms`, `tokens` (when the adapter reported any during the turn), `files` and `snapshotMs` (when snapshots are on: how many files the turn changed, and the time both snapshots took); optional numeric `task`, `attribution` (`delivery`, `single_open`, `unattributed`) frozen at turn start, `pii: true` for an attributed PII task |
+| `tokens` | `peer`, `n` (tokens added since the previous report), optional numeric `task`, `attribution` (`delivery`, `single_open`, `unattributed`), `pii: true` for an attributed PII task |
+| `usage` | `peer`, `source`, opaque `id`, optional `measuredAt` (provider/source time), requested/served model and provider labels, and any provider-reported input/output/cache/total counters; optional numeric `task`, `attribution` (`delivery`, `single_open`, `unattributed`), `pii: true` for an attributed PII task. Missing counters stay unknown. |
 | `task` | `id`, `event` (the board history event, e.g. `proposed`, `assigned`, `done`, `check failed`, `blocked`, `ready`), `by`, `state`, `owner`, `reviewer`, `class`, `pii` |
 | `overlap` | `task`, `owner`, `others` (`task`, `owner`, `paths`, and `symbols` when plans name the same symbol; a name that matches a PII pattern is left out, so either list can be empty), the structured twin of the console notice |
 | `quota` | `peer`, `windows` (`id`, `used`, `resetsAt`), `hard`, `measuredAt` (when the reading was taken, if not when it arrived: Claude's numbers come through a file) |
@@ -50,6 +50,40 @@ Token usage by adapter:
 - `ahub report` deduplicates usage records by peer, source and id. Coverage counts distinguish calls with provider usage from calls where usage was absent. Token counters are provider-reported values; the report never derives a price or treats missing spend as zero. Estimated price and measured provider spend remain unknown unless a future source reports them.
 - Usage telemetry has no prompt, completion, task text, credential, Access header, session id or transcript path.
 
+## Per-task usage reports
+
+`ahub report --by task` (also `--json` and `--since`) reads only `events.jsonl`.
+It reports task ids, the latest recorded class/outcome, completed logical turns,
+and wall time from the first `in_progress` task event to the first `approved`
+event. Wall time is unknown if either boundary is absent or the latest outcome
+is not approved. Each task and class rollup includes per-peer native token
+increments and provider-reported input/output/cache/total counters. Usage is
+deduplicated by peer, source and id; missing counters are `null` in JSON and
+`unknown` in text, with known-record counts alongside measured subsets. A
+missing task history has unknown class/outcome and belongs to the unknown class
+rollup. PII tasks have ids and a `pii: true` flag, never titles. No prices are derived.
+
+At write time, the first applicable attribution rule wins:
+
+- `delivery`: the current turn's original delivery names exactly one distinct positive task id, including work by a peer that does not own it.
+- `single_open`: otherwise the peer owns exactly one `in_progress` task.
+- `unattributed`: otherwise no task is assigned to the record.
+
+`Bus.onDeliver` observes originals immediately before `peer.deliver` starts the
+turn. Pending task identity is consumed at turn start and cleared on delivery
+admission/failure, so later user-started native turns do not inherit it. Usage
+and token events apply the rule at write time; `turn_end` keeps the start-time
+attribution. Local usage uses its request-bound route policy task when present.
+The existing relay has no task-bearing route usage event; this change adds no
+new usage source. Schema version 1 and the control protocol are unchanged.
+
+The unattributed share is always printed for token increments and deduplicated
+usage records, against all recorded increments/usage records. A zero denominator
+has unknown share. Records with no `attribution` field belong to a separate
+`before attribution` bucket displayed beside the share, even if a task field is
+present. Neither bucket is redistributed. `ahub export` preserves these fields
+as raw JSON lines; plain `ahub report` keeps its existing behavior.
+
 The file is local and never uploaded. It grows without rotation; delete it to start
 over (the hub recreates it).
 

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.12.17 and control protocol 15. Live verification
+This guide describes ahub 0.12.18 and control protocol 15. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Operator console and panels
@@ -26,6 +26,43 @@ a reason. Tasks use the same public redaction as the board. Panels need at least
 polling runs only while the corresponding panel is visible. Leaving restores
 the terminal and returning from panels replays the bounded stream buffer.
 
+Console color policy is `--color=auto|always|never`, with `auto` as the default.
+Auto enables color only when both input and output are TTYs, `TERM` is not
+`dumb`, and `NO_COLOR` is empty or absent. Explicit `always` overrides these
+conditions, including redirected stream output; `never` disables styling.
+Neither option changes terminal size requirements, panel decisions, cursor
+management or the final reset. Invalid values fail before connecting.
+
+| Meaning | Palette | Examples |
+|---|---|---|
+| Information and navigation | Cyan, bold cyan for active/selected labels | Tabs, section/peer labels and `>` selection marker |
+| Success and availability | Green | Idle peer, approved task |
+| Waiting and attention | Yellow | Busy/paused peer, pending approval, confirmation, review/ready task, important priority |
+| Failure and intervention | Red | Failed/check-failed task, undeliverable/overflow, `needs_review` queue, denial request or expired/cancelled approval |
+| Metadata | Bright black | Ages and remaining approval time |
+
+Offline peers, primary titles, action details and message body lines keep the
+terminal's default foreground. Labels and prompts remain readable without
+color. Stream styling applies only to the header, using structured event data;
+message text cannot choose a color. A local denial is shown as requested, not
+as a confirmed receipt; a remote answered closure has no option-kind metadata
+and is not guessed to be a denial. A fixed palette is applied after terminal
+control sanitization. Width, clipping, wrapping and cursor placement use plain
+Unicode text. Each styled span and every interactive exit restores attributes.
+Color adds no polling, timers or extra redraws. `ahub tail`, logs and JSON stay
+unchanged.
+
+```sh
+ahub console --panels --color=auto
+NO_COLOR=1 ahub console
+ahub console --color=never
+ahub console --color=always > console-stream.txt
+```
+
+Actual light/dark terminal readability and bounded idle-CPU observations are
+recorded separately in the smoke ledger; fake-terminal tests establish policy,
+geometry, sanitization and restoration only.
+
 The command input accepts existing status, board, task, review, say, pause,
 resume, budget, queue, permit, ask, remember, route, turns, undo, check-path and
 report operations. It executes an argument vector with closed stdin. Lifecycle,
@@ -346,11 +383,16 @@ token counts, never message bodies or task titles.
 ```bash
 ahub report --since 7d          # turns, busy time and tokens per peer, messages, overlaps, task events
 ahub report --since 7d --json   # the same numbers as JSON
+ahub report --by task           # tokens, turns and wall time per task and class, with the unattributed share
 ahub export --since 24h         # the raw events as JSON lines, for your own analysis
 ```
 
 `ahub report` counts the same overlap warnings as `scripts/overlaps.ts`, from the
-structured events instead of log lines.
+structured events instead of log lines. `--by task` uses the task each usage and
+token record was attributed to when it was written: the delivery that started the
+turn, otherwise the peer's only `in_progress` task. Everything else is reported as
+unattributed, and records from before 0.12.18 as a separate bucket; neither is
+redistributed (rules: [events](events.md#per-task-usage-reports)).
 
 ## Turns and undo
 
@@ -744,21 +786,21 @@ Rows without a live process are stale registrations; forget them with
 
 Upgrade running projects with the target release's own coordinator. It accepts
 a running source on control protocol 9 (0.6.x), 10 (0.7.0 through 0.12.0),
-11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15) 14 (0.12.16) or 15 (0.12.17), and only
+11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15) 14 (0.12.16) or 15 (0.12.17 and 0.12.18), and only
 a target on its own protocol, so the target's coordinator fits every supported
 source and carries every recovery fix released up to it. Protocol 8 and older
 (0.5.x and earlier) are refused as `manual-bootstrap-required`. Run from the
 project directory, without replacing the global CLI first:
 
 ```bash
-bunx --package @staix/agent-hub@0.12.17 ahub upgrade --to 0.12.17 --dry-run
-bunx --package @staix/agent-hub@0.12.17 ahub upgrade --to 0.12.17 --yes
+bunx --package @staix/agent-hub@0.12.18 ahub upgrade --to 0.12.18 --dry-run
+bunx --package @staix/agent-hub@0.12.18 ahub upgrade --to 0.12.18 --yes
 ```
 
 | Running now | Coordinator to use |
 | --- | --- |
 | 0.6.x (protocol 9) | the target's, through `bunx` as above |
-| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 (protocol 15) | the target's, through `bunx` as above |
+| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 and 0.12.18 (protocol 15) | the target's, through `bunx` as above |
 | any supported source, with the installed CLI already at the target | `ahub upgrade` below, which is the same coordinator |
 | 0.5.x or earlier (protocol 8 and older) | not supported: bootstrap by hand with the matching CLI |
 
@@ -790,14 +832,14 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.17 --dry-run
+ahub upgrade --to 0.12.18 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.17 --yes
+ahub upgrade --to 0.12.18 --yes
 ahub recovery status <operation-id>
 ahub recovery resume <operation-id>
 ahub recovery abort <operation-id>

package/docs/quickstart.md

@@ -17,7 +17,7 @@ ahub setup                                # installs the Claude Code channel plu
 Or use the matching GitHub release:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.12.17
+bun add -g github:STAIxBWLB/agent-hub#v0.12.18
 ahub setup
 ```
 

package/docs/security.md

@@ -8,7 +8,7 @@ agent-hub connects agents that can each run commands. This page says what the hu
 - **The control link is loopback plus a secret.** The daemon and the Codex proxy bind 127.0.0.1 only. The control WebSocket requires a per-run token (`.agenthub/state/control-token`, mode 600), and both servers refuse any request that carries an `Origin` header: any web page can open a WebSocket to localhost, and browsers always send `Origin`. External clients cannot claim the console user's id or a hub-managed peer's id.
 - **Permission prompts stay on.** `ahub claude` and `ahub codex` add nothing that weakens the agents' own prompts. Kimi's and `local`'s permission requests are relayed to the console and cancelled after `approvals.timeout_s` (default 120 s) of silence; the macOS notification for a waiting request carries the peer and the tool name only. The one exception is the hub's own tools (`hub_send` and the task tools, matched by exact name): Kimi's requests for them are approved once without a prompt and logged by name, the same trust Codex gets through `approval_mode` in the hub's config. They invoke hub-owned operations rather than arbitrary file or shell tools, and every call passes the hub's own checks. Identity comes from the exact permission title, or from the earlier tool-call title bound to the same call id and resolved against the configured MCP servers when the permission title contains argument JSON (Qwen). Payload text and unrelated display titles never establish identity. A payload longer than the console shows is marked as cut and never offers a session-wide grant. `--unattended` turns prompts off, says so loudly, and is never the default.
 - **A committed config cannot choose launch commands, credential files, data endpoints or a wider sandbox.** The machine-local fields (`kimi_cmd`, `codex_bin`, `pi.cmd`, `checks`, `mlx.bin`, `mlx.runtimeDir`, `mlx.modelPath`, `omniroute.urls`, `omniroute.access_hosts`, the `omniroute` key files, `memory.worker_url`, `local.read_allow`, `local.bash_network`, `local.network_allow`) apply only from a config file git confirms nobody committed: `.agenthub/config.json` or `.agenthub/config.local.json`, matched by file identity so no other spelling the file system accepts slips past, and `.agenthub` itself not a committed symlink or submodule. Without a repository, or when git fails, they keep their defaults; an empty value always means the default. "Untracked" is answered by the repository that contains the project: a checkout copied or extracted into an unrelated repository, or into an ignored directory of one, is trusted like your own files. So a cloned repository cannot choose a launch command, a completion check, a gateway to send a key file to, a memory endpoint, or a wider sandbox. A command in `checks` runs as you, outside the local worker's sandbox, like a git hook. Nothing in `routing.toml` or in task text is ever run. `routing.toml` and the other shared fields still come from the checkout, and they matter: `routing.toml` picks the models the local worker and the hub's inference use at your gateway and can turn the PII constraint off, and roles and budget shape who does what. Review them in a repository you do not trust.
-- **Telemetry holds no bodies.** `.agenthub/state/events.jsonl` (issue #40) records envelope ids, routing and sizes, task ids and states, overlapping paths and token counts. It never records a message body, a task title or detail, and marks private (PII) envelopes and tasks as such. It stays on the machine; `ahub export` only prints it.
+- **Telemetry holds no bodies.** `.agenthub/state/events.jsonl` (issue #40) records envelope ids, routing and sizes, task ids and states, overlapping paths and token counts, and the task id (with a PII flag) that each usage and token record is attributed to. It never records a message body, a task title or detail, and marks private (PII) envelopes and tasks as such. It stays on the machine; `ahub export` only prints it.
 - **Snapshots stay in your repository.** Per-turn snapshots (issue #33) are git objects in the project's own object store, written through a temporary index; nothing is referenced, pushed or copied elsewhere, and `git gc` prunes them. They hold what the work tree held, including untracked files that are not ignored, so keep secrets in ignored files. They carry the repository's own permissions, and nothing caps their disk use but `git gc`. A turn of a peer holding an open PII task is not snapshotted; a PII file left in the project is snapshotted by later turns like any other file. `ahub undo` restores only files whose current content is exactly what the turn left.
 - **The edit hook reads, never decides.** `ahub check-path --hook` (issue #32) reads hub.db and returns context for Claude and a line for you; it sets no permission decision, so your permission rules stay in charge. It names other owners' task ids, titles and states, which then reach Claude's model; PII tasks are left out.
 - **The session record holds identities only.** `.agenthub/state/sessions.json` (issue #37, mode 600) keeps each attached peer's recovery metadata: launch options, session and thread ids, Pi's session file path. No message or task text; loss notices name deliveries by id, sender and public task title.
@@ -38,7 +38,10 @@ capability. Conflicting or malformed markers fail closed. There is no `--as-user
 Human-only operations are refused before connecting, including permission answers,
 queue resolution, budget overrides, lifecycle and recovery operations, and `ask`.
 The operator uses a plain terminal or `ahub console`. A Claude `!` command that
-inherits the agent markers follows the same rule.
+inherits the agent markers follows the same rule. The console strips control
+sequences from agent and daemon text before it quotes forged headers, and its
+colors come only from a fixed palette applied afterwards, so message text cannot
+set styles or operate the terminal.
 
 This is an honest default against accidental impersonation and injected commands.
 It does not make the token inaccessible to an agent with unrestricted project

package/docs/specs/2026-09-19-agent-hub-design.md

@@ -1360,6 +1360,30 @@ approval. Deny is direct. Pending requests include expiry and are withdrawn by
 Panels expose Peers, Approvals, Tasks, Queue and Events with bounded polling and
 Unicode cell widths, fall back below 80x24, and restore terminal state on exit.
 
+Console semantic colors (issue #201) use spans with a fixed terminal-native
+palette: cyan information, bold cyan active/selected labels, green availability
+and success, yellow attention/waiting, red failure/intervention, and restrained
+bright-black metadata. Offline peers, ordinary titles, action details and body
+lines use the default foreground. Existing labels, selection markers and
+confirmation prompts remain sufficient without color. Stream headers use event
+structure for their tone; body text is never parsed for meaning or passed
+through as terminal styling. Denial requests and observed expiry/cancellation
+are red; an answered remote closure lacks option-kind metadata and is not
+guessed to be a denial.
+
+`--color=auto|always|never` affects styling only. Auto requires terminal input
+and output, a non-dumb TERM, and absent/empty NO_COLOR. Always overrides those
+checks even for redirected stream output, without enabling panels or raw mode;
+never disables styling. Invalid values fail with usage text before connection.
+Plain `renderConsole` remains available, while `renderConsoleLines` exposes
+semantic spans. Geometry is computed from sanitized plain Unicode text before
+painting. `paint` sanitizes every span, inserts only fixed palette SGR sequences
+and resets each styled span. Interactive exits, signals, disconnect and errors
+retain the console restoration sequence. No new dependencies, protocol changes,
+polling or redraw triggers are added. Tail, logs and machine-readable output
+remain unchanged. Native light/dark readability and idle-CPU observations are
+separate smoke evidence, not inferred from fake-terminal tests.
+
 Agent shell CLI calls connect as the detected peer in tools mode. Hub launches
 set `AGENTHUB_PEER_ID`; the pinned installed Codex shell injects
 `CODEX_THREAD_ID` after environment filtering, and Claude uses `CLAUDECODE`.
@@ -1465,3 +1489,35 @@ provider/configuration change, account retry or authority relaxation. Once quota
 is available under an authorized account, the same isolated read-only status-tool
 and ordinary-role refusal probe must record a native tool event and daemon result
 before this Kimi prerequisite can be marked verified.
+
+## Amendment: per-task usage attribution (issue #200)
+
+Task usage is attributed by a rule at write time, never by a proportional guess:
+
+- A turn whose original delivery names exactly one distinct positive `refs.task` uses that id and `attribution: "delivery"`, even when the peer does not own the task. Two distinct delivery task ids fall through to the next rule.
+- Otherwise a peer with exactly one owned `in_progress` task uses that id and `attribution: "single_open"`.
+- Otherwise the record carries `attribution: "unattributed"` and no task id.
+
+The bus calls `onDeliver(peer, originals)` immediately before `peer.deliver`,
+after retaining the original delivery. The daemon consumes pending delivery
+identity during the synchronous busy/turn-start transition and clears it on
+delivery admission/failure. A user-started native turn cannot inherit an older
+delivery. Tokens and usage use the rule at write time; turn ends preserve the
+start-time attribution. Local worker usage carries its request-bound route
+policy task when one exists. Relay usage would use a route decision's task when
+present; the current daemon has no such relay usage writer, so collection is
+unchanged. Attributed PII records carry only a task id and `pii: true`.
+
+`ahub report --by task` and `--by task --json` use only events, never the board or
+task text. They report latest task class/outcome, attributed turn ends, first
+accept-to-first-approval wall time (unknown while not approved or without both
+boundaries), per-peer token increments and provider counters, and class rollups.
+Usage deduplication uses peer/source/id. Missing counters stay unknown, distinct
+from reported zero, and known-record counts identify measured subsets.
+
+Unattributed token and usage-record shares always appear. Older records without
+`attribution` stay in a distinct `before attribution` bucket, never redistributed
+to a task; both buckets appear even when empty. A zero denominator has unknown
+share. Export carries the new fields without task text. No prices or savings
+counterfactuals are derived. These additive fields retain events schema 1 and
+the existing control protocol. Plain `ahub report` remains unchanged.

package/docs/verified.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "documents": {
     "README.md": {
-      "verifiedAgainst": "c3d1e22f9b200cbe3f484c9e73d30bad046c9221",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "package.json",
         "src/",
@@ -11,14 +11,14 @@
       ]
     },
     "docs/security.md": {
-      "verifiedAgainst": "c3d1e22f9b200cbe3f484c9e73d30bad046c9221",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/",
         "templates/"
       ]
     },
     "docs/operations.md": {
-      "verifiedAgainst": "c3d1e22f9b200cbe3f484c9e73d30bad046c9221",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "package.json",
         "src/",
@@ -35,7 +35,7 @@
       ]
     },
     "docs/quickstart.md": {
-      "verifiedAgainst": "c3d1e22f9b200cbe3f484c9e73d30bad046c9221",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "package.json",
         "src/",
@@ -43,7 +43,7 @@
       ]
     },
     "docs/agent-notes/adapters.md": {
-      "verifiedAgainst": "20ad5e68fd1264fa43dd7426f60cb0c8211d6555",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/adapters/",
         "src/pi/",
@@ -68,7 +68,7 @@
       ]
     },
     "docs/agent-notes/budget.md": {
-      "verifiedAgainst": "20ad5e68fd1264fa43dd7426f60cb0c8211d6555",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/hub/budget.ts",
         "src/cli/statusline-tee.ts",
@@ -80,7 +80,7 @@
       ]
     },
     "docs/agent-notes/bus.md": {
-      "verifiedAgainst": "20ad5e68fd1264fa43dd7426f60cb0c8211d6555",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/hub/bus.ts",
         "src/hub/envelope.ts",
@@ -92,7 +92,7 @@
       ]
     },
     "docs/agent-notes/daemon.md": {
-      "verifiedAgainst": "20ad5e68fd1264fa43dd7426f60cb0c8211d6555",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/hub/daemon.ts",
         "src/hub/control-client.ts",
@@ -118,7 +118,7 @@
       ]
     },
     "docs/agent-notes/local-worker.md": {
-      "verifiedAgainst": "8b7d7254f1bb5602ec5d658e7814e236f8fb43e7",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/adapters/local-worker.ts",
         "src/local/",
@@ -136,7 +136,7 @@
       ]
     },
     "docs/agent-notes/tasks.md": {
-      "verifiedAgainst": "c3d1e22f9b200cbe3f484c9e73d30bad046c9221",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/hub/tasks.ts",
         "src/hub/board.ts",
@@ -151,7 +151,7 @@
       ]
     },
     "docs/agent-notes/tests.md": {
-      "verifiedAgainst": "2a274289e280252b264716da3a1112f67b0c278e",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "test/",
         "scripts/check.sh",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.12.17",
+  "version": "0.12.18",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   "license": "MIT",
   "type": "module",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.12.17",
+  "version": "0.12.18",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",

package/plugins/agent-hub/server.js

@@ -15403,7 +15403,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.12.17",
+  version: "0.12.18",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",

package/src/adapters/local-worker.ts

@@ -35,7 +35,7 @@ export interface LocalOptions {
   /** Runs a hub task tool (hub_task_*, hub_review, hub_remember) as this peer. Absent = the tools are not offered. */
   taskTool?: (name: string, args: Record<string, unknown>, turn: { pii: boolean }) => Promise<string>;
   /** Successful provider responses only; usage may be absent when the gateway omits it. Never includes prompt data. */
-  onUsage?: (record: { id: string; at: string; usage?: ChatResult["usage"]; requestedModel: string; servedModel?: string; provider?: string }) => void;
+  onUsage?: (record: { id: string; at: string; usage?: ChatResult["usage"]; requestedModel: string; servedModel?: string; provider?: string; task?: number }) => void;
   /** Atomic task/run admission immediately before every model request or tool execution. */
   admitBudget?: (envs: Envelope[], unit: "model_calls" | "tool_calls") => Promise<ExecutionBudgetDecision[]>;
   /** Per-turn policy from the task the delivery carries: the class's route, and whether it is a PII task. */
@@ -76,6 +76,7 @@ export class LocalPeer extends BasePeer {
   private readonly routes: HubRouteRuntime;
   private routeEnvs: Envelope[] = [];
   private routePii = false;
+  private routeTask?: number;
   private labelTurnId?: string;
   private turn = 0; // generation guard, as in acp.ts: a turn aborted by the watchdog must not touch the next one
   private abort: AbortController | undefined;
@@ -94,13 +95,13 @@ export class LocalPeer extends BasePeer {
     this.routes = new HubRouteRuntime({
       execute: async (model, messages, judge, signal, maxTokens) => {
         if (signal.aborted) throw new Error("turn cancelled before model request");
-        const envs = this.routeEnvs, pii = this.routePii, generation = this.turn;
+        const envs = this.routeEnvs, pii = this.routePii, generation = this.turn, task = this.routeTask;
         await this.requireBudget(envs, "model_calls");
         if (generation !== this.turn) throw new Error("route belongs to an ended turn");
         if (signal.aborted) throw new Error("turn cancelled before model request");
         const tools = judge ? undefined : [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...TASK_TOOLS, ...CONDUCTOR_TOOLS].map(asFunction) : [])];
         const result = await this.opts.omni.chat({ model, messages, ...(tools ? { tools } : {}), ...(judge ? { max_tokens: maxTokens ?? 2048 } : {}) }, { signal, ...(pii ? { onCampusOnly: true } : {}) });
-        this.recordUsage(result, model);
+        this.recordUsage(result, model, task);
         if (generation !== this.turn) throw new Error("route belongs to an ended turn");
         this.lastServedBy = `hub ${model} (provider ${result.provider ?? "?"})`;
         return result;
@@ -329,11 +330,12 @@ export class LocalPeer extends BasePeer {
   }
 
   /** L2 when the sidecar is up, otherwise (or when a call through it fails) the fixed model on L3. */
-  private async call(turnMsgs: ChatMessage[], policy: { route?: string; fixedModel?: string; pii?: boolean } | undefined, envs: Envelope[]): Promise<ChatResult> {
+  private async call(turnMsgs: ChatMessage[], policy: { route?: string; fixedModel?: string; pii?: boolean; task?: string } | undefined, envs: Envelope[]): Promise<ChatResult> {
     const { omni, sidecar } = this.opts;
     // A task turn asks for its class's route; a route needs the sidecar, which exists only when the worker was started with one.
     const route = policy?.route ?? this.opts.route;
     const fixedModel = policy?.fixedModel ?? this.opts.fixedModel;
+    const task = policy?.task === undefined ? undefined : Number(policy.task);
     const tools = [...TOOL_SCHEMAS, ...(this.opts.taskTool ? [...TASK_TOOLS, ...CONDUCTOR_TOOLS].map(asFunction) : [])];
     const signal = this.abort!.signal;
     const messages: ChatMessage[] = [{ role: "system", content: system(this.opts.cwd, this.opts.preamble) }, ...this.history, ...turnMsgs];
@@ -345,7 +347,7 @@ export class LocalPeer extends BasePeer {
       try {
         const res = await omni.chat({ model: route!, messages, tools }, { via, sessionId: this.sessionId, signal });
         this.lastServedBy = `switchyard ${route} -> ${res.selectedModel ?? "?"}`;
-        this.recordUsage(res, route!);
+        this.recordUsage(res, route!, task);
         return res;
       } catch (e) {
         if (signal.aborted) throw e;
@@ -355,7 +357,7 @@ export class LocalPeer extends BasePeer {
     await this.requireBudget(envs, "model_calls");
     const res = await omni.chat({ model: fixedModel, messages, tools }, { signal, ...(policy?.pii ? { onCampusOnly: true } : {}) });
     this.lastServedBy = `omniroute ${fixedModel} (provider ${res.provider ?? "?"})`;
-    this.recordUsage(res, fixedModel);
+    this.recordUsage(res, fixedModel, task);
     return res;
   }
 
@@ -364,6 +366,7 @@ export class LocalPeer extends BasePeer {
     try { id = this.opts.turnId?.(); } catch { /* optional host metadata */ }
     id ??= `${this.id}#${this.sessionId}.${generation}`;
     const number = task ? Number(task) : undefined;
+    this.routeTask = Number.isSafeInteger(number) && number! > 0 ? number : undefined;
     this.labelTurnId = id;
     this.routes.beginTurn({ turn: id, pii, ...(Number.isSafeInteger(number) && number! > 0 ? { task: number } : {}) });
     return id;
@@ -418,13 +421,14 @@ export class LocalPeer extends BasePeer {
     } catch { /* optional research observations */ }
   }
 
-  private recordUsage(res: ChatResult, requestedModel: string): void {
+  private recordUsage(res: ChatResult, requestedModel: string, task?: number): void {
     try {
       this.opts.onUsage?.({
         id: randomUUID(),
         at: new Date().toISOString(),
         ...(res.usage ? { usage: res.usage } : {}),
         requestedModel: safeModelLabel(requestedModel) ?? "unknown",
+        ...(Number.isSafeInteger(task) && task! > 0 ? { task } : {}),
         ...(safeModelLabel(res.servedModel ?? res.selectedModel) ? { servedModel: safeModelLabel(res.servedModel ?? res.selectedModel)! } : {}),
         ...(safeModelLabel(res.provider) ? { provider: safeModelLabel(res.provider)! } : {}),
       });

package/src/cli/console-state.ts

@@ -4,7 +4,7 @@ export interface Approval {
   id: string; peer: string; title: string; expiresAt: number;
   options: { optionId: string; name: string; kind: string }[];
 }
-export interface ConsoleEvent { text: string; peer?: string; kind?: string }
+export interface ConsoleEvent { text: string; peer?: string; kind?: string; tone?: Tone }
 export interface ConsoleState {
   mode: "stream" | "panels"; panel: number; selection: number; approvalIndex: number;
   input: string; editing: boolean; history: string[]; historyIndex: number;
@@ -22,11 +22,48 @@ export function initialConsoleState(panels = false): ConsoleState {
 }
 /** Strip terminal controls before any daemon or child output reaches a terminal. Preserve printable Unicode. */
 export function terminalText(value: unknown): string {
-  return sanitize(String(value ?? ""))
+  return sanitize(String(value ?? "")
     .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\|$)/g, "")
     .replace(/\x1b[P_X^][\s\S]*?(?:\x1b\\|$)/g, "")
     .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
-    .replace(/\x1b[^\n]?/g, "").replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, "");
+    .replace(/\x1b[^\n]?/g, "").replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, ""));
+}
+export type Tone = "info" | "strong" | "success" | "attention" | "failure" | "muted";
+export interface Span { text: string; tone?: Tone }
+export const PALETTE: Readonly<Record<Tone, string>> = Object.freeze({
+  info: "\x1b[36m", strong: "\x1b[1;36m", success: "\x1b[32m", attention: "\x1b[33m", failure: "\x1b[31m", muted: "\x1b[90m",
+});
+export function paint(line: Span[], color: boolean): string {
+  return line.map(span => {
+    const text = terminalText(span.text);
+    const sgr = span.tone && Object.hasOwn(PALETTE, span.tone) ? PALETTE[span.tone] : undefined;
+    return color && sgr && text ? sgr + text + "\x1b[0m" : text;
+  }).join("");
+}
+export function resolveColor(flag: string | undefined, env: { isTTY: boolean; TERM?: string; NO_COLOR?: string }): boolean | Error {
+  if (flag === "always") return true;
+  if (flag === "never") return false;
+  if (flag === undefined || flag === "auto") return env.isTTY && env.TERM !== "dumb" && !env.NO_COLOR;
+  return new Error("usage: ahub console [--panels] [--color=auto|always|never]");
+}
+export function stateTone(state: string): Tone | undefined {
+  if (state === "idle" || state === "approved") return "success";
+  if (["busy", "paused", "in_review", "changes_requested", "ready"].includes(state)) return "attention";
+  if (["failed", "check failed", "needs_review"].includes(state)) return "failure";
+  return undefined;
+}
+const span = (text: unknown, tone?: Tone): Span => ({ text: String(text ?? ""), ...(tone ? { tone } : {}) });
+/** Clip only sanitized plain text, then retain the tones of the surviving prefix. */
+function fitLine(line: Span[], columns: number): Span[] {
+  const clean = line.map(s => ({ ...s, text: terminalText(s.text).replace(/\n/g, " ") }));
+  const text = clean.map(s => s.text).join("");
+  const clipped = fit(text, columns);
+  const marker = text === clipped ? "" : ".".repeat(Math.max(0, Math.min(3, columns)));
+  let remaining = clipped.length - marker.length;
+  const out: Span[] = [];
+  for (const s of clean) { const part = s.text.slice(0, Math.max(0, remaining)); if (part) out.push({ ...s, text: part }); remaining -= part.length; }
+  if (marker) out.push(span(marker));
+  return out;
 }
 export function fit(value: unknown, columns: number): string {
   const text = terminalText(value).replace(/\n/g, " ");
@@ -179,35 +216,64 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
   return done();
 }
 export function renderConsole(s: ConsoleState, columns: number, rows = 24, now = Date.now()): string[] {
+  return renderConsoleLines(s, columns, rows, now).map(line => paint(line, false));
+}
+export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24, now = Date.now()): Span[][] {
   const permission = s.approvals[s.approvalIndex];
   let prompt = s.editing ? `: ${s.input}` : "q quit | Tab panels | : command | a allow d deny v view [ ] select";
   if (s.confirm?.type === "permission") prompt = `allow ${s.confirm.option} for ${s.confirm.peer} (request ${s.confirm.id})? y/N`;
   if (s.confirm?.type === "command") prompt = `${s.confirm.args.join(" ")}? y/N`;
   if (s.optionChoice) prompt = s.approvals.find(a => a.id === s.optionChoice)?.options.filter(o => o.kind.startsWith("allow")).map((o, i) => `${i + 1}:${o.name}`).join(" | ") ?? "";
+  const summary: Span[] = [];
+  for (const [id, p] of Object.entries(s.peers)) {
+    if (summary.length) summary.push(span(" "));
+    summary.push(span(id, p.state === "offline" ? undefined : "info"), span(":"), span(p.state, stateTone(p.state)), span(` q${p.queued ?? 0}`));
+    if (p.needsReview) summary.push(span(` review${p.needsReview}`, "failure"));
+    if (p.paused) summary.push(span(" paused", "attention"));
+  }
   const quotas = Object.entries(s.budget).map(([id, b]) => `${id}:${b.windows?.map((w: any) => `${w.id} ${Math.round(w.used * 100)}%`).join("/") ?? "?"}`).join(" ");
-  const summary = Object.entries(s.peers).map(([id, p]) => `${id}:${p.state} q${p.queued ?? 0}${p.needsReview ? ` review${p.needsReview}` : ""}${p.paused ? " paused" : ""}`).join(" ");
-  const footer = [fit(summary + (quotas ? ` | ${quotas}` : ""), columns), fit(`${s.approvals.length} approvals${permission ? ` | ${permission.peer} ${permission.id} ${Math.max(0, Math.ceil((permission.expiresAt - now) / 1000))}s` : ""}${s.notice ? ` | ${s.notice}` : ""}`, columns), fit(prompt, columns)];
+  if (quotas) summary.push(span(` | ${quotas}`));
+  const approvals = [span(`${s.approvals.length} approvals`, s.approvals.length ? "attention" : undefined)];
+  if (permission) approvals.push(span(` | ${permission.peer} ${permission.id}`, "attention"), span(` ${Math.max(0, Math.ceil((permission.expiresAt - now) / 1000))}s`, "muted"));
+  if (s.notice) approvals.push(span(` | ${s.notice}`));
+  const footer = [fitLine(summary, columns), fitLine(approvals, columns), fitLine([span(prompt, s.confirm || s.optionChoice ? "attention" : undefined)], columns)];
   if (s.mode === "stream") return footer;
-  const title = ["Peers", "Approvals", "Tasks", "Queue", "Events"][s.panel - 1];
-  const lines = [fit(`agent-hub | 1 Peers 2 Approvals 3 Tasks 4 Queue 5 Events | ${title}`, columns), fit(`j/k move Enter detail Esc back ? keys${s.panel === 5 ? ` | f peer:${s.peerFilter ?? "all"} g kind:${s.kindFilter ?? "all"}` : ""}`, columns)];
-  if (s.help) lines.push(...wrap("Tab stream/panels; 1-5 panel; j/k or arrows move; Enter detail; Esc back; : command; q quit. Approvals: a allow (confirm y), d deny, v title, [ ] select. Peers: p pause, r resume. Tasks: a assign (confirm y), r review. Queue: r resolve (reason and confirm y). Events: f peer filter, g kind filter.", columns));
-  else if (s.detail) { const detail = wrap(s.detail, columns); lines.push(...detail.slice(Math.min(s.detailOffset, Math.max(0, detail.length - (rows - 5))))); }
+  const titles = ["Peers", "Approvals", "Tasks", "Queue", "Events"];
+  const title = titles[s.panel - 1];
+  const tabs = [span("agent-hub | ", "info")];
+  for (const [i, name] of titles.entries()) tabs.push(span(`${i + 1} ${name}${i < 4 ? " " : ""}`, i + 1 === s.panel ? "strong" : "info"));
+  tabs.push(span(` | ${title}`, "strong"));
+  const lines: Span[][] = [fitLine(tabs, columns), fitLine([span(`j/k move Enter detail Esc back ? keys${s.panel === 5 ? ` | f peer:${s.peerFilter ?? "all"} g kind:${s.kindFilter ?? "all"}` : ""}`)], columns)];
+  if (s.help) lines.push(...wrap("Tab stream/panels; 1-5 panel; j/k or arrows move; Enter detail; Esc back; : command; q quit. Approvals: a allow (confirm y), d deny, v title, [ ] select. Peers: p pause, r resume. Tasks: a assign (confirm y), r review. Queue: r resolve (reason and confirm y). Events: f peer filter, g kind filter.", columns).map(text => [span(text)]));
+  else if (s.detail) { const detail = wrap(s.detail, columns); lines.push(...detail.slice(Math.min(s.detailOffset, Math.max(0, detail.length - (rows - 5)))).map(text => [span(text)])); }
   else {
     const data = panelRows(s); const capacity = Math.max(1, s.panel === 2 ? Math.floor((rows - 6) / 2) : rows - 6); const start = Math.max(0, s.selection - capacity + 1);
     for (const [i, row] of data.slice(start, start + capacity).entries()) {
-      let text = "";
+      const selected = start + i === s.selection;
+      const line = [span(`${selected ? ">" : " "} `, selected ? "strong" : undefined)];
       if (s.panel === 1) {
         const b = s.budget[row.id];
-        text = `${row.id} ${row.state} ${row.attached === false ? "detached" : "attached"} q:${row.queued ?? 0} !:${row.queuedImportant ?? 0} review:${row.needsReview ?? 0} ${row.paused ? `paused:${JSON.stringify(row.paused)}` : ""} ${b?.paused ? `budget pause ${b.paused.reason} reset:${b.paused.resetsAt}` : ""} ${b?.windows?.map((w: any) => `${w.id}:${Math.round(w.used * 100)}% reset:${w.resetsAt ?? "?"}`).join(" ") ?? "quota:?"} model:${row.servedBy ?? row.requestedModel ?? "?"}`;
-      } else if (s.panel === 2) text = `${row.id} ${row.peer} ${Math.max(0, Math.ceil((row.expiresAt - now) / 1000))}s ${row.title}`;
-      else if (s.panel === 3) { const at = row.history?.at(-1)?.at ?? row.updated ?? row.created; text = `#${row.id} ${row.state}${row.ready ? " ready" : ""} ${row.owner ?? "-"} review:${row.reviewer ?? "-"} ${row.class} age:${at ? Math.max(0, Math.floor((now - at) / 1000)) + "s" : "?"} ${row.title}`; }
-      else if (s.panel === 4) text = `${row.id} ${row.peer} ${row.state} rev:${row.revision} age:${row.createdAt ? Math.max(0, Math.floor((now - row.createdAt) / 1000)) + "s" : "?"}`;
-      else text = row.text;
-      lines.push(fit(`${start + i === s.selection ? ">" : " "} ${text}`, columns));
+        line.push(span(row.id, row.state === "offline" ? undefined : selected ? "strong" : "info"), span(" "), span(row.state, stateTone(row.state)),
+          span(` ${row.attached === false ? "detached" : "attached"} q:${row.queued ?? 0} `), span(`!:${row.queuedImportant ?? 0}`, row.queuedImportant ? "attention" : undefined),
+          span(` review:${row.needsReview ?? 0}`, row.needsReview ? "failure" : undefined), span(" "),
+          span(row.paused ? `paused:${JSON.stringify(row.paused)}` : "", "attention"), span(" "),
+          span(b?.paused ? `budget pause ${b.paused.reason} reset:${b.paused.resetsAt}` : "", "attention"), span(" "),
+          span(b?.windows?.map((w: any) => `${w.id}:${Math.round(w.used * 100)}% reset:${w.resetsAt ?? "?"}`).join(" ") ?? "quota:?"), span(` model:${row.servedBy ?? row.requestedModel ?? "?"}`));
+      } else if (s.panel === 2) line.push(span(`${row.id} ${row.peer}`, "attention"), span(` ${Math.max(0, Math.ceil((row.expiresAt - now) / 1000))}s`, "muted"), span(` ${row.title}`));
+      else if (s.panel === 3) {
+        const last = row.history?.at(-1);
+        const at = last?.at ?? row.updated ?? row.created;
+        const tone = last?.event === "check failed" || last?.event === "failed" ? "failure" : stateTone(row.state);
+        const failure = (last?.event === "check failed" || last?.event === "failed") && row.state !== last.event ? ` ${last.event}` : "";
+        line.push(span(`#${row.id}`, selected ? "strong" : "info"), span(" "), span(row.state, tone), span(failure, "failure"), span(row.ready ? " ready" : "", "attention"),
+          span(` ${row.owner ?? "-"} review:${row.reviewer ?? "-"} ${row.class} `), span(`age:${at ? Math.max(0, Math.floor((now - at) / 1000)) + "s" : "?"}`, "muted"), span(` ${row.title}`));
+      } else if (s.panel === 4) line.push(span(row.id, selected ? "strong" : "info"), span(` ${row.peer} `), span(row.state, stateTone(row.state)), span(` rev:${row.revision} `), span(`age:${row.createdAt ? Math.max(0, Math.floor((now - row.createdAt) / 1000)) + "s" : "?"}`, "muted"));
+      else { const [header, ...body] = String(row.text).split("\n"); line.push(span(header, row.tone)); if (body.length) line.push(span("\n" + body.join("\n"))); }
+      lines.push(fitLine(line, columns));
     }
-    if (!data.length) lines.push("(empty)");
-    if (s.panel === 2 && permission) lines.push(...wrap(permission.title, columns).slice(0, Math.max(0, rows - 3 - lines.length)));
+    if (!data.length) lines.push([span("(empty)")]);
+    if (s.panel === 2 && permission) lines.push(...wrap(permission.title, columns).slice(0, Math.max(0, rows - 3 - lines.length)).map(text => [span(text)]));
   }
-  const body = lines.slice(0, rows - 3); while (body.length < rows - 3) body.push("");
+  const body = lines.slice(0, rows - 3); while (body.length < rows - 3) body.push([]);
   return [...body, ...footer];
 }

package/src/cli/console.ts

@@ -3,8 +3,9 @@ import { StringDecoder } from "node:string_decoder";
 import type { ControlClient } from "../hub/control-client.ts";
 import { contextLine } from "./status-lines.ts";
 import { renderTailEvent } from "./tail-render.ts";
-import { initialConsoleState, pruneApprovals, reduceConsole, renderConsole, terminalText, wrap } from "./console-state.ts";
-import type { ConsoleEffect, ConsoleEvent } from "./console-state.ts";
+import { initialConsoleState, paint, pruneApprovals, reduceConsole, renderConsoleLines, resolveColor, stateTone, terminalText, wrap } from "./console-state.ts";
+import type { ConsoleEffect, ConsoleEvent, Tone } from "./console-state.ts";
+import type { BusEvent } from "../hub/bus.ts";
 
 export interface ConsoleTerminal {
   columns: number; rows: number; isTTY: boolean; isRaw?: boolean;
@@ -19,11 +20,23 @@ export interface ConsoleOptions {
   client: Pick<ControlClient, "request" | "send" | "close" | "onPush" | "onClose">;
   cwd: string; stateDir: string; panels?: boolean; columns?: number; rows?: number;
   terminal?: ConsoleTerminal;
+  color?: boolean;
   /** Injected command runner must use argv, closed stdin, and return a cancellation handle. */
   runCommand?: (args: string[], output: (text: string) => void, done: () => void) => (() => void);
   pollMs?: number;
 }
 export const RESTORE_CONSOLE = "\x1b[?1049l\x1b[r\x1b[0m\x1b[?25h";
+/** Console-only styling uses event structure; tail text and message bodies are never parsed for meaning. */
+export function eventTone(e: BusEvent): Tone | undefined {
+  if (e.t === "state") return stateTone(e.state);
+  if (e.t === "undeliverable" || e.t === "overflow") return "failure";
+  if (e.t === "envelope") {
+    if (e.dropped === "hop") return "failure";
+    if (e.env.priority === "important" || e.env.kind === "task" || e.env.kind === "review" || e.env.kind === "budget") return "attention";
+    return "info";
+  }
+  return undefined;
+}
 function nativeTerminal(): ConsoleTerminal {
   return {
     get columns() { return process.stdout.columns ?? 80; }, get rows() { return process.stdout.rows ?? 24; },
@@ -46,6 +59,7 @@ function nativeTerminal(): ConsoleTerminal {
 /** One terminal client, no daemon ownership. All text crosses terminalText before writing. */
 export async function runConsole(options: ConsoleOptions): Promise<void> {
   const { client } = options; const terminal = options.terminal ?? nativeTerminal();
+  const color = options.color ?? resolveColor(undefined, { isTTY: terminal.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR }) === true;
   let state = initialConsoleState(!!options.panels);
   let columns = options.columns ?? terminal.columns; let rows = options.rows ?? terminal.rows;
   let active = true; let inAlternate = false; let plain = !terminal.isTTY || columns < 80 || rows < 24;
@@ -54,15 +68,19 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   const removers: (() => void)[] = []; const timers: ReturnType<typeof setInterval>[] = [];
   let resolveDone: () => void = () => {}; const done = new Promise<void>(resolve => { resolveDone = resolve; });
   let pendingStream: ConsoleEvent[] = []; let droppedStream = 0;
-  const safeWrite = (text: string) => terminal.write(terminalText(text));
-  const writeStream = (text: string) => {
+  const safeWrite = (text: string) => terminal.write(paint([{ text }], color));
+  const streamLines = (event: ConsoleEvent) => terminalText(event.text).split("\n").flatMap((text, index) => wrap(text, columns).map(line => [{ text: line, ...(index === 0 && event.tone ? { tone: event.tone } : {}) }]));
+  const writeStream = (event: ConsoleEvent) => {
     terminal.write(`\x1b[${rows - 3};1H`);
-    for (const line of wrap(text, columns)) { safeWrite(line); terminal.write("\r\n"); }
+    for (const line of streamLines(event)) { terminal.write(paint(line, color)); terminal.write("\r\n"); }
   };
   const stream = (event: ConsoleEvent) => {
     state.events = [...state.events, { ...event, text: terminalText(event.text) }].slice(-1000);
-    if (plain) safeWrite(event.text + "\n");
-    else if (state.mode === "stream") writeStream(event.text);
+    if (plain) {
+      const [header, ...body] = terminalText(event.text).split("\n");
+      terminal.write(paint([{ text: header ?? "", tone: event.tone }, ...body.map(text => ({ text: "\n" + text }))], color) + "\n");
+    }
+    else if (state.mode === "stream") writeStream(event);
     else { pendingStream.push(event); if (pendingStream.length > 1000) { pendingStream.shift(); droppedStream++; } }
   };
   const draw = () => {
@@ -70,15 +88,15 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
     if (state.mode === "panels" && !inAlternate) { terminal.write("\x1b[r\x1b[?1049h\x1b[2J"); inAlternate = true; }
     else if (state.mode === "stream" && inAlternate) {
       terminal.write(`\x1b[?1049l\x1b[1;${rows - 3}r`); inAlternate = false;
-      if (droppedStream) writeStream(`${droppedStream} older panel-mode events omitted from console memory; inspect hub.log for the full stream.`);
-      for (const event of pendingStream) writeStream(event.text);
+      if (droppedStream) writeStream({ text: `${droppedStream} older panel-mode events omitted from console memory; inspect hub.log for the full stream.` });
+      for (const event of pendingStream) writeStream(event);
       pendingStream = []; droppedStream = 0;
     }
     terminal.write(state.mode === "stream" ? `\x1b[1;${rows - 3}r` : "\x1b[r");
-    const lines = renderConsole(state, columns, rows);
+    const lines = renderConsoleLines(state, columns, rows);
     const start = state.mode === "stream" ? rows - 2 : 1;
-    for (const [index, line] of lines.entries()) { terminal.write(`\x1b[${start + index};1H\x1b[2K`); safeWrite(line); }
-    terminal.write(`\x1b[${rows};${Math.min(columns, Bun.stringWidth(lines.at(-1) ?? "") + 1)}H\x1b[?25h`);
+    for (const [index, line] of lines.entries()) { terminal.write(`\x1b[${start + index};1H\x1b[2K`); terminal.write(paint(line, color)); }
+    terminal.write(`\x1b[${rows};${Math.min(columns, Bun.stringWidth(paint(lines.at(-1) ?? [], false)) + 1)}H\x1b[?25h`);
   };
   const stop = (reason?: string) => {
     if (!active) return;
@@ -130,7 +148,11 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   });
   const effect = async (action: ConsoleEffect) => {
     if (action.type === "exit") return stop();
-    if (action.type === "permit") { client.send({ t: "permit", surface: "console", id: action.id, ...(action.option ? { option: action.option } : {}) }); return; }
+    if (action.type === "permit") {
+      client.send({ t: "permit", surface: "console", id: action.id, ...(action.option ? { option: action.option } : {}) });
+      if (!action.option) stream({ text: `  ! denial requested for permission ${action.id}`, kind: "permission", tone: "failure" });
+      return;
+    }
     if (action.type === "show") {
       const result = await client.request(action.panel === 3 ? { t: "task", op: "task_show", args: { id: action.id } } : { t: "queue", op: "show", id: action.id }, 3000);
       if (!active) return;
@@ -157,14 +179,15 @@ export async function runConsole(options: ConsoleOptions): Promise<void> {
   client.onPush = msg => {
     if (!active) return;
     try {
-      if (msg.t === "event") stream({ text: renderTailEvent(msg.e), peer: msg.e.peer ?? msg.e.env?.from, kind: msg.e.env?.kind ?? msg.e.t });
+      if (msg.t === "event") stream({ text: renderTailEvent(msg.e), peer: msg.e.peer ?? msg.e.env?.from, kind: msg.e.env?.kind ?? msg.e.t, tone: eventTone(msg.e) });
       else if (msg.t === "context") stream({ text: `  ${msg.peer}: ${contextLine(msg.reading)}`, peer: msg.peer, kind: "context" });
       else if (msg.t === "notice") stream({ text: `  * ${msg.line}`, kind: "notice" });
       else if (msg.t === "permission") {
-        stream({ text: `  ? ${msg.peer} asks permission: ${String(msg.title).replace(/\n/g, "\n      | ")}\n    answer with: ahub permit ${msg.id} <${msg.options.map((o: any) => `${o.optionId} (${o.name})`).join(", ")}> | deny`, peer: msg.peer, kind: "permission" });
+        stream({ text: `  ? ${msg.peer} asks permission: ${String(msg.title).replace(/\n/g, "\n      | ")}\n    answer with: ahub permit ${msg.id} <${msg.options.map((o: any) => `${o.optionId} (${o.name})`).join(", ")}> | deny`, peer: msg.peer, kind: "permission", tone: "attention" });
         if (typeof msg.expiresAt === "number" && msg.expiresAt > Date.now() && !state.approvals.some(a => a.id === msg.id)) state.approvals.push(msg);
       } else if (msg.t === "permission_closed") {
         state.approvals = state.approvals.filter(a => a.id !== msg.id); state = pruneApprovals(state, Date.now());
+        if (msg.reason === "expired" || msg.outcome === "cancelled" || msg.outcome?.startsWith("reject")) stream({ text: `  ! ${msg.peer} permission ${msg.id} ${msg.reason ?? msg.outcome}`, peer: msg.peer, kind: "permission", tone: "failure" });
       }
       draw();
     } catch (error) { stop(`Console error: ${String((error as Error).message)}`); }

package/src/cli/main.ts

@@ -33,12 +33,13 @@ import { setupOllamaModel } from "./models-setup.ts";
 import { unknownContext } from "../hub/context-window.ts";
 import { backendLine, contextLine, peerLine, type BackendRow, type PeerRow } from "./status-lines.ts";
 import { parseSince, readEvents } from "../hub/events.ts";
-import { formatReport, summarize } from "../hub/report.ts";
+import { formatReport, summarize, formatTaskReport, summarizeByTask } from "../hub/report.ts";
 import { hasTree, planUndo, repoOf, restore, Turns } from "../hub/snapshots.ts";
 import { pathWarnings } from "../hub/conflicts.ts";
 import { classifyPeerCommand, cliCommandLabel, detectCliIdentity, peerCommandRefusal } from "./identity.ts";
 import { recordCliAudit } from "./identity-audit.ts";
 import { runConsole } from "./console.ts";
+import { resolveColor } from "./console-state.ts";
 import { renderTailEvent } from "./tail-render.ts";
 
 /** `--since 7d|24h|<iso>` for export and report; everything when absent. */
@@ -61,7 +62,7 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub setup [--yes]            install or update the Claude Code channel plugin from this package, then run doctor
   ahub init [--dry-run --json]   preview or write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block)
   ahub up [--unattended] [--no-console]  start the daemon; interactive terminals enter console
-  ahub console [--panels]      enter the human console, leaving the daemon running on exit
+  ahub console [--panels] [--color=auto|always|never]  enter the human console, leaving the daemon running on exit
   ahub upgrade --to <version> [--dry-run] [--yes]   review and upgrade running projects
   ahub restart [--dry-run] [--yes]                 recover this project's runtime
   ahub recovery status|resume|abort <operation-id> inspect, resume or cancel a preflight
@@ -96,7 +97,7 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub queue resolve <delivery-id> --action completed|retry|discard --reason <text>
   ahub status | logs [-f] | doctor | kill
   ahub export [--since 7d|<iso>]  structured events (events.jsonl) as JSON lines; never message bodies
-  ahub report [--since 7d|<iso>] [--json]  turns, tokens, messages, overlaps and task events per period
+  ahub report [--since 7d|<iso>] [--by task] [--json]  turns, tokens, messages, overlaps and task events per period
   ahub check-path <file> [--peer <id>]  other owners' open tasks that claim or changed a file
   ahub check-path --hook        the same as a Claude Code PreToolUse hook (templates/claude-hooks.json); never blocks
   ahub facts --hook             turn-free facts as a Claude Code PreToolUse, PostToolUse and Stop hook (issue #108); never blocks
@@ -491,8 +492,10 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   console: async () => {
-    if (args.some(arg => arg !== "--panels")) fail("usage: ahub console [--panels]");
-    await runConsole({ client: await connect(), cwd, stateDir, panels: args.includes("--panels") });
+    if (args.some(arg => arg !== "--panels" && !arg.startsWith("--color=")) || args.filter(arg => arg.startsWith("--color=")).length > 1) fail("usage: ahub console [--panels] [--color=auto|always|never]");
+    const color = resolveColor(args.find(arg => arg.startsWith("--color="))?.slice("--color=".length), { isTTY: !!process.stdin.isTTY && !!process.stdout.isTTY, TERM: process.env.TERM, NO_COLOR: process.env.NO_COLOR });
+    if (color instanceof Error) return fail(color.message);
+    await runConsole({ client: await connect(), cwd, stateDir, panels: args.includes("--panels"), color });
   },
 
   up: async () => {
@@ -825,7 +828,14 @@ const commands: Record<string, () => Promise<void> | void> = {
     for (const e of readEvents(join(stateDir, "events.jsonl"), since())) console.log(JSON.stringify(e));
   },
   report: () => {
-    const r = summarize(readEvents(join(stateDir, "events.jsonl"), since()));
+    const by = args.indexOf("--by");
+    if (by >= 0 && args[by + 1] !== "task") return fail("--by takes task");
+    const events = readEvents(join(stateDir, "events.jsonl"), since());
+    if (by >= 0) {
+      const r = summarizeByTask(events);
+      return console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatTaskReport(r).join("\n"));
+    }
+    const r = summarize(events);
     console.log(args.includes("--json") ? JSON.stringify(r, null, 2) : formatReport(r).join("\n"));
   },
   facts: async () => {

package/src/hub/attribution.ts

@@ -0,0 +1,20 @@
+import type { Envelope } from "./envelope.ts";
+
+export type Attribution = "delivery" | "single_open" | "unattributed";
+export interface TaskAttribution { task?: number; attribution: Attribution; pii?: true }
+
+/** Only one distinct positive task id in the original delivery can identify its turn. */
+export function deliveryTask(originals: Envelope[]): number | undefined {
+  const ids = new Set(originals.flatMap(env => {
+    const id = Number(env.refs?.task);
+    return Number.isSafeInteger(id) && id > 0 ? [id] : [];
+  }));
+  return ids.size === 1 ? ids.values().next().value : undefined;
+}
+
+/** Rule order is deliberate: a delivered review belongs to its task, regardless of ownership. */
+export function attribute(delivery: number | undefined, inProgress: number[]): TaskAttribution {
+  if (delivery !== undefined && Number.isSafeInteger(delivery) && delivery > 0) return { task: delivery, attribution: "delivery" };
+  if (inProgress.length === 1) return { task: inProgress[0]!, attribution: "single_open" };
+  return { attribution: "unattributed" };
+}

package/src/hub/bus.ts

@@ -17,6 +17,8 @@ export type BusEvent =
   | { t: "state"; peer: PeerId; state: PeerState };
 
 export interface BusOptions {
+  /** Observe original envelopes immediately before a transport starts its turn. */
+  onDeliver?: (peer: PeerId, originals: Envelope[]) => void;
   retryMs: number;
   /** A queue this long is delivered without waiting for the batch window. */
   batchMax: number;
@@ -125,6 +127,8 @@ export class Bus {
   onQueues?: () => void;
   /** Actual transport admission, using originals even when a digest was condensed. Never an enqueue metric. */
   onDelivered?: (peer: PeerId, originals: Envelope[]) => void;
+  /** Before deliver's synchronous busy transition, with originals rather than a condensed digest. */
+  onDeliver?: (peer: PeerId, originals: Envelope[]) => void;
   /** Synchronous native failure observation, before queue callbacks can finish turn metrics. */
   onDeliveryFailed?: (peer: PeerId) => void;
   private recoveryHeld = false;
@@ -135,6 +139,7 @@ export class Bus {
 
   constructor(opts: Partial<BusOptions> = {}) {
     this.opts = { ...DEFAULT_BUS, ...opts };
+    this.onDeliver = opts.onDeliver;
     this.journal = opts.journal;
     if (this.journal) {
       const state = this.journal.snapshot();
@@ -753,6 +758,7 @@ export class Bus {
         const deliveryId = crypto.randomUUID();
         if (this.journal) { this.durableHandoff(id, deliveryId, delivery, out); this.activeDeliveries.set(deliveryId, id); }
         try {
+          try { this.onDeliver?.(id, delivery); } catch { /* observation must never affect delivery */ }
           if (this.journal) await peer.deliver(out, deliveryId);
           else { await peer.deliver(out); this.delivered(id, delivery); }
         } catch {

package/src/hub/daemon.ts

@@ -46,6 +46,7 @@ import { DEFAULT_INFERENCE, DIGEST, Inference, type InferenceConfig } from "./in
 import { ask, ASK_NOTE_TITLE, RUN_START } from "./ask.ts";
 import { currentRouting, detectSignals } from "./routing.ts";
 import { Bus } from "./bus.ts";
+import { attribute, deliveryTask, type TaskAttribution } from "./attribution.ts";
 import { DeliveryJournal } from "./delivery-journal.ts";
 import { startDashboard } from "./ui.ts";
 import { PROTOCOL, stateDirFor } from "./control-client.ts";
@@ -956,14 +957,26 @@ export async function startDaemon(opts: DaemonOptions) {
   // Turns and their tokens for telemetry (issue #40). Turn ids carry the hub run, so they stay unique across restarts.
   const runId = Date.now().toString(36);
   let turnSeq = 0;
-  const turns = new Map<PeerId, { id: string; start: number; tokens: number; tree?: string; snapshotMs?: number; private?: boolean }>();
+  const turns = new Map<PeerId, { id: string; start: number; tokens: number; tree?: string; snapshotMs?: number; private?: boolean; deliveryTask?: number; attribution: TaskAttribution }>();
+  const pendingDeliveryTask = new Map<PeerId, number>();
+  const taskAttribution = (peer: PeerId, delivery = turns.get(peer)?.deliveryTask): TaskAttribution => {
+    const result = attribute(delivery, board.list("in_progress").filter(t => t.owner === peer).map(t => t.id));
+    const task = result.task === undefined ? undefined : board.get(result.task);
+    return { ...result, ...(task && tasks.isPii(task) ? { pii: true as const } : {}) };
+  };
   const supervisionTurns = new Map<PeerId, { id: string; at: number; tokens?: number; session?: string }>();
+  bus.onDeliver = (peer, originals) => {
+    pendingDeliveryTask.delete(peer);
+    const task = deliveryTask(originals);
+    if (task !== undefined) pendingDeliveryTask.set(peer, task);
+  };
   bus.onDelivered = (peer, originals) => {
+    pendingDeliveryTask.delete(peer);
     if (!originals.some(env => env.from === HUB && env.refs?.supervision) || supervisionTurns.has(peer)) return;
     const turn = turns.get(peer);
     supervisionTurns.set(peer, { id: turn?.id ?? `supervision-${randomUUID()}`, at: turn?.start ?? Date.now(), ...(turn?.tokens ? { tokens: turn.tokens } : {}), ...(contextSession(peer) ? { session: contextSession(peer) } : {}) });
   };
-  bus.onDeliveryFailed = peer => { supervisionTurns.delete(peer); };
+  bus.onDeliveryFailed = peer => { pendingDeliveryTask.delete(peer); supervisionTurns.delete(peer); };
   const finishSupervisionTurn = (peer: PeerId) => {
     const receipt = supervisionTurns.get(peer);
     if (!receipt) return;
@@ -1000,7 +1013,7 @@ export async function startDaemon(opts: DaemonOptions) {
     const supervisionTurn = supervisionTurns.get(peer);
     if (supervisionTurn && Number.isFinite(n) && n >= 0) supervisionTurn.tokens = (supervisionTurn.tokens ?? 0) + n;
     if (n > 0) {
-      event({ type: "tokens", peer, n });
+      event({ type: "tokens", peer, n, ...taskAttribution(peer) });
       const turn = turns.get(peer);
       if (turn) turn.tokens += n;
     }
@@ -1382,7 +1395,7 @@ export async function startDaemon(opts: DaemonOptions) {
       claudeNativeUsageSeen.add(record.id);
       const reported = claudeReportedTokens(record.usage);
       if (reported !== undefined) addTokens("claude", reported);
-      event({ type: "usage", peer: "claude", source: "claude_transcript", id: record.id, ...record.usage, ...(record.servedModel ? { servedModel: record.servedModel } : {}), ...(record.at ? { measuredAt: record.at } : {}) });
+      event({ type: "usage", peer: "claude", source: "claude_transcript", id: record.id, ...record.usage, ...taskAttribution("claude"), ...(record.servedModel ? { servedModel: record.servedModel } : {}), ...(record.at ? { measuredAt: record.at } : {}) });
     }
   };
   const claudeUsageTimer = setInterval(collectClaudeUsage, 2000);
@@ -1631,6 +1644,9 @@ export async function startDaemon(opts: DaemonOptions) {
       // The adapter's own state: a pause shows a busy peer as paused, and its turn goes on all the same.
       const busy = (bus.peers.get(e.peer)?.state ?? e.state) === "busy";
       if (busy && !open) {
+        const delivery = pendingDeliveryTask.get(e.peer);
+        pendingDeliveryTask.delete(e.peer);
+        const attribution = taskAttribution(e.peer, delivery);
         const id = `${e.peer}#${runId}.${++turnSeq}`;
         // A turn of a peer with a PII task open is not snapshotted: what it writes would stay in git's object store until
         // gc. It is still recorded, without trees, so an overlapping turn's undo knows its changes are unknown.
@@ -1639,7 +1655,7 @@ export async function startDaemon(opts: DaemonOptions) {
         turnTasks.set(id, board.list().filter((t) => t.owner === e.peer && ["proposed", "in_progress", "changes_requested", "in_review"].includes(t.state)).map((t) => t.id));
         const start = turnLog && !pii ? snap(`the start of ${id}`) : undefined; // before the peer is handed anything: the tap runs inside setState
         try { turnLog?.begin(id, e.peer, start?.tree); } catch (error) { log(`turn record ${id}: ${(error as Error).message}`); }
-        turns.set(e.peer, { id, start: Date.now(), tokens: 0, ...(start ? { tree: start.tree, snapshotMs: start.ms } : {}), ...(pii ? { private: true } : {}) });
+        turns.set(e.peer, { id, start: Date.now(), tokens: 0, deliveryTask: delivery, attribution, ...(start ? { tree: start.tree, snapshotMs: start.ms } : {}), ...(pii ? { private: true } : {}) });
         event({ type: "turn_start", peer: e.peer, turn: id });
       } else if (!busy && open) {
         turns.delete(e.peer);
@@ -1658,7 +1674,7 @@ export async function startDaemon(opts: DaemonOptions) {
           if (changed.length) afterTurn = () => detectConflicts(e.peer, open.id, open.start, changed);
         }
         // A lost Claude channel/watchdog is not native completion; only its real Stop closes a counted turn.
-        if (e.peer !== "claude" || (nativeCompletedAt.get(e.peer) ?? -1) >= open.start) event({ type: "turn_end", peer: e.peer, turn: open.id, ms: Date.now() - open.start, ...(open.tokens ? { tokens: open.tokens } : {}), ...(files !== undefined ? { files, snapshotMs } : {}) });
+        if (e.peer !== "claude" || (nativeCompletedAt.get(e.peer) ?? -1) >= open.start) event({ type: "turn_end", peer: e.peer, turn: open.id, ms: Date.now() - open.start, ...open.attribution, ...(open.tokens ? { tokens: open.tokens } : {}), ...(files !== undefined ? { files, snapshotMs } : {}) });
         if (e.peer !== "claude") { // Claude's native turn end is its Stop hook
           if ((bus.peers.get(e.peer)?.state ?? e.state) === "idle") queueMicrotask(() => finishSupervisionTurn(e.peer));
           turnEnded.set(e.peer, Date.now());
@@ -2087,7 +2103,7 @@ export async function startDaemon(opts: DaemonOptions) {
       const local = new LocalPeer("local", {
         cwd: opts.cwd,
         omni,
-        onUsage: record => event({ type: "usage", peer: "local", source: "omniroute", id: record.id, ...record.usage, requestedModel: record.requestedModel, ...(record.servedModel ? { servedModel: record.servedModel } : {}), ...(record.provider ? { provider: record.provider } : {}), measuredAt: record.at }),
+        onUsage: record => event({ type: "usage", peer: "local", source: "omniroute", id: record.id, ...record.usage, ...taskAttribution("local", record.task), requestedModel: record.requestedModel, ...(record.servedModel ? { servedModel: record.servedModel } : {}), ...(record.provider ? { provider: record.provider } : {}), measuredAt: record.at }),
         admitBudget: async (envs, unit) => tasks.admitExecutionEnvelopes(envs, "local", unit),
         ...(route ? { route } : {}),
         ...(sidecar && route && !route.startsWith("hub/") ? { sidecar } : {}),

package/src/hub/events.ts

@@ -1,4 +1,5 @@
 import { appendFileSync, closeSync, existsSync, fstatSync, openSync, readFileSync, readSync } from "node:fs";
+import type { TaskAttribution } from "./attribution.ts";
 
 /** Bumped whenever a field changes meaning or goes away; new fields and new types do not bump it. */
 export const EVENTS_SCHEMA = 1;
@@ -23,7 +24,7 @@ export type HubEvent =
   | { type: "split"; task: number; where?: "routing" | "cohort"; verdict: "split" | "single" | "unknown"; single?: string; splitS?: number; singleS?: number; reason?: string; trace?: string[] }
   | { type: "state"; peer: string; state: string }
   | { type: "turn_start"; peer: string; turn: string }
-  | { type: "turn_end"; peer: string; turn: string; ms: number; tokens?: number; files?: number; snapshotMs?: number }
+  | ({ type: "turn_end"; peer: string; turn: string; ms: number; tokens?: number; files?: number; snapshotMs?: number } & Partial<TaskAttribution>)
   | { type: "native_turn_end"; peer: string; id?: string }
   | { type: "conduct"; peer: string; action: string; task?: number; target?: string }
   | { type: "agent_cli"; peer: string; command: string; refused: boolean }
@@ -32,8 +33,8 @@ export type HubEvent =
   | { type: "supervision_turn"; peer: string; turn: string; tokens?: number; ms?: number }
   | { type: "hook_stats"; peer: string; n: number; startupMs: number; hubMs: number; maxStartupMs: number }
   | { type: "cohort"; id: number; event: "formed" | "joined" | "lifted"; silent: boolean; tasks: number[]; owners: string[] }
-  | { type: "tokens"; peer: string; n: number }
-  | { type: "usage"; peer: string; source: "omniroute" | "claude_transcript"; id: string; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number }
+  | ({ type: "tokens"; peer: string; n: number } & Partial<TaskAttribution>)
+  | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript"; id: string; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
   | { type: "task"; id: number; event: string; by: string; state: string; owner: string | null; reviewer: string | null; class: string; pii: boolean }
   | { type: "overlap"; task: number; owner: string; others: { task: number; owner: string; paths: string[]; symbols?: string[] }[] }
   | { type: "conflict"; peer: string; task?: number; other: number; owner: string; paths: string[]; concurrent: boolean; turns?: [string, string] }

package/src/hub/report.ts

@@ -207,3 +207,112 @@ export function formatReport(r: Report): string[] {
   lines.push(`quota readings: ${r.quota.readings} (${r.quota.hard} hard limits)`);
   return lines;
 }
+
+const usageCounters = ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens"] as const;
+const usageCounts = ["inputRecords", "outputRecords", "cacheReadRecords", "cacheWriteRecords", "totalRecords"] as const;
+type TaskUsage = Omit<UsageCoverage, typeof usageCounters[number]> & Record<typeof usageCounters[number], number | null>;
+export interface TaskPeerReport { tokens: number | null; usage: TaskUsage }
+export interface TaskTotals { turns: number; peers: Record<string, TaskPeerReport> }
+export interface TaskSummary extends TaskTotals { class: string | null; outcome: string | null; wallMs: number | null; pii?: true }
+export interface TaskReport {
+  from?: string;
+  to?: string;
+  tasks: Record<string, TaskSummary>;
+  classes: Record<string, TaskTotals>;
+  totals: { tokens: number; usageRecords: number };
+  unattributed: TaskTotals & { tokens: number; usageRecords: number; tokenShare: number | null; usageShare: number | null };
+  beforeAttribution: TaskTotals & { tokens: number; usageRecords: number };
+}
+
+const taskTotals = (): TaskTotals => ({ turns: 0, peers: {} });
+const taskPeer = (group: TaskTotals, id: string): TaskPeerReport => group.peers[id] ??= {
+  tokens: null, usage: { ...emptyUsage(), inputTokens: null, outputTokens: null, cacheReadTokens: null, cacheWriteTokens: null, totalTokens: null },
+};
+
+function addTaskUsage(peer: TaskPeerReport, e: Extract<StampedEvent, { type: "usage" }>): void {
+  const known = emptyUsage();
+  recordUsage(known, e);
+  const u = peer.usage;
+  u.records += known.records; u.withUsage += known.withUsage; u.withoutUsage += known.withoutUsage;
+  for (let i = 0; i < usageCounters.length; i++) {
+    const field = usageCounters[i]!, count = usageCounts[i]!;
+    if (known[count]) u[field] = (u[field] ?? 0) + known[field];
+    u[count] += known[count];
+  }
+}
+
+/** Task identities and history come only from telemetry. Historical usage is never reassigned. */
+export function summarizeByTask(events: StampedEvent[]): TaskReport {
+  const r: TaskReport = { tasks: {}, classes: {}, totals: { tokens: 0, usageRecords: 0 },
+    unattributed: { ...taskTotals(), tokens: 0, usageRecords: 0, tokenShare: null, usageShare: null },
+    beforeAttribution: { ...taskTotals(), tokens: 0, usageRecords: 0 } };
+  const task = (id: number) => r.tasks[String(id)] ??= { ...taskTotals(), class: null, outcome: null, wallMs: null };
+  const starts = new Map<number, number>(), approvals = new Map<number, number>();
+  const seenUsage = new Set<string>();
+  // Resolve latest class/outcome before rolling usage up: usage may precede the task's history in a slice.
+  for (const e of events) {
+    r.from ??= e.at; r.to = e.at;
+    if (e.type !== "task") continue;
+    const t = task(e.id);
+    t.class = e.class; t.outcome = e.state;
+    if (e.pii) t.pii = true;
+    const at = Date.parse(e.at);
+    if (!Number.isFinite(at)) continue;
+    if (e.state === "in_progress" && !starts.has(e.id)) starts.set(e.id, at);
+    if (e.state === "approved" && !approvals.has(e.id)) approvals.set(e.id, at);
+  }
+  for (const [id, t] of Object.entries(r.tasks)) {
+    const start = starts.get(Number(id)), end = approvals.get(Number(id));
+    if (t.outcome === "approved" && start !== undefined && end !== undefined && end >= start) t.wallMs = end - start;
+    r.classes[t.class ?? "unknown"] ??= taskTotals();
+  }
+  for (const e of events) {
+    if (e.type !== "tokens" && e.type !== "usage" && e.type !== "turn_end") continue;
+    if (e.type === "usage") {
+      const key = `${e.peer}\0${e.source}\0${e.id}`;
+      if (seenUsage.has(key)) continue;
+      seenUsage.add(key);
+      r.totals.usageRecords++;
+    } else if (e.type === "tokens") r.totals.tokens += e.n;
+    let groups: TaskTotals[];
+    if (e.attribution === undefined) {
+      groups = [r.beforeAttribution];
+      if (e.type === "tokens") r.beforeAttribution.tokens += e.n;
+      if (e.type === "usage") r.beforeAttribution.usageRecords++;
+    } else if (e.attribution === "unattributed" || e.task === undefined) {
+      groups = [r.unattributed];
+      if (e.type === "tokens") r.unattributed.tokens += e.n;
+      if (e.type === "usage") r.unattributed.usageRecords++;
+    } else {
+      const t = task(e.task);
+      if (e.pii) t.pii = true;
+      groups = [t, r.classes[t.class ?? "unknown"] ??= taskTotals()];
+    }
+    for (const group of groups) {
+      const p = taskPeer(group, e.peer);
+      if (e.type === "turn_end") group.turns++;
+      else if (e.type === "tokens") p.tokens = (p.tokens ?? 0) + e.n;
+      else addTaskUsage(p, e);
+    }
+  }
+  r.unattributed.tokenShare = r.totals.tokens ? r.unattributed.tokens / r.totals.tokens : null;
+  r.unattributed.usageShare = r.totals.usageRecords ? r.unattributed.usageRecords / r.totals.usageRecords : null;
+  return r;
+}
+
+export function formatTaskReport(r: TaskReport): string[] {
+  const lines = [`period: ${r.from ?? "-"} .. ${r.to ?? "-"}`];
+  const peers = (group: TaskTotals) => Object.entries(group.peers).sort(([a], [b]) => a.localeCompare(b)).map(([id, p]) => {
+    const u = p.usage;
+    const counts = usageCounters.map((field, i) => `${field} ${u[field] ?? "unknown"} (${u[usageCounts[i]!]}/${u.records} known)`).join(", ");
+    return `  peer ${id}: tokens ${p.tokens ?? "unknown"}; ${counts}`;
+  });
+  for (const [id, t] of Object.entries(r.tasks).sort(([a], [b]) => Number(a) - Number(b))) {
+    lines.push(`task #${id}${t.pii ? " [pii]" : ""}: class ${t.class ?? "unknown"}, outcome ${t.outcome ?? "unknown"}, turns ${t.turns}, wall ${t.wallMs === null ? "unknown" : `${t.wallMs} ms`}`, ...peers(t));
+  }
+  for (const [name, group] of Object.entries(r.classes).sort(([a], [b]) => a.localeCompare(b))) lines.push(`class ${name}: turns ${group.turns}`, ...peers(group));
+  const share = (value: number | null) => value === null ? "unknown" : `${(value * 100).toFixed(1)}%`;
+  lines.push(`unattributed: tokens ${r.unattributed.tokens}/${r.totals.tokens} (${share(r.unattributed.tokenShare)}), usage records ${r.unattributed.usageRecords}/${r.totals.usageRecords} (${share(r.unattributed.usageShare)}), turns ${r.unattributed.turns}`, ...peers(r.unattributed));
+  lines.push(`before attribution: tokens ${r.beforeAttribution.tokens}, usage records ${r.beforeAttribution.usageRecords}, turns ${r.beforeAttribution.turns}`, ...peers(r.beforeAttribution));
+  return lines;
+}