@staix/agent-hub 0.7.11 → 0.8.1

package/CHANGELOG.md

@@ -2,7 +2,16 @@
 
 Issue and pull request numbers in the entries for 0.7.7 and earlier refer to the previous repository, archived on 2026-09-30 when this repository's history was rewritten; the one exception is the open smoke-check issue, formerly #12, which moved here as #1. Numbers in newer entries refer to this repository.
 
-## Unreleased
+## 0.8.1
+
+- Upgrading a running 0.7.x hub that has a task on its board no longer stops at verification ("queue, manual pause, task board or budget preservation was not verified"): the 0.8.0 target digested its tasks with the new `plan` field, which the 0.7.x source never had. The target now also accepts the digest in the source's shape while every plan is empty; any real change to the board still fails the check. Use the 0.8.1 coordinator, not 0.8.0's, for such an upgrade (#57).
+- `ahub kill` returns only once the hub has released its registry claim, so an `ahub projects remove` right after it no longer refuses, and an `ahub up` right after it no longer reads the project as starting and starts nothing (#58).
+
+## 0.8.0
+
+- Plans and completed-change notices: `hub_task_propose` and `hub_task_accept` take a `plan` (paths, symbols, signatures, insertion points), overlaps also count plan paths and shared symbols, the owners of overlapping tasks get the plan as a ride-along line, and when a task is done they get a notice of the changed files, signatures and summary. PII tasks are left out on both sides, and a plan matching a PII pattern makes a new task a PII task or is refused on an ordinary one. Overlap mentions, ride-alongs, completed-change notices and overlap events leave out any name that matches a PII pattern, and model-written titles, refs and plan items are folded onto one line. During a PII turn the local worker can no longer finish, review or accept-with-plan an ordinary task, which would carry its words to other peers and claude-mem (#31).
+- Per-turn snapshots and undo: in a git work tree, with `snapshots.enabled`, which is on in any project with an `.agenthub/config.json`, existing ones included (off without a config file; `"snapshots": { "enabled": false }` opts out), the hub snapshots the files at each turn boundary, `ahub turns` lists the files each turn changed (shell-made changes included), and `ahub undo <turn> --yes` restores them; it restores nothing when a file changed again since, or when another peer's turn at the same time touched it or left its changes unknown. `--context` also asks Codex to drop the turn from its thread's saved history; whether a running Codex session forgets it too is still to be checked live (#33).
+- Structured telemetry: the hub writes `events.jsonl` (envelopes without bodies, peer states, turns with per-turn tokens for Kimi and Codex, board changes, overlaps, quota readings), and `ahub export` and `ahub report` read it (#40).
 
 ## 0.7.11
 

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.7.11, control protocol 10. Durable delivery records distinguish queued
+Status: 0.8.1, control protocol 10. Durable delivery records distinguish queued
 work from uncertain execution. The [smoke checklist](docs/smoke.md) records
 verified paths and remaining prerequisites.
 
@@ -28,7 +28,7 @@ cd <your project> && ahub init && ahub up && ahub tail
 Or install the same version from GitHub:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.7.11 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.8.1 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.

package/docs/events.md

@@ -0,0 +1,37 @@
+# Hub events (`events.jsonl`)
+
+Schema version 1. The hub appends one JSON object per line to
+`.agenthub/state/events.jsonl`, next to `hub.log`. `hub.log` is for people; this
+file is for tools (`ahub export`, `ahub report`, research measurements). The
+version is bumped only when a field changes meaning or goes away; new fields and
+new event types do not bump it.
+
+Every event has `v` (schema version), `at` (ISO time) and `type`. No event ever
+carries a message body or a task title or detail. Private (PII) envelopes are
+marked `private: true`, and PII tasks `pii: true`.
+
+| type | fields |
+|---|---|
+| `envelope` | `id`, `from`, `to` (absent for broadcast), `priority`, `hop`, `kind`, `task` (task id from refs), `bytes` (UTF-8 size of the body; absent on a private envelope, whose size would say something about the PII text), `private`, `dropped` (`hop` or `fyi` when not delivered) |
+| `overflow`, `undeliverable` | `id`, `from`, `peer` |
+| `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) |
+| `task` | `id`, `event` (the board history event, e.g. `proposed`, `assigned`, `done`, `check failed`), `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) |
+
+Token usage by adapter:
+
+- Kimi (ACP `usage_update`): recorded.
+- Codex (app-server `thread/tokenUsage/updated`): recorded as the growth of the thread's running total, so
+  compaction estimates, usage-limit refreshes and the replay to a reattaching connection add nothing. A thread
+  started under the hub counts from zero; a resumed thread's first update is its history and only sets the
+  baseline. The model call of a compaction itself is real usage and counts.
+- Claude: not recorded. The status line tee carries quota percentages only; per-turn
+  tokens would need transcript parsing.
+- Pi and the local worker: not recorded.
+
+The file is local and never uploaded. It grows without rotation; delete it to start
+over (the hub recreates it).

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.7.11 and control protocol 10. Live verification
+This guide describes ahub 0.8.1 and control protocol 10. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Install and start
@@ -89,9 +89,16 @@ the routing configuration.
 
 An agent can claim work nobody assigned it by proposing a task with itself as
 owner; without a class, and with no model to name one, the claim is filed as
-`implement`. When a task's paths overlap another owner's open task, the newcomer
-is told to settle it and the earlier owner gets one line with its next message,
-at no turn of its own. An owner offline longer than `tasks.release_after_min`
+`implement`. A claim or an accept can carry a plan: the files, symbols and
+signatures it will change and where new code goes (`ahub task show <id>` prints
+it). When a task's paths, or its plan's paths or symbols, overlap another
+owner's open task, the newcomer is told to settle it and the earlier owner gets
+one line with its next message, the plan included, at no turn of its own. When a
+task is done (after its check passes, when one is configured), the owners of
+open tasks on the same paths or symbols get a message with the changed files,
+the plan's signatures and the first line of the summary, each left out when it
+matches a PII pattern; nobody else does. PII
+tasks are left out on both sides. An owner offline longer than `tasks.release_after_min`
 (default 30, `0` turns it off) in `.agenthub/config.json` loses its open tasks
 to a peer routing can give them to; with nobody to take them they stay, and a
 paused peer or a hub in a recovery operation is left alone.
@@ -109,6 +116,75 @@ to attached peers. `[IMPORTANT]` can bypass batching where the peer supports
 it; `[STATUS]` may batch, and `[FYI]` is recorded without follow-on
 delivery. A delivery or answer is not a task completion receipt.
 
+## Telemetry: export and report
+
+The hub writes structured events to `.agenthub/state/events.jsonl` alongside
+`hub.log` (schema: `docs/events.md`). They carry ids, routing, sizes, states and
+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 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.
+
+## Turns and undo
+
+In a git work tree the hub snapshots the project's tracked and unignored files (the
+project directory only, when it is part of a larger repository) when a peer
+turns busy and again when it stops. The snapshots are git tree objects written
+through a temporary index, so your index, HEAD and branches stay as they are. The
+files a turn changed are the difference between its two snapshots, which counts
+changes made by shell commands as well as edits. The last 20 turns per peer are
+kept (`"snapshots": { "enabled": true, "keep": 20 }` in `.agenthub/config.json`).
+Snapshots are on in any project with a config file, including one written before
+0.8.0 without a `snapshots` block, and off without one; set `"enabled": false`
+to opt out.
+
+```bash
+ahub turns                        # recent turns of every peer and the files each changed
+ahub turns codex --limit 5
+ahub undo <turn>                  # lists what it would restore; changes nothing
+ahub undo <turn> --yes            # puts those files back as they were when the turn started
+ahub undo <turn> --yes --context  # Codex's latest turn: also drop it from Codex's conversation
+```
+
+- A turn's files are everything that changed in the project while it ran,
+  whoever changed them: the hub cannot tell Claude's or your edits made during
+  the turn from the peer's own.
+- `ahub undo` refuses the whole turn, naming the files, when a file it changed
+  has changed again since the turn ended (by anyone; modes, symlinks and a
+  directory in a deleted file's place count), or when another peer's turn that
+  ran at the same time changed it too, so the change may be theirs. It also
+  refuses while such an overlapping turn's changes are unknown (still running,
+  cut short by a stop, a failed snapshot, a PII turn, or pruned records).
+  Nothing is restored then. It plans again right before restoring and stops if
+  anything moved meanwhile. A turn that is already undone says so.
+- A file the turn created is deleted; a file it deleted comes back.
+- `--context` asks Codex (`thread/revert`) to drop the turn, and every later one,
+  from its thread's saved history before the files are restored; Codex receives
+  nothing while that runs. It changes no file itself, works only on Codex's
+  latest recorded turn while Codex is idle, and is logged in hub.log. Whether
+  Codex's running session also forgets the turn, or only its saved history, is
+  still to be checked against a live Codex (docs/smoke.md).
+- A turn of a peer that holds an open PII task (assigned, accepted or sent
+  back) is not snapshotted, so it cannot be undone. Another peer's turn that
+  starts or ends meanwhile snapshots the whole project, a PII file the worker
+  has not removed yet included, and a PII file left in the project is
+  snapshotted by later turns like any other file. Keep PII files in an ignored
+  directory.
+- A turn the hub stopped in the middle of shows as `(no end snapshot)` and
+  cannot be undone.
+- Claude's turns are not recorded: its channel shows the hub no turn boundary.
+  Claude Code's own checkpoints cover its edits, though not its shell commands.
+- The snapshots are unreferenced objects in the repository's own object store, so
+  `git gc` prunes them after `gc.pruneExpire` (two weeks by default); undoing an
+  older turn says so.
+- Each `turn_end` event carries `files` and `snapshotMs` (`ahub export`).
+
 ## Approvals and pauses
 
 Inspect permission requests in the terminal:
@@ -226,8 +302,8 @@ source and carries every recovery fix released up to it. Protocol 8 and older
 project directory, without replacing the global CLI first:
 
 ```bash
-bunx --package @staix/agent-hub@0.7.11 ahub upgrade --to 0.7.11 --dry-run
-bunx --package @staix/agent-hub@0.7.11 ahub upgrade --to 0.7.11 --yes
+bunx --package @staix/agent-hub@0.8.1 ahub upgrade --to 0.8.1 --dry-run
+bunx --package @staix/agent-hub@0.8.1 ahub upgrade --to 0.8.1 --yes
 ```
 
 | Running now | Coordinator to use |
@@ -237,7 +313,12 @@ bunx --package @staix/agent-hub@0.7.11 ahub upgrade --to 0.7.11 --yes
 | 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 |
 
-Do not use an older installed CLI as the coordinator. A 0.6.x CLI cannot target
+Do not use the 0.8.0 coordinator for a running 0.7.x hub with tasks on its board:
+its verification never matches the board and the operation stays blocked (fixed
+in 0.8.1). Such a blocked operation can neither resume nor abort, and its lock
+refuses `up` and `kill` for every project; the [smoke ledger](smoke.md) (0.7.11
+to 0.8.0) records the manual cleanup. Do not use an older installed CLI as the
+coordinator. A 0.6.x CLI cannot target
 protocol 10: its plan does not check the target's protocol, so the dry-run shows
 no blocker, and `--yes` stops at staging ("target protocol requires a newer
 coordinator") with an operation left to clear by `ahub recovery abort <id>`. An
@@ -249,19 +330,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.7.11, review the current project or all registered
+Once the installed CLI is 0.8.1, review the current project or all registered
 projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.7.11 --dry-run
+ahub upgrade --to 0.8.1 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.7.11 --yes
+ahub upgrade --to 0.8.1 --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.7.11
+bun add -g github:STAIxBWLB/agent-hub#v0.8.1
 ahub setup
 ```
 

package/docs/security.md

@@ -8,6 +8,8 @@ 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 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.
 - **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`) 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 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: no writes outside the project, its git dir and temp; the home directory is unreadable except toolchains; no `.git/hooks` or `.git/config` writes; no network, loopback included. Without the sandbox there is no `bash` tool.
 - **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.
 - **Secrets stay where they are read.** The gateway key and Cloudflare Access values are read inside the gateway client and go only into request headers: never into logs, errors, envelopes, tool output, memory, or the generated Switchyard config (the key travels by environment variable name). Subscription logins of Claude, Codex and Kimi are never proxied or pooled.

package/docs/smoke.md

@@ -847,3 +847,39 @@ the claim overlap warnings (0.7.6 and later), then the owner decides in issue #8
 | Week of | Warnings | Task pairs | Pairs with a conflicting edit | Notes |
 |---|---|---|---|---|
 | 2026-09-28 | 0 | 0 | 0 | baseline counted on 2026-09-30 over every registered project; the issue #68 live run's project was already removed |
+
+## Per-turn snapshots (issue #33, 2026-10-01)
+
+- AC1, measured on a clone of this repository (156 tracked files; Apple M5 Max,
+  git 2.55.0) with 10 turns that each change three files: a snapshot takes 16.8 ms
+  median, 47.6 ms max; each turn adds 68 KiB of loose objects. A turn that changes
+  nothing writes no objects.
+- Live leg, pending: `ahub undo <turn> --yes --context` against a real Codex TUI,
+  checking that the TUI drops the reverted turn from its view on `thread/reverted`,
+  and that Codex's running session no longer knows the turn (ask it about the
+  reverted turn): the schema says `thread/revert` changes only the saved history.
+
+## 0.7.11 to 0.8.0 attended upgrade (2026-10-01)
+
+A scratch project (a git work tree whose `.agenthub/config.json` predates 0.8.0
+and has no `snapshots` block) ran a 0.7.11 hub with one proposed task and no
+peers attached.
+
+- `bunx --package @staix/agent-hub@0.8.0 ahub upgrade --to 0.8.0 --dry-run`
+  exited 0: one project, source 0.7.11, protocol 10, no blockers.
+- `--yes` prepared and committed the source, started the 0.8.0 target and
+  reached the restored-peers phase (no peers were attached), then stopped at
+  verification: `phase: blocked`, "queue,
+  manual pause, task board or budget preservation was not verified". The
+  global CLI stayed at 0.7.11.
+- Cause: the 0.7.11 source digested its task rows without `plan`, and the
+  0.8.0 target's rows carry `plan: {}` after the #31 migration, so any board
+  with a task failed the check. Fixed in 0.8.1 (#57).
+- The blocked operation could not resume (the same target fails the same
+  check) or abort (the source was already stopped), and its recovery lock
+  refused `up` and `kill` for every project. The scratch hub was stopped under
+  the operation's environment, and the operation was marked cancelled with its
+  lock released: an operator step, not a designed path.
+- The release gate for v0.8.0 (Actions run 36807880478) failed once on
+  "removing a running project is refused"; the rerun passed and published. Cause: `ahub kill` returned before
+  the hub released its registry claim. Fixed in 0.8.1 (#58).

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

@@ -839,3 +839,85 @@ session modes (`default`, `plan`, `auto`, `yolo`) but nothing per server or tool
   start, `ahub codex` and `ahub models` print it, `ahub doctor` shows a row.
   `ahub init` adds `.agenthub/config.local.json` to `.gitignore`.
 - `routing.toml` and the shared fields still come from the checkout.
+
+## Amendment: telemetry export (issue #40)
+
+- The daemon appends structured events to `.agenthub/state/events.jsonl` (schema
+  version 1, `docs/events.md`): envelopes (no bodies), overflow and undeliverable,
+  peer states, turns with per-turn tokens where the adapter reports them (Kimi,
+  Codex), board changes (ids and states, no titles), overlap records and quota
+  readings. Writes never throw.
+- `ahub export [--since]` prints the events; `ahub report [--since] [--json]`
+  summarizes them. Both read the file directly, so the control protocol is
+  unchanged. Bodies are never exported (the issue's `--with-bodies` option was
+  dropped: the file never holds them).
+- Codex tokens are the growth of each thread's `total`, with the baseline kept in
+  the adapter: Codex 0.156.1 also sends `thread/tokenUsage/updated` for
+  compaction, usage-limit refreshes and a replay to a reattaching connection,
+  where `last` is not new usage. A thread adopted from `thread/start` counts from
+  zero; one adopted from `thread/resume` takes its first total as the baseline.
+  Kimi reports a session total, which is turned into increments per session.
+- Not in schema 1: per-delivery events and delivery-journal transitions, which
+  the issue's design listed. `ahub queue list` and hub.log keep them; a later
+  schema version can add them without changing the meaning of a field.
+
+## Amendment: per-turn snapshots and undo (issue #33)
+
+- Backend: git tree objects only, written through a copy of the index
+  (`GIT_INDEX_FILE`) with `add -A` minus `.agenthub/state`, then `write-tree`. The
+  user's index, HEAD and refs are untouched. The issue's APFS `clonefile` and
+  reflink backends were not built: on this repository a snapshot takes 17 ms
+  (median) and a three-file turn adds 68 KiB of loose objects, and git objects
+  already deduplicate unchanged files.
+- Snapshots are taken inside the state transition, before the peer is handed its
+  prompt. Turn records (`turns` table in hub.db) keep the last `snapshots.keep`
+  per peer. `DEFAULT_CONFIG` has snapshots off, like approvals.notify; a project
+  config turns them on.
+- `ahub undo` refuses the whole turn when any of its files changed since it
+  ended (a file-by-file partial undo would leave a mixed state).
+- Codex: the method is `thread/revert {threadId, beforeTurnId}` (codex-cli
+  0.156.1; there is no `thread/rollback`). It changes conversation history only.
+  The CLI asks for it with `--context` (off by default) through the console task
+  op `turn_revert`, a new op name on an existing message shape.
+- Claude's turns are not recorded: the channel has no turn boundary.
+- Not built from the issue's design: a disk cap (the objects stay until `git gc`;
+  `snapshots.keep` prunes only the records) and 0700 snapshots (the objects carry
+  the repository's own permissions).
+- After review: the undo plan reads the current state with one more snapshot
+  and refuses a path when anything at or under it differs from the turn's end
+  tree, or when another peer's turn that overlapped this one in time changed it;
+  paths reach git as `:(literal)` pathspecs; the plan is made again right before
+  restoring; snapshots cover the project prefix only and run with a 10 s git
+  timeout; turns of a peer holding an open PII task (any state before review)
+  are recorded without snapshots; turns left open by a stopped hub are closed at
+  the next start without an end snapshot; undo refuses while an overlapping
+  turn's changes are unknown; removals run before restorations (a case-only
+  rename on a case-insensitive disk); Codex receives nothing while
+  `thread/revert` runs.
+
+## Amendment: plans and completed-change notices (issue #31)
+
+- A plan is a JSON column on `tasks` (`paths`, `symbols`, `signatures`,
+  `insertion_points`, each a list of short strings), not part of `refs`: refs ride
+  on every task envelope. A plan on accept replaces the old one whole. Boards
+  from before 0.8 get the column on open.
+- A plan's text counts for PII detection when a task is proposed. On accept the
+  task's signals are fixed, so a plan that matches a PII pattern is refused for
+  an ordinary task.
+- Overlap: paths from refs and plan (same file or a directory of it), or the
+  same symbol named in both plans. An overlap that only the new plan reveals on
+  accept is announced like one found at assignment (console notice and overlap
+  event); one already announced is not announced again, but the other owner
+  still gets the new plan.
+- The completed-change notice is a normal-priority `task` envelope of its own,
+  not a ride-along line: an owner in the middle of those files needs it before
+  its next task arrives. It lists the files from refs and plan and the plan's
+  signatures, as declared; the hub does not read the diff.
+- After review: during a PII turn, `hub_task_done`, `hub_review` and
+  `hub_task_accept` with a plan are refused for an ordinary task (its plan,
+  summary or note would reach other peers and claude-mem), as `hub_remember`
+  and `hub_task_propose` already were. Model-written refs and plan items are one
+  line (whitespace collapses), so none can forge a hub.log line; a `null` or
+  empty plan on accept keeps the plan there is. The completed-change notice
+  leaves out any file, signature or summary line that matches a PII pattern.
+

package/package.json

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

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

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

package/plugins/agent-hub/server.js

@@ -15727,7 +15727,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.7.11",
+  version: "0.8.1",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",
@@ -15797,14 +15797,26 @@ var refs = {
   properties: { branch: str, commit: str, paths: { type: "array", items: str } },
   additionalProperties: false
 };
+var list = (description) => ({ type: "array", items: str, description });
+var plan = {
+  type: "object",
+  description: "what you will change, before you start. Owners of open tasks on the same files or symbols see it, and get a notice when your task is done.",
+  properties: {
+    paths: list("files you will edit or create"),
+    symbols: list("functions, types or other names you will change, as they appear in code (e.g. Bus.publish)"),
+    signatures: list("new or changed signatures, as you will write them"),
+    insertion_points: list("where new code goes (file and the function or line it follows)")
+  },
+  additionalProperties: false
+};
 var tool = (name, description, properties, required2 = []) => ({
   name,
   description,
   inputSchema: { type: "object", properties, required: required2, additionalProperties: false }
 });
 var TASK_TOOLS = [
-  tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, refs, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it" } }, ["title"]),
-  tool("hub_task_accept", "Take a task that was assigned to you.", { id }, ["id"]),
+  tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it" } }, ["title"]),
+  tool("hub_task_accept", "Take a task that was assigned to you, with your plan for it.", { id, plan }, ["id"]),
   tool("hub_task_decline", "Pass on a task assigned to you; the hub offers it to the next peer.", { id, reason: str }, ["id"]),
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested"] } }),
@@ -15815,7 +15827,7 @@ var TASK_TOOLS = [
 var TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));
 var ROLE_TEXT = {
   planner: "planner: break work into tasks with hub_task_propose (one outcome each, the right class, paths in refs) instead of doing everything yourself.",
-  implementer: "implementer: accept tasks assigned to you, do them, and finish with hub_task_done (summary: what changed, why, and the check you ran with its result; refs). Decline what you cannot do. Before starting work nobody assigned you, claim it with hub_task_propose naming yourself as owner, with the paths in refs.",
+  implementer: "implementer: accept tasks assigned to you, do them, and finish with hub_task_done (summary: what changed, why, and the check you ran with its result; refs). Decline what you cannot do. Before starting work nobody assigned you, claim it with hub_task_propose naming yourself as owner, with the paths in refs. With a claim or an accept, give a plan: the files, symbols and signatures you will change and where new code goes.",
   verifier: "verifier: run the checks a task names and report what passed and what did not in hub_task_done.",
   reviewer: "reviewer: when asked to review, read the change itself, then hub_review with approved or changes_requested and a note that says what to fix."
 };

package/src/adapters/acp.ts

@@ -31,7 +31,7 @@ export interface AcpOptions {
   /** Appended to the standing instruction of the first delivery (role contract). */
   preamble?: string;
   /** The session's running token total from `usage_update` (inferred shape: totalTokens, else input + output, else `used`). Cumulative, not a delta. */
-  onTokens?: (sessionTotal: number) => void;
+  onTokens?: (sessionTotal: number, sessionId: string) => void;
   /** Resolve with an optionId, or undefined to cancel. Absent = every request is cancelled.
    *  A request whose payload could not be resolved is titled as such and carries no session-wide allow option. */
   onPermission?: (req: PermissionRequest) => Promise<string | undefined>;
@@ -212,7 +212,7 @@ export class AcpPeer extends BasePeer {
         const f = { ...u, ...(typeof u.usage === "object" ? u.usage : {}) } as Record<string, unknown>;
         const num = (k: string) => (typeof f[k] === "number" ? (f[k] as number) : 0);
         const total = num("totalTokens") || num("total_tokens") || num("inputTokens") + num("outputTokens") || num("input_tokens") + num("output_tokens") || num("used");
-        if (total > 0) this.opts.onTokens(total);
+        if (total > 0) this.opts.onTokens(total, this.sessionId);
       }
     } else if (msg.method === "session/request_permission") {
       void this.answerPermission(msg);

package/src/adapters/codex-appserver.ts

@@ -18,6 +18,10 @@ export interface CodexOptions {
   preamble?: string;
   /** Raw `rateLimits` snapshots from app-server, and `hard = true` when a turn was refused for quota. */
   onUsage?: (rateLimits: unknown, hard: boolean) => void;
+  /** Tokens the thread used since the previous update (see `tokenTotal` for how they are counted). */
+  onTokens?: (added: number) => void;
+  /** The native id of each turn as it starts, after the peer turned busy (issue #33: `ahub undo --context`). */
+  onTurn?: (turnId: string) => void;
   /** How often to ask app-server for the rate limits while a TUI is attached. */
   usagePollMs?: number;
   cwd: string;
@@ -49,6 +53,14 @@ export class CodexPeer extends BasePeer {
   /** Claimed as soon as a TUI WebSocket opens, before it can start a thread. */
   private claimedTui: Link | undefined;
   private threadId = "";
+  /**
+   * The thread's running token total at the last update, and whether the thread started here. Codex 0.156.1 also
+   * sends `thread/tokenUsage/updated` for compaction (an estimate in `last`, `total` unchanged), a usage-limit refresh
+   * and a replay to a connection that attaches, so `last` is not always new usage; differences of `total` are. A
+   * resumed thread's first update only sets the baseline: its total holds the history from before (issue #40).
+   */
+  private tokenTotal: number | undefined;
+  private freshThread = false;
   private readonly activeTurns = new Set<string>();
   private nextId = -1;
   private readonly pending = new Map<number, { resolve: (result?: any) => void; reject: (e: Error) => void; deliveryId?: string; kind?: "deliver" | "steer" }>();
@@ -327,17 +339,20 @@ export class CodexPeer extends BasePeer {
     if (typeof msg.id === "number" && msg.id < 0 && !msg.method) {
       const p = this.pending.get(msg.id);
       this.pending.delete(msg.id);
-      if (msg.error) p?.reject(new Error(msg.error.message ?? "turn/start rejected"));
+      if (msg.error) p?.reject(new Error(msg.error.message ?? "app-server rejected the request"));
       else p?.resolve(msg.result);
       return; // ours: the TUI never asked for it
     }
-    if (msg.id !== undefined && !msg.method && link.tracked.delete(msg.id)) this.adopt(link, msg.result?.thread?.id);
+    const tracked = msg.id !== undefined && !msg.method ? link.tracked.get(msg.id) : undefined;
+    if (tracked && link.tracked.delete(msg.id)) this.adopt(link, msg.result?.thread?.id, tracked === "thread/start");
     else if (msg.method) this.onNotification(link, msg.method, msg.params ?? {});
     link.tui.send(raw);
   }
 
-  private adopt(link: Link, threadId: unknown): void {
+  private adopt(link: Link, threadId: unknown, fresh = false): void {
     if (typeof threadId !== "string" || !threadId) return;
+    this.tokenTotal = undefined;
+    this.freshThread = fresh;
     this.link = link;
     this.threadId = threadId;
     this.activeTurns.clear();
@@ -350,6 +365,22 @@ export class CodexPeer extends BasePeer {
     this.usageTimer.unref?.();
   }
 
+  /**
+   * thread/revert through the TUI's connection (issue #33): drops `turnId` and every later turn from the conversation
+   * history. It touches no file; `ahub undo` restores those. The TUI sees the `thread/reverted` notification.
+   */
+  revert(turnId: string): Promise<void> {
+    const link = this.link;
+    if (this.state !== "idle" || !link || link.up.readyState !== WebSocket.OPEN) return Promise.reject(new Error(`${this.id} is not idle`));
+    const id = this.nextId--;
+    return new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => this.pending.delete(id) && reject(new Error("thread/revert got no answer")), 30_000);
+      timer.unref?.();
+      this.pending.set(id, { resolve: () => (clearTimeout(timer), resolve()), reject: (e) => (clearTimeout(timer), reject(e)) });
+      link.up.send(JSON.stringify({ method: "thread/revert", id, params: { threadId: this.threadId, beforeTurnId: turnId } }));
+    });
+  }
+
   /** account/rateLimits/read through the TUI's connection, with a hub id so the answer never reaches the TUI. */
   private readUsage(): void {
     const link = this.link;
@@ -367,12 +398,21 @@ export class CodexPeer extends BasePeer {
       this.opts.onUsage?.({ rateLimitReachedType: "usageLimitExceeded" }, true);
     }
     if (link !== this.link || params.threadId !== this.threadId) return;
+    if (method === "thread/tokenUsage/updated") {
+      const total = Number(params.tokenUsage?.total?.totalTokens);
+      if (!Number.isFinite(total)) return;
+      const added = this.tokenTotal === undefined ? (this.freshThread ? total : 0) : Math.max(0, total - this.tokenTotal);
+      this.tokenTotal = total;
+      if (added > 0) this.opts.onTokens?.(added);
+      return;
+    }
     if (method === "turn/started") {
       const nativeTurn = params.turn?.id ?? `unknown:${Date.now()}`;
       this.activeTurns.add(nativeTurn);
       for (const id of [...this.unboundDeliveries]) this.addTurnDelivery(nativeTurn, id);
       this.lastAnswer = "";
       this.setState("busy");
+      if (params.turn?.id) this.opts.onTurn?.(params.turn.id);
     } else if (method === "item/agentMessage/delta") {
       const buf = this.deltas.get(params.itemId) ?? [];
       buf.push(params.delta);