@staix/agent-hub 0.12.15 → 0.12.17

package/CHANGELOG.md

@@ -4,6 +4,23 @@ Issue and pull request numbers in the entries for 0.7.7 and earlier refer to the
 
 ## Unreleased
 
+## 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).
+- Require six sequential guard checks to pass without mutation and fail their named assertion with a seeded regression. Reuse full Linux/macOS plus seeded CI only for an identical release tree (#187).
+- Add a default-off task-idle sweep with persisted escalation steps, real-activity anchors, PII-safe notices, hold/cohort suppression and explicitly opted-in owner reassignment (#186).
+- Preview initialization changes and native launcher arguments through the same builders, without hub writes or native startup; redact arbitrary user values and identify unresolved runtime metadata (#189).
+- Show native Claude/Codex context-window readings with freshness and session identity. Optional pressure checkpoints do not pause quota, reassign work or replace sessions; unknown readings stay unknown and private summaries stay out of cloud memory (#185).
+- Advance the control protocol to 14 for context status metadata while retaining controlled recovery from supported earlier protocols.
+
 ## 0.12.15
 
 - Bind Pi tool-step ceiling diagnostics to the trusted producer's session and turn, retain the rejected pre-effect invocation count, and keep the first active failure cause frozen (#179).

package/README.md

@@ -4,12 +4,12 @@ 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.2, control protocol 11. Durable delivery records distinguish queued
+Status: 0.12.17, control protocol 15. Durable delivery records distinguish queued
 work from uncertain execution. The [smoke checklist](docs/smoke.md) records
 verified paths and remaining prerequisites.
 
 Read the [operations guide](docs/operations.md) for the daily workflow, queue
-reconciliation, and the staged protocol-9/10 to protocol-11 upgrade command.
+reconciliation, and the staged upgrade command for supported source protocols.
 Controlled recovery preserves work; uncertain effects are never automatically
 replayed and may require operator review.
 
@@ -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.0 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.12.17 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.
@@ -44,6 +44,19 @@ and agent sessions so both load the update.
 - [Smoke checklist](docs/smoke.md): the live checks, and what has and has not been verified against real agents
 - [Changelog](CHANGELOG.md), [Contributing](CONTRIBUTING.md)
 
+## What ahub changes on your machine
+
+`ahub init --dry-run --json` lists missing project defaults, the managed AGENTS.md
+block, legacy CLAUDE.md cleanup and gitignore updates before writing them.
+The preview does not register the project.
+
+`ahub claude|codex|kimi|pi --print-command` (also `--dry-run`) prints the native
+argv, Claude session settings and environment variable names without launching.
+It uses the normal command builders. Arbitrary user arguments, configured commands
+and settings are redacted; runtime-assigned endpoints and session identities are
+explicitly unresolved. It does not check executable or account readiness.
+See [Security notes](docs/security.md).
+
 ## Why not agent-bridge
 
 [raysonmeng/agent-bridge](https://github.com/raysonmeng/agent-bridge) proves the
@@ -87,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/budget.md

@@ -1,6 +1,6 @@
 # Budget, pause and handoff
 
-Scope: quota readings, pause, handoff and resume, and the status line tee. Read before editing `src/hub/budget.ts`, `src/cli/statusline-tee.ts`, `src/hub/bus.ts`, `src/hub/delivery-journal.ts` or `src/hub/restart.ts` (pause persistence).
+Scope: quota and native context readings, checkpoints, pause, handoff and resume, and the status line tee. Read before editing `src/hub/budget.ts`, `src/hub/context-window.ts`, `src/cli/statusline-tee.ts`, `src/hub/bus.ts`, `src/hub/delivery-journal.ts` or `src/hub/restart.ts` (pause persistence).
 
 - Budget: checkpoint first, pause second (a paused peer receives nothing). A handoff that fails is left unmarked so the next tick or hub run retries it; never record it as done.
 - A handoff needs somebody to hand over to: `canHandOff` is false right after a restart, when no peer is attached yet, and the handoff waits for a later tick instead of stripping tasks of their owner.
@@ -8,3 +8,7 @@ Scope: quota readings, pause, handoff and resume, and the status line tee. Read
 - On resume the notice is published before the peer is released, so it leads the first delivery.
 - The coordinator only lifts its own pauses: `manualPaused` in the daemon keeps a `ahub pause` in place, and `ahub resume` refuses while a budget record is open.
 - The status line tee must never fail or slow the render: no throw, original command run with the same stdin, 5 s cap.
+
+- Keep native context occupancy in `src/hub/context-window.ts` separate from quota accounting; never use Codex's accumulated `total` as occupancy or estimate Pi counters.
+- Context checkpoint completion requires its request id and the current attached peer/native session. Invalidate its transport generation synchronously at a new peer claim, before asynchronous recall or attachment. Never pause, reassign or replace a session on context pressure. Refuse private-turn, PII-pattern and all non-approved associated PII-task summaries (owner or reviewer, including in_review, with the current routing policy) before local persistence or cloud memory; never broadcast checkpoint text.
+- Invalid/stale context readings expose unknown and do not rearm a crossing. Latch a crossing only after its event is accepted; reconsider paused/recovery-held crossings after release with fresh current-session readings. Tee context fields contain finite numeric values or null only, bound to daemon instance, launcher and native session.

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` 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

@@ -1,7 +1,9 @@
 # Tests
 
-Scope: tests, fakes and the test gate. Read before adding or changing a test or fake under `test/`, or editing `scripts/check.sh` or `scripts/hang-watch.sh`.
+Scope: tests, fakes and the test gate. Read before adding or changing a test or fake under `test/`, or editing `scripts/check.sh`, `scripts/hang-watch.sh`, `scripts/seeded-check.ts` or `scripts/seeds.json`.
 
 - 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/operations.md

@@ -1,8 +1,99 @@
 # Operations guide
 
-This guide describes ahub 0.12.7 and control protocol 13. Live verification
+This guide describes ahub 0.12.17 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.
+
+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 +105,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
@@ -27,7 +117,7 @@ what the hub runs, which files it sends as credentials, where task text goes,
 or how far the local worker's sandbox reaches (`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`, `local.sandbox`) are machine-local:
+`local.read_allow`, `local.bash_network`, `local.network_allow`) are machine-local:
 they apply only from a file git confirms nobody committed. Put them in
 `.agenthub/config.local.json` (`ahub init` adds it to `.gitignore`), which is
 read after `config.json`; outside a git repository they keep their defaults, and
@@ -521,6 +611,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 +744,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) or 13 (0.12.4 through 0.12.10) 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 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.10 ahub upgrade --to 0.12.10 --dry-run
-bunx --package @staix/agent-hub@0.12.10 ahub upgrade --to 0.12.10 --yes
+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
 ```
 
 | 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.10 (protocol 13) | 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 |
 | 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 |
 
@@ -688,19 +785,19 @@ The coordinator verifies and retains the exact target package, preserves its
 own source, and promotes the global CLI only after restored projects pass
 readback.
 
-Once the installed CLI is 0.12.0, review the current project or all registered
+Once the installed CLI matches the target release, review the current project or all registered
 projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.2 --dry-run
+ahub upgrade --to 0.12.17 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.2 --yes
+ahub upgrade --to 0.12.17 --yes
 ahub recovery status <operation-id>
 ahub recovery resume <operation-id>
 ahub recovery abort <operation-id>
@@ -924,3 +1021,172 @@ the capability is absent. It never rewrites these settings. Explicit
 `--backend mlx`, `--model mlx/fast`, and recorded MLX recovery launches are
 refused before any local startup. Re-enable MLX or explicitly migrate the
 recorded launch before recovery.
+
+## Task idle sweep
+
+The between-turn task sweep (#186) is disabled by default. Set `task_sweep` in
+`.agenthub/config.json` (or its machine-local override) to enable it:
+
+```json
+{
+  "task_sweep": {
+    "enabled": true,
+    "interval_s": 300,
+    "unaccepted_min": 60,
+    "idle_min": 120,
+    "review_min": 120,
+    "ladder_min": 30,
+    "auto_reassign": false
+  }
+}
+```
+
+Booleans must be actual booleans. Each time setting must be a finite number of
+at least 1; timeouts are bounded to the platform timer limit. Each threshold
+measures time since the last real task history event. A ladder record does not
+refresh that activity; a new event resets the ladder even at the same timestamp.
+
+The first overdue sweep sends the assigned owner or reviewer one normal task
+reminder. After `ladder_min`, the next sweep notifies the console and available
+planner-role peers. After another interval it reports a reassignment suggestion
+from the ordinary routing function. At most one step runs per task per sweep.
+PII notices contain only the public task stub, never its text, refs or plan.
+
+Busy, paused, offline or native-active peers, queued/in-flight deliveries and
+queue holds, unresolved dependencies, completion checks, recovery/shutdown and
+silent turn-free cohorts suppress the sweep. An offline owner remains governed
+by the existing `tasks.release_after_min` policy. Human reviews produce console
+notices. The sweep does not change route-explain output.
+
+For Claude, `ahub claude` installs the existing PreToolUse/PostToolUse/Stop
+observation hooks when the sweep is enabled, including in advisory projects.
+The hooks return no facts in advisory mode. A native Stop establishes an idle
+boundary; a subsequent PreToolUse marks activity. A delivery acknowledgement or
+task approval does not establish native idle. Restart the daemon and relaunch
+Claude after enabling the sweep so its session receives the hooks. A caller's
+`--settings` still wins: the launcher warns that native idle observation is off,
+and the sweep cannot verify that Claude session between turns.
+
+`auto_reassign: true` explicitly allows an available alternative owner selected
+under the existing routing, role and PII constraints to receive the task at step
+three. Review-pending work always produces only a reviewer suggestion. The
+sweep records no failed-work outcome and never weakens routing constraints.
+
+Each ladder step is persisted in task history before publishing. A restart
+therefore does not repeat it. A crash after the history write can leave its
+notice unpublished or uncertain; the history records an attempted step, not a
+receipt. Inspect `ahub task show <id>` and the delivery journal before acting;
+durable-delivery retries remain the journal's responsibility.
+
+## Documentation source verification
+
+`docs/verified.json` maps README, the current security, operations and quickstart
+pages, and every agent note to a full source commit and explicit covered paths.
+A stamp records a human check of the cited paths, symbols, numeric limits and
+operational commands. It does not certify live deployment or prove prose
+correctness automatically. Specs, changelogs and the smoke ledger retain their
+own dated evidence and are outside this manifest.
+
+`node scripts/check-docs.mjs` also runs in `scripts/check.sh`. Missing manifest
+coverage, unresolved or nonancestor commits, removed source paths and a README
+status version different from `package.json` fail the gate. Source commits since
+a stamp and uncommitted covered changes produce sorted stale notices without
+failing it. Counts are commits touching any covered path, rather than file or
+line counts; an unrelated commit leaves the document fresh. Git history must
+include the stamped ancestors (CI checks out full history).
+
+During release preparation, source review precedes restamping. Review each stale
+page against its covered source, correct drift, and use the full SHA of the
+reviewed source commit as `verifiedAgainst`. Record any deferred page and its
+specific unverified claims in the release verification report before tagging.
+Do not advance a stamp solely to clear a notice. Source stamps can name an
+ancestor: the manifest-only follow-up commit need not hash or stamp itself.
+
+## Seeded guard verification
+
+`bun scripts/seeded-check.ts` runs six guard pairs sequentially: header quoting,
+Origin refusal, control-token authentication, the hop cap, PII public views and
+uncertain-delivery receipts. Each named test first passes on current tracked
+checkout bytes, then must fail an assertion with the corresponding guard weakened.
+Seed rot (anything other than one exact replacement), a surviving seed and an
+invalid detection have distinct errors. Compiler, setup, unrelated-test and timeout
+failures never count as detection.
+
+Each seed has a private temporary checkout without Git metadata, state, output
+directories or user untracked files. Installed dependency packages are linked,
+never copied or installed by the runner. Child tests use private home, temp and
+registry directories and a scrubbed environment. The normal 20-second test timeout,
+60-second hang watchdog and current-invocation process ledger/leak scan apply to
+both legs. Successful fixtures are removed; a failed pair prints its preserved
+fixture location with test and leak evidence for inspection.
+
+The required Linux CI job `seeded guards` follows the ordinary checks; it does not
+repeat on macOS or run recursively inside `bun test`. The runner reports every
+pair's elapsed seconds and the total runtime. Runtime measurement remains pending
+until that gate executes; a green ordinary check alone does not prove these pairs.
+
+The full CI gate tests the PR head tree on Linux and macOS, followed by the
+sequential seeded-guard job. Main and release jobs reuse only a successful full
+PR or push check with the identical Git tree and all three successful jobs. An absent or
+unreadable result runs the main gate again and refuses release. A manual
+`prepare_bundle` dispatch builds reviewable plugin assets without publishing;
+it is never accepted as full-gate evidence.
+
+## Preview initialization and native launch
+
+Run `ahub init --dry-run --json` for action/path/reason metadata, including a
+managed-block summary. The real init applies the same plan and preserves user text
+and legacy symlink/hardlink safeguards. Preview creates no files or registration.
+
+Use `ahub claude --print-command`, `ahub codex --dry-run`,
+`ahub kimi --model <alias> --print-command`, or
+`ahub pi --mode tui --print-command` to inspect launch JSON.
+Environment values and arbitrary supplied values are withheld. Native-assigned
+proxy/bridge endpoints and new session identity remain unresolved.
+Claude and Codex previews include conditional `AGENTHUB_INSTANCE_ID` and
+`AGENTHUB_LAUNCH_ID` environment names with unresolved reasons. Claude's existing
+daemon identity is read at launch; a launch identity is allocated only after
+verified Orca terminal readback. Codex identities are injected when that Orca
+launch record is made. Preview neither reads those runtime identities nor
+allocates them, and never displays their values. Pi's environment preview
+continues to describe its native builder output.
+These previews do not connect to the daemon, toggle permissions, record terminal
+ownership, bind servers or start agents, sidecars or models.
+
+
+## Native context readings and optional checkpoints
+
+`ahub status`, `ahub tail` and the dashboard show native context occupancy,
+source and measurement freshness. Claude readings come from the status-line
+tee installed by `ahub claude`; Codex readings come from its current thread's
+native token-usage updates. Pi and other unsupported surfaces show unknown.
+A stale or disconnected reading is unknown, not 0%. Codex's accumulated session
+usage is never used as context occupancy.
+
+Context-triggered checkpoints are disabled by default. To enable them, add
+this to `.agenthub/config.json` and restart the daemon deliberately:
+
+```json
+{"context":{"gate":0.85,"stale_min":30}}
+```
+
+`gate` is a fraction between 0 and 1; 0 disables checkpoint requests.
+`stale_min` must be positive. A reading at or above the threshold records a metadata-only
+event and console notice, then asks an attached Claude/Codex with active work
+for a checkpoint when no checkpoint request is already outstanding. The request
+supplies a `request_id`; include that id with
+`hub_checkpoint {summary, request_id}`. Repeated high readings do not repeat
+it until a fresh below-threshold reading or new session rearms the crossing.
+
+The resulting non-private note is saved in the state directory as
+`context-checkpoint-<peer>.json`, mode 0600; saving to shared memory is attempted
+when memory is enabled. Its body is never broadcast. A private turn, an open PII
+task held by the peer, or PII-pattern text prevents persistence and sharing.
+Requests are bound to the current peer, native session and transport generation.
+A new connection claim invalidates the old request before asynchronous recall or
+attachment, even with an unchanged native session id. Requests also expire after
+`budget.checkpoint_timeout_s` (90 seconds by default).
+Quota pause and task handoff are separate; a context checkpoint neither pauses
+nor hands work over. Continue normally or deliberately restart into a fresh
+session with your chosen checkpoint as preface. No automatic restart or native
+compaction override is performed.

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.0
+bun add -g github:STAIxBWLB/agent-hub#v0.12.17
 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
@@ -58,7 +58,7 @@ ahub say @kimi "run the tests and report"          # one peer
 
 or set `OMNIROUTE_API_KEY`. Name the model in `.agenthub/routing.toml` (`[local] fixed_model`). Then `ahub local`. It works only inside the project, asks before it writes or runs anything (`ahub permit <id> allow`), and everything it executes is sandboxed.
 
-## The five commands of a working day
+## Commands of a working day
 
 | Command | What for |
 | --- | --- |

package/docs/security.md

@@ -6,12 +6,13 @@ agent-hub connects agents that can each run commands. This page says what the hu
 
 - **Other agents' text is untrusted.** Every message that crosses from one peer to another is framed as untrusted input (a channel tag with `meta.source` for Claude, a fixed header line plus a standing instruction for the others). A message body cannot forge the hub's own headers: such lines are quoted (`sanitize`). Replies inherit a hop count capped at 3, so agents cannot ping-pong forever; neither a digest nor a steer can reset it.
 - **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 touch no file and run no process, and every call passes the hub's own checks. The match relies on the agent putting the tool name in the request's `title`, as Kimi does; an ACP agent that titles calls with model-written text must not be configured as `kimi_cmd`. 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.
+- **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.
 - **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.
+- **Context checkpoints have a separate text record.** Native occupancy readings carry numeric metadata only. An optional context checkpoint persists its summary in `.agenthub/state/context-checkpoint-<peer>.json` with mode 0600 and attempts shared-memory storage when enabled. Completion requires the outstanding request id, current peer/native session and transport generation; new connection claims invalidate old requests. Private turns, every open PII task associated with the peer as owner or reviewer (including pending review), and PII-pattern summaries are refused before persistence or cloud memory. Its text is never broadcast, and context pressure does not pause, reassign or replace the session.
 - **The local worker is boxed in.** Paths are resolved through symlinks and must stay inside the project; a secrets denylist (`.env*`, keys, credential files, the hub's own state) applies to its file tools, its git arguments and its memory capture alike; `.git` and `.agenthub` are not writable. Writes, edits, shell commands and mutating git wait for approval, and the approver sees what will be written or run, with control characters escaped. Everything it executes runs under the macOS sandbox, attended or not. Since 0.10 the profile starts from deny default (issue #39): commands run and read only the system, toolchain and project directories (and the project's git dir and the selected developer dir; with network on, the public CA bundles); no writes outside the project, its git dir and a temp dir of its own (`TMPDIR`, made for each command and removed when it ends; issue #63); no `.git/hooks` or `.git/config` writes; no network, loopback included, unless `local.bash_network`; with it, only through the hub's egress proxy to the hosts in `local.network_allow` (issue #65), which refuses names that resolve to internal addresses (behind NAT64 with the well-known prefix, by the IPv4 address the answer carries; a network-specific prefix is not recognised), so claude-mem and the Codex app-server stay out of reach (`"direct"` opens everything, until 0.13.0). One channel stays open: `trustd`, which TLS clients need, can fetch a certificate's AIA or OCSP URL on a command's behalf, outside the proxy. The allow-default profile of 0.9 and earlier was removed in 0.12.0 (issue #83); a `local.sandbox` setting is ignored with a note. The shared temp dirs (the user's and `/private/tmp`) are closed. Without the sandbox there is no `bash` tool.
 - **Capabilities are enforced, not suggested.** `capabilities` (issue #39) is checked by the daemon where task operations and messages arrive, so a peer cannot get round it by phrasing. A peer can never answer a permission request: the control link takes `permit` from the console role only, and a message that quotes a permit command is just text. Both bind the hub's own tool paths: a vendor agent with its own shell in the project (Codex, Claude, Kimi) can read `.agenthub/state/control-token` and connect as the console, which only the local worker's and Pi's sandbox prevents.
 - **PII has an enforced path.** A task matching `signals.pii_patterns` goes to `local` or to nobody; its text is absent from other peers' envelopes, the console stream, the log and the board listing; the console user reviews it; `local` answers such a turn to the console only, keeps it out of its history, refuses it when the only gateway is off campus, and may not save notes or spin off tasks during it. Nothing about it is sent to claude-mem, whose observer is a cloud model.
@@ -27,6 +28,30 @@ 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.
+
+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.