@staix/agent-hub 0.12.16 → 0.12.18

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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).
+- Identify agent shell CLI calls as their peer, refuse human-only commands before connecting and record ids-only audit notices without an as-user bypass (#193).
+- Grant steering tools only to one explicit conductor role, preserve the actor on task changes and keep conductor holds separate from human, budget and recovery holds (#194).
+- Batch public task milestones and human-action reminders through the existing digest window, replace repeated pending notices and report completed native supervision turns with unknown usage preserved (#195).
+- Advance the control protocol to 15 for approval lifecycle and supervision metadata, retaining controlled recovery from supported previous sources.
+
 ## 0.12.16
 
 - Record source-verification commits for current operating documents and agent notes; fail missing coverage, invalid stamps and README version drift, and report stale source scopes deterministically (#188).

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.16, control protocol 14. 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.
 
@@ -22,13 +22,13 @@ Install from npm:
 
 ```bash
 bun add -g @staix/agent-hub && ahub setup
-cd <your project> && ahub init && ahub up && ahub tail
+cd <your project> && ahub init && ahub up
 ```
 
 Or install the same version from GitHub:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.12.16 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.12.18 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.
@@ -100,7 +100,7 @@ only. `--backend dgx` or `--backend mlx` explicitly pins a Pi session's backend.
 Pi connects to an authenticated relay with model aliases `dgx/coding`,
 `dgx/fast`, and `mlx/fast`; upstream gateway credentials stay in the hub.
 Its managed tools use the existing path guards, shell sandbox and terminal
-approval flow. Keep `ahub tail` open to approve write/edit/shell operations.
+approval flow. Keep `ahub console` open to approve write/edit/shell operations.
 Tool-call receipts survive daemon restart; an interrupted operation with an
 unknown outcome must be reconciled before repeating it. Cancelling a Pi turn
 does not automatically hand its task to a cloud peer.

package/docs/agent-notes/adapters.md

@@ -15,4 +15,5 @@ Scope: the Codex, ACP and Pi adapters and the Pi extension (turn `generation` an
 - Native owner teardown must handle a lost shutdown acknowledgement using verified process identity. Pending launches must be revocable, and active tools/streaming output must count as watchdog activity.
 - Pi owner identity is one shared contract, `processSignature` in `src/pi/process-signature.ts`; the startup claim check, the extension's claim, the TUI owner monitor, `recoveryReady` and the verified teardown all go through it. Its `ps` read pins LC_ALL=C and TZ=UTC (the `processTable` contract) because `lstart` follows the reader's timezone and locale, and a hub on UTC with a Pi child on system time otherwise hashes different strings for the same process and refuses the valid owner (#174). Strict pid + start + command identity stays; never accept PID-only or a fuzzy command match.
 - Return the shared `toolResultFailed` verdict as `/tool`'s `failed`; map only `failed === true` to Pi's `isError`. Preserve text and the older bridge's absent-flag behavior.
+- Spawn a native peer with `peerChildEnv(peer, source)` so its own `AGENTHUB_PEER_ID` replaces inherited agent markers. Sandbox tool environments carry their executing peer too. Preserve the native shell environment policy; Codex's `CODEX_THREAD_ID` supplies the fallback after filtering. Before changing marker detection or launcher environments, read `docs/verification/2026-10-09-agent-shell-t0.md` for pinned source and live-probe limits.
 - Emit Pi's ceiling event at the pre-effect rejection boundary (`src/pi/ceiling.ts`), before `agent_end`. Accept only a valid current-session/current-generation signal during a running turn; retain the first signal and attach it to that turn's failure. Never classify a ceiling from free text.

package/docs/agent-notes/bus.md

@@ -1,5 +1,7 @@
 # Bus, digests and replies
 
+- Supervision replaces only pending, never attempted or accepted, envelopes with the same stable key. Preserve the first batch deadline and existing digest/queue ceilings; role/feed revocation withdraws pending notices only. Count supervision from actual transport admission followed by a successful native turn completion, never from enqueue or failure-to-idle.
+
 Scope: delivery, digests and condensation, reply addressing, priority and limits. Read before editing `src/hub/bus.ts`, `src/hub/envelope.ts`, `src/hub/limits.ts`, `src/hub/delivery-journal.ts`, `src/hub/inference.ts` (digest condensation), or how an adapter addresses a reply or sets its priority.
 
 - A failed digest is retried one envelope at a time, so a poison envelope cannot take its neighbours down with it.

package/docs/agent-notes/tasks.md

@@ -1,7 +1,9 @@
 # Task board and hub tools
 
-Scope: the task flow, assignment, the state machine and the hub's MCP tools. Read before editing `src/hub/tasks.ts`, `src/hub/board.ts`, `src/hub/routing.ts`, `src/hub/task-sweep.ts` or `src/hub/hub-tools.ts`.
+Scope: the task flow, assignment, the state machine and the hub's MCP tools. Read before editing `src/hub/tasks.ts`, `src/hub/board.ts`, `src/hub/routing.ts`, `src/hub/task-sweep.ts`, `src/hub/conductor.ts`, `src/hub/supervision.ts` or `src/hub/hub-tools.ts`.
 
 - Tool callers are models: MCP `inputSchema` is not enforced on the way in. Normalize at the boundary (`cleanRefs`) before anything reaches the board, and never throw after a board write.
 - `assign()` never defaults to the task's current owner, or a decline can only come back to the decliner.
 - The state machine allows `in_progress -> approved` only for classes without a reviewer; `review()` checks `in_review` itself.
+- Conductor authority requires the explicit unique role before capability checks. Assignments preserve the acting peer. A peer releases only its own conductor hold; operator release and manual, quota and recovery holds remain separate paths.
+- Supervision reasons use structured enums, never history notes, check output or approval titles. Round signatures survive restart; later summaries count only newly joined tasks.

package/docs/agent-notes/tests.md

@@ -5,4 +5,5 @@ Scope: tests, fakes and the test gate. Read before adding or changing a test or
 - Tests that are not about batching build the bus with `batchMs: 0`; with the default 15 s window a lone status envelope looks like a lost message.
 - In Bun 1.3.14 a test timeout that fires while `Bun.spawnSync` runs can start the next test inside spawnSync's own event loop, where another spawnSync then spins at full CPU for good (trigger not pinned down; see README). Bun 1.4.2 still runs the next test inside the outer spawnSync's event loop. `scripts/check.sh` runs tests with a 20 s timeout and under `scripts/hang-watch.sh`; a test that spawns and reads the process table gets a timeout of its own.
 - A child process gets a scrubbed environment, so test knobs for fakes travel in a wrapper script, not in `process.env`.
+- Bind agent identity markers explicitly in native/CLI fixture children. The full gate starts the test runner without inherited agent markers for human CLI fixtures; never weaken production marker detection to make them pass.
 - Run `bun scripts/seeded-check.ts` before reporting the seeded-guard gate complete. Keep the six `scripts/seeds.json` cases sequential; require the same named test green before its seeded assertion fails. Seed rot, survivors, setup/compiler failures, timeout/watchdog termination and process leaks fail the gate. Never run the full seed runner from a unit test or mutate the source checkout; inspect preserved failed fixtures before removing them. CI runs this in the required Linux `seeded guards` job after the ordinary check, separately from `scripts/check.sh`.

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,8 +1,136 @@
 # Operations guide
 
-This guide describes ahub 0.12.16 and control protocol 14. 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
+
+`ahub console` combines the existing tail stream with peer, quota, approval-age
+and input rows. `ahub up` opens it when both input and output are terminals;
+`--no-console` and redirected input/output retain the start-only behavior.
+`ahub tail` remains available with its existing rendering.
+
+Allowing an approval requires selection and a separate confirmation. Denying
+does not. Only options the daemon supplied are selectable. Typing a command
+prevents approval shortcuts from interpreting that input as an answer. Full
+approval titles are terminal-only; expiry and answers from another console remove
+the pending item. Approval audit records contain id, peer, option kind, response
+time and answering surface, without the title.
+
+Tab toggles stream and panels; `ahub console --panels` starts in panels. Peers,
+Approvals, Tasks, Queue and Events support arrow keys or j/k, Enter for detail,
+Escape to return and `?` for help. `:` enters a command. Assignment, delivery
+resolution and allow decisions require confirmation; delivery resolution requires
+a reason. Tasks use the same public redaction as the board. Panels need at least
+80 columns by 24 rows; smaller terminals stay in stream mode. Task and queue
+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,
+launch, nested console, setup, UI, logs and tail commands are refused.
+
+## Conducting a team from Claude Code or Codex
+
+Start the daemon with `ahub up --no-console`, set exactly one conductor in the
+project configuration, then open `ahub console` in a split terminal for approvals:
+
+```json
+{
+  "roles": { "claude": ["planner", "reviewer", "conductor"] },
+  "conductor": { "feed": "own" }
+}
+```
+
+Launch that peer with `ahub claude` for channel pushes, or select `codex` in
+`roles` and launch `ahub codex`. The conductor splits work into owned tasks,
+observes `hub_status`, moves stalled work and obtains review before reporting
+results and open decisions. It does not implement the tasks it handed out.
+`hub_peer_start` starts local, Kimi or headless Pi; requests for native TUIs
+return the `ahub` command for the person to run, after validating it through
+the shared launcher planner. The wrapper plans again at launch when native
+endpoints are available. `hub_peer_hold` and `hub_peer_release`
+manage only holds placed by that conductor. Assignment also requires `assign`
+when the conductor has an explicit capabilities list.
+
+Check the returned owner and task state after assignment. Routing skips paused
+peers, so assign work before placing a delivery hold. Hand work out through the
+board and report to the person with `hub_send` addressed to `user`, or a `[FYI]`
+final response in the native TUI. Broadcasting implementation instructions can
+cause an otherwise unassigned owner to claim duplicate work.
+
+The person answers approvals in the console, resolves `needs_review` deliveries
+with `ahub queue resolve`, and handles budget overrides and hub lifecycle.
+Running these commands from an agent shell is refused; the CLI retains the
+agent's identity even when invoked through a shell tool.
+
+`conductor.feed` is `own` by default, `all` for all tasks, or `off`. Ordinary
+milestones share the existing digest window and collapse repeated queued
+task/kind notices. They wait behind a busy conductor. An aged approval or
+`needs_review` hold is important, contains only peer/tool-age or delivery id,
+and directs the conductor to ask the person. A completed task set emits one
+round notice until a new task joins. Removing the role or switching the feed
+off withdraws pending feed notices.
+
+For a Claude conductor, `ahub claude` also observes native session and turn
+boundaries when facts injection and task-idle sweeps are off. Keep the managed
+hooks enabled to measure completion and supervision usage. Passing your own
+`--settings` takes precedence and produces a warning when it replaces that
+observation. The launcher records its private session identity in ordinary
+terminals too; this does not grant terminal-recovery authority.
+Ordinary Claude sessions with turn-free facts or task-idle sweeps enabled get the
+same session/start observation. Other ordinary launches remain non-opt-in.
+
+`ahub report` records conductor actions and completed native turns containing
+supervision. Tokens describe the whole measured turn, which may also contain
+other work; they are not a per-notice cost estimate. Missing measurements stay
+unknown. Use the live smoke ledger to assess observed turns and tokens per
+approved task before choosing `all`; an unmeasured run is not a cost benchmark.
+Claude turn counts use authenticated native completion events. Older logical
+state counts are labelled; an idle channel or approved task alone does not prove
+that the native answer finished.
+The Stop hook acknowledgement is not a counted completion. The daemon checks the
+native transcript after the hook can return; missing or changed-session evidence
+stays unknown.
+
 ## Install and start
 
 Use Bun 1.3 or newer. Install the released package and install its Claude
@@ -14,12 +142,11 @@ ahub setup
 cd <project>
 ahub init
 ahub up
-ahub tail
 ```
 
 `ahub init` writes the project configuration and managed instruction blocks.
 Run it after an upgrade when those blocks need refreshing. `ahub setup`
-updates the shared Claude plugin. Keep `ahub tail` open when a local worker
+updates the shared Claude plugin. Keep `ahub console` open when a local worker
 may request an approval.
 
 `.agenthub/config.json` can be committed and shared. The fields that choose
@@ -256,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
 
@@ -521,6 +653,13 @@ stays the default until an evaluation says otherwise (`docs/cooperbench.md`).
 
 Inspect permission requests in the terminal:
 
+```bash
+ahub console
+```
+
+Select the requested option in the console and confirm an allow decision.
+For a separate plain terminal, the existing command remains available:
+
 ```bash
 ahub tail
 ahub permit <request-id> allow
@@ -647,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) or 14 (0.12.16), 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.16 ahub upgrade --to 0.12.16 --dry-run
-bunx --package @staix/agent-hub@0.12.16 ahub upgrade --to 0.12.16 --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) | 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 |
 
@@ -693,14 +832,14 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.16 --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.16 --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.16
+bun add -g github:STAIxBWLB/agent-hub#v0.12.18
 ahub setup
 ```
 
@@ -34,8 +34,8 @@ In your project directory, one terminal each:
 
 ```bash
 ahub init          # .agenthub/config.json, .agenthub/routing.toml, the marker block in AGENTS.md
-ahub up            # the daemon for this directory (loopback only)
-ahub tail          # keep open: the conversation, state changes, permission requests
+ahub up            # starts the daemon and opens the operator console in a terminal
+ahub console       # use in another terminal if up used --no-console; Tab opens panels
 ahub kimi          # Kimi, headless
 ahub codex         # Codex TUI, attached through the hub
 ahub claude        # Claude Code with the hub channel

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.
@@ -28,6 +28,33 @@ agent-hub connects agents that can each run commands. This page says what the hu
 - **Network-level proof for PII.** The hub proves at its own boundaries (tests search every output) that PII text does not leave; packet-level verification of your gateway path is an operations check.
 - **Other operating systems' sandboxes.** Only macOS seatbelt is implemented.
 
+## Agent CLI identity and conductor authority
+
+Inside an agent session, `ahub` identifies the caller from `AGENTHUB_PEER_ID`,
+or the native Claude/Codex shell marker when the hub marker is absent. It connects
+as that peer in tools mode. Messages and task changes retain that actor;
+`say` defaults to status priority and important messages still require the peer's
+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. 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
+shell access. The existing OS sandbox and loopback authentication boundaries apply.
+
+Steering tools require an explicit `conductor` role, independent of default-allow
+capabilities. Only one peer may hold that role. A conductor may inspect public
+state, assign or escalate work, start supported headless peers and place its own
+delivery holds. It cannot answer approvals, resolve durable deliveries, override
+budget pauses or release a human hold. Pending approval summaries exclude titles;
+PII tasks remain public stubs. Conduct events contain ids only. Supervision feeds
+use structured reasons and never carry check output or approval bodies.
+
 ## Reporting
 
 Please report vulnerabilities privately through GitHub's "Report a vulnerability" on this repository rather than in a public issue.

package/docs/smoke.md

@@ -2,6 +2,99 @@
 
 `scripts/check.sh` covers everything against fakes. The legs below need real accounts and an interactive terminal, so they are run by hand and recorded here.
 
+## Operator console and conductor candidate (#190, #191, #193-#195)
+
+Candidate 0.12.17, protocol 15, observed on 2026-10-09 KST. The final Claude
+observer runs used immutable source `20ad5e6`; their native completion receipts
+and actual console effects were checked independently. The Kimi new-tool leg
+remains quota-blocked, as recorded below.
+
+- Actual Codex 0.146.0 (`gpt-5.5`) and Claude 2.1.295 (Opus 5.5) TUIs started
+  real local and headless Pi peers, proposed exactly two tasks owned initially
+  by local, reassigned Beta to Pi, and placed and released their own holds.
+  The real owners checked their outputs and called `hub_task_done`; the native
+  conductor independently read the exact files before approving both tasks.
+  Real CLI calls retained the agent actor, and human-only queue/permission
+  actions were refused from an agent shell.
+- The person authorized `alpha.txt = ALPHA` (5 bytes) and `beta.txt = BETA`
+  (4 bytes), both without a newline. Separate selection and confirmation keys
+  reached the actual console PTY and produced allow-once console audit records.
+  Out-of-scope directory-list commands were cancelled. The final Claude own
+  run used three allow-once answers because Pi combined its exact write and
+  bounded byte checks in one approved command; it also recorded two cancelled
+  local directory-list requests. No permission or task completion was fabricated.
+- The final Claude own run recorded nine completed native turns and nine
+  matching daemon Stop records, 27 unique native usage records, and
+  1,888,242 tokens including cached input. Eight completed native turns contained
+  supervision, with 1,292,922 recorded tokens. Its final message UUID/id,
+  `end_turn`, `turn_duration`, instance/session/launcher and opaque Stop receipt
+  matched; native idle and an empty pending delivery queue were verified before
+  owned-process cleanup. Local recorded three turns and 72,046 gateway tokens;
+  Pi recorded two turns and 47,177 native tokens.
+- A read-only Claude feed-off continuation on the final observer preserved the
+  existing approved tasks and exact files. It verified one completed native turn,
+  four usage records and 263,413 cached-inclusive tokens, with matching daemon
+  Stop, native idle and delivery settlement. An obsolete review hold was first
+  discarded through the authenticated public operator API after fresh approved
+  task/history and exact BETA readback. That discard is not native execution.
+- A real console with two pending cards and no operator input consumed 0.07 CPU
+  seconds over 40.018 wall seconds in stream mode (0.175% of one CPU). A separate
+  actual Peers panel, 120x40, with two pending cards and no operator input used
+  0.07 CPU seconds over 40.012 wall seconds (0.175%). These are cumulative `ps`
+  process CPU samples in distinct modes/runs, not whole-host idle measurements.
+- In a plain Claude TUI without the development-channel flag, one actual
+  `hub_status` MCP call succeeded and the daemon audited the Claude status
+  action. A unique directed operator push was accepted by the bridge, but no
+  pushed native user row or answer appeared in the observed 20.075-second window.
+  This proves tool access separately from the bounded negative push observation.
+  The real channel-enabled runs above received actual review and supervision
+  pushes. The plain probe and cleanup completed in 56.724 seconds, with no model
+  file, shell, task or settings actions.
+- Real Kimi Code CLI 2.1.1 completed ACP initialization and `session/new`, then
+  rejected the single prompt with HTTP 403 for its weekly account usage limit.
+  No requested native tool event or role-refusal result occurred. The reset time
+  was not supplied. The owning CLI listed only the managed OAuth Kimi provider
+  (four models, default `kimi-code/k3`), so no configured alternative provider was
+  found. This is an incomplete external prerequisite, not a new-tool pass. No
+  purchase, provider/configuration change or model retry was performed; owned
+  processes were stopped after 3.142 seconds.
+
+The user explicitly approved release 0.12.17 with only the Kimi native new-tool
+and ordinary-role refusal T0 evidence deferred on 2026-10-09. That native
+prerequisite remains unverified; the quota rejection is not a tool pass. This
+decision does not defer the other native/source gates or authorize a purchase,
+credentials, provider/configuration change or account retry. The same isolated
+read-only Kimi probe remains required before its native coverage is marked verified.
+
+Earlier captures remain part of the evidence:
+
+- Codex feed-off included an interrupted original and read-only continuation:
+  six logical native turns, 49 increments and 1,979,016 tokens. Codex feed-own
+  recorded nine turns, 34 increments and 1,399,470 tokens. Their journals were
+  independently checked after cleanup. The first baseline interruption and
+  operator reconciliation are preserved; neither native task completion nor
+  board approval was substituted by the harness.
+- The original Claude runs approved the actual files but an early idle-based
+  harness stopped their final review answers. Subsequent `da2ebbc` feed-off
+  completed five native turns and 1,451,782 tokens but certified only one daemon
+  Stop. A `6034dd9` read-only continuation completed another native turn and
+  261,483 tokens, while its Stop remained unavailable during the native hook.
+  Both incomplete observer captures are preserved alongside raw and audited
+  summaries. The final post-ACK observer above closes the fresh completion proof;
+  it does not retroactively certify the earlier missed Stop records.
+
+All token totals describe whole native/model turns, including cached input and
+other work. Operator waiting, cancelled requests, marker probes, interrupted
+continuations and differing source revisions make these observations unsuitable
+for a causal feed-overhead or model-efficiency comparison. Unknown measurements
+and the Kimi prerequisite remain explicit.
+
+The harness uses real Python PTYs. Operator-file-input forwards only
+chat-authorized keys, removes inherited Orca terminal ownership from fixture
+children, and generates no approval automatically. Private original and
+continuation captures remain separate. The shell-marker probes and vendor
+limits are recorded in [the identity T0 ledger](verification/2026-10-09-agent-shell-t0.md).
+
 ## Approval race live reproduction and candidate verification (#98)
 
 Measured on 2026-10-02 KST with installed 0.12.1 and the correction candidate,