@staix/agent-hub 0.12.15 → 0.12.16

package/CHANGELOG.md

@@ -4,6 +4,15 @@ Issue and pull request numbers in the entries for 0.7.7 and earlier refer to the
 
 ## Unreleased
 
+## 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.16, control protocol 14. 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.
 
@@ -28,7 +28,7 @@ cd <your project> && ahub init && ahub up && ahub tail
 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.16 && 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

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/tasks.md

@@ -1,6 +1,6 @@
 # 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` 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.

package/docs/agent-notes/tests.md

@@ -1,7 +1,8 @@
 # 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`.
+- 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,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.12.7 and control protocol 13. Live verification
+This guide describes ahub 0.12.16 and control protocol 14. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Install and start
@@ -27,7 +27,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
@@ -647,21 +647,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) or 14 (0.12.16), 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.16 ahub upgrade --to 0.12.16 --dry-run
+bunx --package @staix/agent-hub@0.12.16 ahub upgrade --to 0.12.16 --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) | 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 +688,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.16 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.2 --yes
+ahub upgrade --to 0.12.16 --yes
 ahub recovery status <operation-id>
 ahub recovery resume <operation-id>
 ahub recovery abort <operation-id>
@@ -924,3 +924,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.16
 ahub setup
 ```
 
@@ -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.

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

@@ -1242,3 +1242,107 @@ Relay native-session counters and per-dispatch transport usage are separate
 measurements. Request usage and provider availability are optional metadata,
 bound to their own dispatch IDs; provider absence does not change model
 qualification. Primary and fallback dispatches have independent outcomes.
+
+
+## Task idle sweep (#186, 2026-10-09)
+
+`Tasks.sweep(now)` owns a deterministic, default-off between-turn sweep. It
+classifies proposed tasks with an owner as unaccepted assignments, in-progress
+tasks with an idle owner as idle-owner findings, and in-review tasks with a
+reviewer as review-pending findings. Separate minute thresholds and a ladder
+interval are configured through the strict `task_sweep` config block described
+in operations. The daemon ticks only an enabled sweep and clears its timer on
+shutdown. No control message shape changes.
+
+The activity identity is the last real history entry index, so simultaneous
+real events are distinct. Typed sweep entries persist finding kind, activity
+index, step and injected sweep time in the existing hub.db task history. They
+never reset activity or invalidate a pending completion check. Persisting a
+step precedes its notice: restart does not repeat the step, but a crash between
+write and publish can leave the attempted notice unpublished or uncertain.
+This is not an exactly-once delivery claim.
+
+The ladder sends one ordinary task reminder to the responsible peer, then
+notifies the console and available planner-role peers, then suggests an
+alternative from pure `assign()`. Every notice uses public task titles and
+numeric task refs only; PII text and task refs/plans are absent from notices and
+ladder records. Busy/paused/offline/native-active peers, unresolved dependencies,
+completion checks, queued/in-flight/held deliveries, recovery/shutdown and live
+silent cohorts suppress the sweep. Human review reminders go to the console.
+
+The Claude launcher and preview share one native-observation hook selector.
+Turn-free coordination selects facts observations; an enabled task sweep also
+selects the existing PreToolUse/PostToolUse/Stop transport in advisory mode.
+Advisory observations update native turn evidence without enabling facts
+injection. A delivery receipt or task transition never counts as a native Stop.
+Explicit caller settings remain authoritative, with a diagnostic that the
+managed idle observation hooks are disabled for that session.
+
+Automatic reassignment remains off. Explicit `auto_reassign: true` enables only
+an owner handover to an available routed alternative through Tasks' existing
+assignment path; reviewer handovers remain suggestions. No failed-work outcome
+is inferred from elapsed time. Existing route-explain behavior is unchanged,
+and offline-owner release and delivery-journal retries remain separate policies.
+
+## Initialization and launcher previews (issue #189)
+
+Initialization provides a read-only action/path/reason plan with managed-block
+insert/replace/remove metadata. Normal initialization applies the same planner.
+
+Claude/Codex/Kimi/Pi launcher previews share native command builders with actual
+launches. Preview exits before project registration, runtime setup or terminal
+ownership records. JSON contains argv/settings with arbitrary user-supplied
+values and custom executable overrides redacted, environment names only, and
+explicit reasons for unresolved native-assigned endpoints/session identities.
+A preview does not assert runtime, account or executable readiness.
+Claude/Codex previews report the conditional daemon/Orca launcher identity
+environment names and unresolved reasons without reading runtime identity,
+querying Orca, allocating a launch id or exposing values. Existing Pi launch
+behavior and its builder-derived environment preview remain unchanged.
+
+
+
+## Native context telemetry and checkpoints (issue #185)
+
+Context occupancy is separate from quota and accumulated billable session usage.
+Claude reports `context_window.used_percentage` and `context_window_size` from
+its status-line payload. A valid `current_usage` counter tuple is required;
+null, malformed or missing current usage is unknown, including immediately
+after compaction. Its input occupancy excludes output and sums input tokens,
+cache creation and cache reads, matching the [official status-line schema](https://code.claude.com/docs/en/statusline).
+Codex reports `tokenUsage.last.totalTokens / tokenUsage.modelContextWindow` in
+`thread/tokenUsage/updated`. The [native protocol](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/schema/typescript/v2/ThreadTokenUsage.ts)
+and [native TUI](https://github.com/openai/codex/blob/main/codex-rs/tui/src/token_usage.rs)
+distinguish the last active context from the accumulated `total`; the displayed
+raw occupancy does not apply the TUI's baseline-adjusted remaining percentage.
+Pi's RPC state exposes no measured native counter. Its extension context API
+returns an estimate, so Pi and unsupported peers remain unknown here.
+
+Each reading records source and measurement time. Claude's status-line file is
+bound to the daemon instance, managed launcher and native session; Codex's
+notification is fenced by its owning link and native thread. Stale, invalid,
+disconnected or replaced-session readings expose unknown occupancy, never zero.
+`context.gate` defaults to 0 (off); `context.stale_min` defaults to 30.
+A valid above-gate reading emits one metadata-only `context_pressure` event
+and one crossing notice. Invalid or stale readings do not rearm a crossing;
+a valid below-gate reading or a new native session does. A crossing held by pause or recovery remains unlatched and is reconsidered after release using only a still-fresh, current-session reading; no new native sample is required.
+
+Context and quota checkpoints share the same request/wait path. Only one
+request per peer may wait at a time. Context responses must carry the supplied
+`request_id` and match the attached peer and native session. Timeout,
+disconnection, recovery hold, shutdown and session replacement invalidate the
+request. Context requests leave quota records, task assignments, pause state,
+native compaction settings and session ownership unchanged.
+
+A valid non-private context response is saved in the state directory as a
+0600 `context-checkpoint-<peer>.json` note. With memory enabled, its text is
+also saved as a handover note only after the active-turn, task PII and text
+pattern checks. It is never broadcast to peers or quoted in logs/events.
+Private turns and all non-approved PII tasks associated with the peer as owner or reviewer, including tasks already in review, block requests and completion. The current routing PII policy is rechecked at both boundaries. The operator chooses
+whether to continue the native session or restart; this change provides no
+automatic session replacement. Status, tail and dashboard expose readings with
+source, measurement time and freshness beside quota information.
+
+The control contract is protocol 14. Recovery sources 9 through 13 remain
+supported; protocol 13 identifies releases 0.12.4 through 0.12.15, while
+0.12.16 uses protocol 14.