@staix/agent-hub 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.
 
+## 0.10.0
+
+- Review checklists and review outcomes: review requests ask the reviewer to map signatures and call sites to the plan, read the check result and list unmet items (`hub_review {unmet}`); the hub records approved, caught, contradicted and escalated reviews per implementer, reviewer and class, shown by `ahub task show` and `ahub route explain`, and `review.adaptive` (off by default) orders reviewers by that record, after idle before busy and ahead of quota. A record counts tasks, a catch belongs to the owner whose work was caught, and only a failure on the same file or symbol contradicts an approval (#35).
+- Recovery after an unplanned stop: the hub keeps each attached peer's session identity while it runs; a hub started after a crash reports what happened to each peer in `ahub status`, resumes Kimi (ACP `session/load`), a headless Pi and the local worker (on its recorded route) when `recovery.auto_resume_after_crash` is on, and gives each peer a notice of its deliveries left in `needs_review` with its next delivery. A stop someone asked for, even one past the shutdown deadline, is not taken for a crash (#37).
+- The local worker's sandbox starts from deny default: commands may run and read the system, toolchain and project directories (and the selected Xcode or Command Line Tools dir) and write the project and temp, nothing else; `/Applications`, `/nix`, `/Volumes` and `/Users/Shared` now need `local.read_allow`; `local.sandbox: "allow-default"` (machine-local) keeps the profile of 0.9 and earlier for one release; with network on, the public CA bundles stay readable for TLS. Per-peer `capabilities` (`propose`, `assign`, `remember`, `important`) are enforced by the daemon, a malformed entry grants nothing and every refusal is logged, under deny-default the worker's commands can no longer reach the LaunchServices, CoreServices or SecurityServer brokers, and a test pins that a peer can never answer a permission request (#39).
+
+## 0.9.0
+
+- Early conflict detection: in a git work tree, a turn that changes a file another owner's open task changed earlier warns both owners (and the console, and `events.jsonl`), once per file and task, marked concurrent when another peer worked meanwhile. `ahub check-path` and the PreToolUse hook template `templates/claude-hooks.json` give Claude the same warning before an edit, without blocking it (#32).
+- Task dependencies: `hub_task_propose` takes `after: [ids]`; a task waits, offered to nobody and not claimable, until those are approved, then goes through assignment (a task the hub stopped before offering is offered once it runs again). `hub_task_list {ready: true}` and `ahub board --ready` show the ready queue, and existing boards gain the column on open (#34).
+- Quota-aware routing: candidates with quota readings are ordered by headroom per hour to their reset, so the window that resets first is drained first; a paused peer whose window resets within `budget.wait_max_min` (30 with a project config) keeps its work unless a task is `urgent`; and a peer whose recent failures in a class outweigh its approvals there is demoted for that class, with a one-day half-life. `ahub route explain` shows both, and `ahub task propose ... --urgent` marks a task urgent (#36).
+- Per-sender limits on what agents send: token buckets per sender, per recipient and for `[IMPORTANT]`, plus dropping the same text to the same recipients, answering the same message, within a window. A refused `hub_send` answers with the reason and the seconds to wait; a turn answer over the important budget goes out as status, and one over a rate limit is dropped, the agent hearing why with its next delivery. `[FYI]` and the console user are never limited (#38).
+- An upgrade or controlled restart from a 0.9.0 or later source waits for completion checks and console task operations still in flight; one that finished after the commit used to leave the operation blocked at verification, unable to resume or abort. A 0.8.x or older source cannot report them: wait for its checks by hand before upgrading (see the operations guide) (#50).
+- Upgrading a running 0.7.x or 0.8.x hub with tasks on its board verifies the board although 0.9.0 adds the `deps` column, like 0.8.1 did for `plan` (#50).
+- Turn snapshots no longer miss an edit that keeps a file's size and lands in the second git last wrote the index: the snapshot's copy of the index now keeps the original's time, which git's racy-entry check compares against in whole seconds. A missed edit could leave a file out of `ahub undo`, let undo restore over another agent's later change, or skip an early conflict warning (#60).
+
 ## 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).

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.8.1, control protocol 10. Durable delivery records distinguish queued
+Status: 0.10.0, 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.8.1 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.10.0 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.

package/docs/events.md

@@ -18,9 +18,10 @@ marked `private: true`, and PII tasks `pii: true`.
 | `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` |
+| `task` | `id`, `event` (the board history event, e.g. `proposed`, `assigned`, `done`, `check failed`, `blocked`, `ready`), `by`, `state`, `owner`, `reviewer`, `class`, `pii` |
 | `overlap` | `task`, `owner`, `others` (`task`, `owner`, `paths`, and `symbols` when plans name the same symbol; a name that matches a PII pattern is left out, so either list can be empty), the structured twin of the console notice |
 | `quota` | `peer`, `windows` (`id`, `used`, `resetsAt`), `hard`, `measuredAt` (when the reading was taken, if not when it arrived: Claude's numbers come through a file) |
+| `conflict` | `peer`, `task` (its task in progress, when it had one), `other` (the other owner's open task), `owner`, `paths` (names that match a PII pattern left out, so it can be empty), `concurrent` (another peer worked during the turn) |
 
 Token usage by adapter:
 

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.8.1 and control protocol 10. Live verification
+This guide describes ahub 0.10.0 and control protocol 10. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Install and start
@@ -27,11 +27,38 @@ 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`) are machine-local: they apply only
-from a file git confirms nobody committed. Put them in
+`local.read_allow`, `local.bash_network`, `local.sandbox`) 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
 an empty value always means the default.
+
+The local worker's commands run under a sandbox that starts from deny default
+(0.10): they may run and read the system, toolchain and project directories and
+the selected Xcode or Command Line Tools dir (`xcode-select -p`), write the
+project and temp, and nothing else. With `local.bash_network` on they may also
+read the public CA bundles, which the `*.pem` key deny would otherwise hide.
+`"local": { "sandbox": "allow-default" }` in `config.local.json` brings back the
+profile of 0.9 and earlier for one release, should a toolchain need a path the
+new one lacks; please report it. Newly closed outside home: `/Applications`
+(an app's bundled CLI), `/nix`, `/Volumes` and `/Users/Shared`. A toolchain
+there, or elsewhere in your home (a CI tool cache, a version manager the profile
+does not list), needs its directory in `local.read_allow`, for example
+`"/nix"` or `"~/.pixi"`.
+
+`capabilities` in `.agenthub/config.json` narrows what a peer may do with the
+hub's tools: list a peer and it keeps only the capabilities named, from
+`propose` (`hub_task_propose`), `assign` (proposing with another peer as owner),
+`remember` (the `hub_remember` tool; the notes the hub itself keeps of done
+summaries and review verdicts are not gated) and `important` (`[IMPORTANT]`
+messages). For example `"capabilities": { "local": ["propose", "remember"] }`.
+A peer that is not listed keeps all of them, a listed peer whose value is not a
+list gets none, and an unknown capability name grants nothing; `hub.log` says
+so for each, and logs every refusal (`capabilities:`). A refused tool call says
+which capability is missing; an `[IMPORTANT]` turn answer without the
+capability goes out as status, with a note to the sender.
+Approvals are never a capability: only the console (and the dashboard) answers a
+permission request.
 A committed value is ignored with a line in `hub.log`, a note from `ahub
 codex` and `ahub models`, and a row in `ahub doctor`.
 
@@ -87,6 +114,21 @@ external side effect happened unless the task's refs and a live readback show
 that effect. The hub can reassign after repeated review changes according to
 the routing configuration.
 
+A review request carries a checklist: map the changed signatures and call sites
+to the task's plan (without one, to its detail, which the request then
+includes), read the check result, and list what is
+unmet (`hub_review` takes `unmet`, `ahub review ... --unmet <item>`). The hub
+records how each review turned out, per implementer, reviewer and class:
+approved; caught (changes were requested and the owner's redo was approved);
+contradicted (within a week, work on the same file or symbol failed its check
+or review); escalated (after the reviewer asked for changes). A record counts
+tasks, not verdicts. `ahub task show <id>` lists a task's outcomes and `ahub
+route explain` shows each reviewer's record with the implementer. With
+`"review": { "adaptive": true }` in `.agenthub/config.json`, reviewers with at
+least `min_reviews` (5) reviews of that implementer in the class are ordered by
+how their reviews held up, ahead of quota but after idle before busy; off by
+default, which leaves assignment as it was.
+
 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`. A claim or an accept can carry a plan: the files, symbols and
@@ -98,7 +140,20 @@ 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`
+tasks are left out on both sides.
+
+A task can wait for others: `hub_task_propose` takes `after: [ids]` (`ahub task
+propose ... --after <id>`). Until every one of them is approved, the task is
+offered to nobody, cannot be claimed, accepted or marked done, and `ahub route
+explain <id>` says what it waits for. When the last one is approved, the task
+goes through assignment like a new one; if the hub stopped before it got that
+far, the task is offered within a minute of a peer that can take it attaching
+to the next run.
+`ahub board --ready` and
+`hub_task_list {ready: true}` list the proposed tasks with nothing left to wait
+for. Dependencies are fixed when a task is proposed and can only name tasks that
+already exist, so they cannot form a cycle. A waiting task cannot name an owner;
+use `ahub task assign` once it is ready. 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.
@@ -111,6 +166,27 @@ ahub say @claude "[STATUS] the test run is complete"
 ahub say @kimi "[FYI] the result is recorded"
 ```
 
+What agents send is limited per sender (`limits` in `.agenthub/config.json`; a
+project config gets the values below unless it sets others, `0` turns one off):
+
+- `sender_per_min` (12) messages a minute from one agent, `pair_per_min` (6) to
+  one recipient (a broadcast counts as one), and `important_per_hour` (6)
+  `[IMPORTANT]` messages, each of which can interrupt a running turn. Limits
+  count what is sent: a reply goes to the agent it answers, a reply to a
+  condensed digest counts against the agents behind it, and an `[IMPORTANT]` the
+  hub lowers to status is not important. `[FYI]` costs nobody a turn and is
+  never limited.
+- `repeat_window_s` (120): the same text to the same recipients, answering the
+  same message, again within the window is dropped. "Yes." to two different
+  questions is two messages.
+- A refused `hub_send` answers `not sent: <why>`, with the seconds to wait for a
+  rate limit, so the agent learns at once. A turn answer has nobody to refuse
+  to: one over the important budget goes out as status, and one over a rate
+  limit or repeated is not published; either way the agent gets the reason with
+  its next delivery, and has to send a dropped answer again. hub.log records
+  each refusal (`limits:`), and a value that is not a number falls back to the
+  default above. The console user and the hub itself are never limited.
+
 `@peer` addresses one known peer. With no recipient, `ahub say` broadcasts
 to attached peers. `[IMPORTANT]` can bypass batching where the peer supports
 it; `[STATUS]` may batch, and `[FYI]` is recorded without follow-on
@@ -185,6 +261,34 @@ ahub undo <turn> --yes --context  # Codex's latest turn: also drop it from Codex
   older turn says so.
 - Each `turn_end` event carries `files` and `snapshotMs` (`ahub export`).
 
+## Edit conflicts
+
+With snapshots on, the hub also compares each turn's files with what other
+owners' open tasks changed before it. A turn's files count for every task its
+peer has in progress, except files that another peer's overlapping turn changed;
+while such a turn's changes are unknown (it still runs), the turn's files count
+for none. When a peer changes a file that another owner's open task changed
+earlier, both get a message naming the file and the other task, the console
+shows a `conflict:` line, and `events.jsonl` records a `conflict` event (`ahub
+report` counts them). Each peer, task and file is reported once per hub run.
+When another peer worked during the same turn, the messages say so: the change
+may be theirs. Edits by Claude or by you during a peer's turn count as that
+peer's, without that note: the hub sees no turn of yours. Nothing is blocked. A
+file only one agent touched, and anything to do with a PII task, warns nobody.
+A file whose name matches a PII pattern is not named, as in overlap notices: the
+messages and the console line only count such files, and the event leaves them out.
+
+Claude's edits do not pass through turn snapshots, so Claude can ask before each
+edit instead. `templates/claude-hooks.json` is a PreToolUse hook for Edit, Write,
+MultiEdit and NotebookEdit that runs `ahub check-path --hook`. Merge it into
+`.claude/settings.local.json` (or your user settings) yourself. When another
+owner's open task claims the file (refs or plan paths) or changed it, Claude gets
+the list with the tool result and you see one line. The hook never decides a
+permission, so your permission rules apply as before. Task titles in the list
+are quoted and marked as other agents' text. The hook runs `ahub`, so it has to
+be on the PATH Claude Code's hooks see; otherwise every edit shows a hook error
+(it never blocks). `ahub check-path <file>` prints the same list in a terminal.
+
 ## Approvals and pauses
 
 Inspect permission requests in the terminal:
@@ -215,6 +319,25 @@ A budget pause remains authoritative until the budget command explicitly
 overrides it or the window resets. Check `ahub status` and `ahub board` after
 a pause or handoff.
 
+Quota also shapes routing and handoffs:
+
+- Among peers a task could go to, those with quota readings are ordered by
+  headroom per hour left until the reset of the window that bounds it (the most
+  used one, so a week window near its cap is not mistaken for a 5 h window about
+  to reset), so the window that resets first is used first. Peers without readings, such as `local` and `pi`, keep
+  their place in `routing.toml`. `ahub route explain` shows the reordering.
+- When a paused peer's window resets within `budget.wait_max_min` (30 once the
+  project has `.agenthub/config.json` or `config.local.json`, 0 without one; `0`
+  always hands over), it keeps its work and only tasks proposed with `urgent`
+  (`ahub task propose ... --urgent`) move. If the reset moves past the limit
+  while it waits (a week window crosses the gate), its work is handed over after
+  all. `ahub budget` shows each decision and why in the pause reason.
+- A peer whose recent failures in a class (failed checks, changes requested,
+  escalations by hand) reach 1.5 after decay, and outweigh its recent
+  approvals there (a task without a reviewer counts when done), goes behind the
+  other candidates in the same state for that class, `local` and `pi` included.
+  A failure counts half after a day. `ahub route explain` names demoted peers.
+
 ## Durable delivery and queue resolution
 
 Protocol 10 records each recipient delivery in the private project journal.
@@ -302,8 +425,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.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
+bunx --package @staix/agent-hub@0.10.0 ahub upgrade --to 0.10.0 --dry-run
+bunx --package @staix/agent-hub@0.10.0 ahub upgrade --to 0.10.0 --yes
 ```
 
 | Running now | Coordinator to use |
@@ -318,36 +441,64 @@ 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
+coordinator. After an upgrade, do not start an older hub on the same project: it
+does not know the newer task columns, and its board readback breaks a later
+upgrade. 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
 older 0.7.x CLI may lack recovery fixes released after it. The
 [smoke ledger](smoke.md) records dry-runs from real 0.6.4 and 0.7.5 hubs (issue
-#75); an applied upgrade was last proven with the 0.7.0 coordinator.
+#75), an applied upgrade with the 0.7.0 coordinator, and one from a running
+0.8.1 hub with tasks and a budget pause with the 0.9.0 coordinator.
 
 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.8.1, review the current project or all registered
+Once the installed CLI is 0.10.0, review the current project or all registered
 projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.8.1 --dry-run
+ahub upgrade --to 0.10.0 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.8.1 --yes
+ahub upgrade --to 0.10.0 --yes
 ahub recovery status <operation-id>
 ahub recovery resume <operation-id>
 ahub recovery abort <operation-id>
 ```
 
+The coordinator commits only once the source is quiet: no turn running, no
+approval pending, no completion check queued or running. It waits up to 10
+minutes and then aborts, leaving the source running; upgrade between long
+checks. A 0.8.x or older source does not report completion checks or console
+task commands in flight, so the coordinator cannot wait for them. Before
+`--yes`, for each task whose check `hub.log` reported as "queued or running",
+wait until `ahub task show <id>` has `check passed`, `check failed` or `check
+finished late` after `done (checking)` (a pass with a peer reviewer writes no
+line of its own to `hub.log`), and until no task command or dashboard action is
+still running. A check the commit's stop kills writes to the board after the
+commit has recorded it, and the operation stays blocked.
+
+0.9.0 turns on for every project with a config file, whether or not it has the
+block: `limits` (12 messages a minute per sender, 6 per recipient, 6
+`[IMPORTANT]` an hour, 120 s repeats) and `budget.wait_max_min` (30). Set them
+to 0 to opt out.
+
+0.10.0 changes every project's local worker: its commands run under the
+deny-default sandbox described above, and a toolchain outside the listed
+directories needs `local.read_allow`; `"local": { "sandbox": "allow-default" }`
+in `config.local.json` restores the old profile for one release. Off unless set:
+`review.adaptive`, `recovery.auto_resume_after_crash` and `capabilities`. A hub
+before 0.10.0 keeps no session record, so a crash of one is not reported as such
+by the next start.
+
 The 0.7.0 transition stages the verified package and runs a retained
 coordinator from the source tree. It accepts a verified protocol-9 source and
 moves to a protocol-10 target. The source journal, queued envelopes, tasks,
@@ -369,6 +520,29 @@ Do not run an upgrade with an incompatible active protocol, an unverified
 terminal binding, or an unresolved operation lock. Dry-run performs no package,
 plugin, daemon, or terminal mutation.
 
+### After an unplanned stop
+
+While it runs, the hub keeps each attached peer's session identity in
+`.agenthub/state/sessions.json` (ids and launch options, no message text); a stop
+removes it as it begins. When a hub starts and finds the file, the previous run
+died (`kill -9`, a crash, a lost machine), and `ahub status` and the console say
+what happened to each peer. Hubs before 0.10.0 kept no such record, so a
+crash of one is not reported this way.
+
+- Deliveries that were in flight are in `needs_review` (`ahub queue list`), as
+  before. When a peer next attaches, its next delivery starts with a notice that
+  lists them by id, sender and task (`[pii]` for a PII task), never their text.
+- Kimi, Pi and the local worker run inside the hub, so they died with it. With
+  `"recovery": { "auto_resume_after_crash": true }` in `.agenthub/config.json` the
+  hub starts them again: Kimi loads its recorded session (ACP `session/load`), Pi
+  resumes its session file, and the local worker starts without its history, on
+  its recorded route (or pinned model). Off by default: the report then says
+  what to start. A Pi that ran in a terminal (`--mode tui`) is never started by
+  the hub; the report gives the command. With `pi.auto_start` and no resume,
+  Pi starts on a fresh session as usual.
+- Codex's app-server died with the hub; run `ahub codex` again. Claude Code's
+  plugin reconnects by itself while that session is open.
+
 ## Evidence and limits
 
 The 0.6.4 release has real measurements in [the smoke checklist](smoke.md):

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.8.1
+bun add -g github:STAIxBWLB/agent-hub#v0.10.0
 ahub setup
 ```
 

package/docs/security.md

@@ -10,7 +10,10 @@ agent-hub connects agents that can each run commands. This page says what the hu
 - **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.
+- **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.
+- **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, the selected developer dir and temp; with network on, the public CA bundles); no writes outside the project, its git dir and temp; no `.git/hooks` or `.git/config` writes; no network, loopback included, unless `local.bash_network`. `local.sandbox: "allow-default"`, machine-local, brings back the profile of 0.9 and earlier for one release. The user's temp dir is still readable in both: a command can read another tool's leftovers there. 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.
 - **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.
 - **The hub's own model calls are fenced.** Digest condensation and task triage read agent-written text as data; their output is capped text framed as untrusted, or a value checked against a closed list. It is never used as a route, a peer id, a tool call or an instruction.

package/docs/smoke.md

@@ -883,3 +883,57 @@ peers attached.
 - 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).
+
+## Edit conflict detection (issue #32, 2026-10-01)
+
+- AC3, on a clone of this repository (156 tracked files) with 10 open tasks of
+  other owners holding 200 touches: the turn-end path (end snapshot, diff,
+  touch query, match) takes 57.6 ms median, 59.6 ms max; the detection part
+  alone (diff, query, match) 7.1 ms median. The machine was under load from
+  other work; the snapshot alone measured 17 ms median earlier the same day.
+- AC4, Claude Code 2.1.286 headless (`claude -p --settings <hook settings>
+  --permission-mode acceptEdits`, model Haiku 4.5) in a scratch repository whose
+  hub.db had kimi's open task claiming `notes.txt`, asked to edit `notes.txt` and
+  quote any agent-hub note:
+  - Runs 2 and 3: the hook fired (logged input and output in run 2), Claude
+    quoted the warning verbatim, and the edit went through under the session's
+    permission mode.
+  - Run 1, before the hook was logged: Claude answered NONE. Whether the hook
+    did not fire or the model left the reminder out was not determined; that run
+    also had no stdin redirect (`< /dev/null`), which runs 2 and 3 had.
+
+## Recovery after an unplanned stop (issue #37, 2026-10-01)
+
+- AC1 baseline, released 0.7.11 in a scratch project, the fake ACP agent standing
+  in for the Kimi binary (`kimi_cmd`), `kill -9` of the daemon:
+  - the ACP child exited with the daemon;
+  - `ahub status` failed to reach the stale manifest's port;
+  - `ahub up` started a hub with no peers attached; nothing recorded Kimi's
+    session, so it could only start a new one.
+- The same run with this branch and `auto_resume_after_crash` on: `ahub up`
+  reported the crash and `kimi resumed: ... session s1 ... (ACP session/load)`,
+  and Kimi was idle on its recorded session id.
+- Pending, needs real accounts: Kimi 2.x (does it offer `loadSession`, and does
+  the resumed session keep its context), Pi with a real session file, and Codex
+  and Claude reattachment after `kill -9`.
+
+## 0.8.1 to 0.9.0 attended upgrade (2026-10-01)
+
+A scratch project (a git work tree whose `.agenthub/config.json` was written by
+the 0.8.1 `ahub init`) ran a 0.8.1 hub with two proposed tasks, one with a path
+and a detail, and an open budget pause: a peer had attached once and gone
+offline, and `ahub budget set` fed it a 95% reading. No completion check was
+configured or running, and no peer was attached at the upgrade.
+
+- `bunx --package @staix/agent-hub@0.9.0 ahub upgrade --to 0.9.0 --dry-run`
+  exited 0: one project, source 0.8.1, protocol 10, no blockers.
+- `--yes` scheduled the operation, which completed in about 10 s with the
+  project `verified`.
+- After release the hub ran 0.9.0 under a new instance id. Both tasks were on
+  the board unchanged, now with `deps: []` (the column the target adds on open),
+  the budget pause kept its reset time, and the `outcomes` table was created.
+- The coordinator promoted the global CLI to 0.9.0, and `ahub setup --yes`
+  installed the 0.9.0 plugin.
+- For about two minutes after the publish step logged `+ @staix/agent-hub@0.9.0`,
+  `npm view` still showed `latest: 0.8.1`; the registry caught up without any
+  action.

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

@@ -921,3 +921,174 @@ session modes (`default`, `plan`, `auto`, `yolo`) but nothing per server or tool
   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.
 
+## Amendment: early conflict detection (issue #32)
+
+- Shared tree only. The issue's worktree mode (pairwise `git merge-tree` between
+  per-agent worktrees, AC2) moves to #41, which provides those worktrees.
+- Attribution reuses the #33 turn snapshots: the files a turn changed are
+  recorded as `touches` (task, peer, path) in hub.db for each task the peer has
+  in progress. A later turn by another peer that changes one of those files, while
+  the task is open, is a conflict. A file touched by one agent only is not, even
+  when its task changed hands. PII tasks are left out on both sides, and a turn of
+  a peer with a PII task in progress is not checked.
+- Notices are normal-priority `task` envelopes to both owners, once per (peer,
+  task, file) per hub run, plus a console line and a `conflict` event.
+  "Concurrent" means another peer had a turn open during this one.
+- The PreToolUse hook template runs `ahub check-path --hook`, which reads hub.db
+  read-only and answers with `hookSpecificOutput.additionalContext` and a
+  `systemMessage`, never a `permissionDecision`. Claude Code adds that context
+  with the tool result, so it warns after the edit is allowed, not before.
+- After review: a turn's touches leave out files an overlapping turn of another
+  peer changed (#33's `Turns.overlapping`), and none are recorded while such a
+  turn's changes are unknown; detection runs after the `turn_end` event; the
+  hook quotes task titles as JSON strings and says they are agents' text; a
+  file name that matches a PII pattern is never named, through the same check as
+  overlap mentions (#31): notices and the console line count such files, the
+  event leaves them out.
+
+## Amendment: task dependencies (issue #34)
+
+- `deps` is a JSON column of task ids, set from `after` when a task is proposed
+  and never changed. It may name only tasks that exist, so the new task closes no
+  cycle (nothing can depend on it yet); the issue's cycle check at propose holds
+  by construction, and unknown ids are refused.
+- A task waits while any dependency is not approved. Waiting is an input to
+  `assign()` (`waitsFor`), which then returns no owner and says why, so `ahub
+  route explain` and assignment agree. Accept and done refuse a waiting task,
+  for the console user too.
+- A proposal that names an owner (a claim, or an owner for someone else) and
+  would wait is refused: the owner of waiting work is chosen when it is ready,
+  by routing or by `ahub task assign`.
+- Approval, by review or by a class without a reviewer, releases the
+  dependents that wait for nothing else; each is recorded as `ready` and assigned.
+  A proposal re-reads what it waits for after its insert, since triage may have
+  awaited an approval. An approval is saved before its dependents are assigned,
+  so the daemon's 60 s release timer sweeps for ownerless tasks whose last event
+  is `blocked` or `ready` and that wait for nothing: each is offered once per hub
+  run, once an attached peer can take it, outside recovery operations.
+- A recovery commit also waits for task operations in flight and for completion
+  checks queued or running: both can write the board after its integrity digest
+  (a check the commit's stop kills records `check interrupted`).
+
+## Amendment: quota-aware routing, wait or hand off, demotion (issue #36)
+
+- `assign()` stays pure: quota (per peer, the headroom of the most used fresh
+  window and that window's reset, from `Budget.headroom()`), the clock and the
+  demotion weights are inputs. Demoted peers go behind the others (owner role
+  only; local and Pi lose their place ahead of the cloud peers too); within each
+  group, peers with readings swap places by headroom per hour to reset (at least
+  15 min), and peers without readings keep their configured place. Idle still
+  comes before busy, so demotion orders peers in the same state.
+- Wait or hand off is decided at handoff time from the pause record's reset:
+  within `budget.wait_max_min` the handoff moves only tasks whose signals include
+  `urgent` (set by `hub_task_propose {urgent: true}`), and the pause reason says
+  so; beyond it the reason says the work was handed over and why. A wait is
+  undone when a later reading moves the reset past the limit: the record is
+  unmarked and the next tick hands over the rest, keeping both lists of moved
+  tasks. `DEFAULT_BUDGET` has it off, like approvals.notify; any project config turns it
+  on at 30 unless it sets another value.
+- Outcomes (`peer`, `class`, ok, time) are recorded in hub.db and kept a week:
+  approved counts for the owner, by review or done without a reviewer; changes
+  requested, a failed check and an escalation by hand count against it (the
+  hub's own escalations are not counted: after repeated changes requested each
+  one already was, and after a Pi inference failure the backend failed). Demotion: decayed failures reach 1.5 and outweigh decayed
+  successes, half-life one day, fixed constants for now.
+
+## Amendment: per-sender limits (issue #38)
+
+- One `Limiter` (`src/hub/limits.ts`) serves both ways an agent sends: the
+  control WS `send` (hub_send from Claude, and from Codex and Kimi through the
+  tools server) refuses with the reason in `error`, which the channel already
+  shows, so the message shape is unchanged; the bus's `admit` option guards
+  adapter messages (turn answers, the local worker's hub_send), drops a refused
+  one and tells the sender in a ride-along line.
+- Both admit the envelope as it will be sent: a reply without `to` goes to its
+  parent's sender, `digest` is resolved to the senders it replaced, and the
+  priority is capped. The repeat key includes the id of what the message
+  answers. `fyi` is never limited: it reaches no peer.
+- An `important` hub_send through the control WS (Claude, and Codex and Kimi
+  through the tools server) over its budget is refused, not downgraded, and the
+  reason says to send it without `[IMPORTANT]`. On the bus path (turn answers,
+  and the hub_send of Pi and the local worker) there is no caller to refuse:
+  over its important budget a message is lowered to status and delivered, and
+  the sender is told.
+- A refusal consumes no token and does not count as a send for repeat
+  suppression. Limits are off in `DEFAULT_CONFIG` and on with any project config
+  (12/min per sender, 6/min per recipient, 6 important an hour, 120 s repeats).
+
+## Amendment: review checklists and outcomes (issue #35)
+
+- A review request carries a checklist: map the changed signatures and call
+  sites to the task's plan, or without a plan to the task detail, which the
+  request then includes; the result of the class's check, or that none ran; and
+  `hub_review`'s `unmet`, one item each, which is appended to the verdict note.
+- Review outcomes live in a `reviews` table in hub.db: implementer, reviewer,
+  class, kind, task, time. Kinds: `approved`; `caught` (each reviewer who asked
+  for changes on the current owner's work, which was then approved);
+  `contradicted` (an approval, within seven days, of a task on the same file or
+  symbol as one whose check failed or whose review asked for changes, a
+  directory or `.` not counting; once per approval; console approvals and PII
+  tasks are not judged); `escalated` (the reviewer had asked for changes on the
+  work that was escalated, so not an escalation of unreviewed work).
+- A reviewer's record with an implementer in a class counts tasks: n = the tasks
+  it reviewed (approved, caught or escalated), held = (n - contradicted tasks) /
+  n. `assign()` takes the records as input and always shows them in its trace;
+  with `review.adaptive` it orders reviewer candidates that have at least
+  `min_reviews` by held, others keep their place, and the implementer is never
+  a candidate. The record is applied after quota, so the order is idle before
+  busy, then the record, then quota.
+
+## Amendment: recovery after an unplanned stop (issue #37)
+
+- The continuous record is `sessions.json` (instance id, time, and each attached
+  peer's `recoveryMetadata()`), rewritten when a peer's state changes and
+  removed when a stop of the run that wrote it begins (a stop that then runs past
+  the shutdown deadline is still not a crash). Found at start, with no
+  controlled-restart state in play, it means the previous run crashed; the new
+  run takes the record over at once, so its own clean stop removes it even when
+  no peer attaches. A controlled restart's target removes any record it finds.
+- Limits: a second crash before the peers attach loses their loss notices (the
+  journal rows stay in `needs_review`, shown by `ahub queue list`), and the first
+  attach rewrites the record with only the attached peers. A Pi in TUI mode is
+  reported with its command, not resumed: the CLI runs its terminal.
+- Resume goes through the same start path as `ahub kimi` / `ahub pi` / `ahub
+  local`: Kimi with `sessionId` (ACP `session/load`, refused when the agent does
+  not offer `loadSession`), Pi with its session file, the local worker afresh.
+  Codex and Claude are reported, not resumed: the TUI and the Claude session live
+  outside the hub. The issue's Codex `thread/resume` needs the TUI, so the report
+  names the thread instead.
+- Loss notices use the bus preface, not an envelope: a peer's `needs_review`
+  rows block its later deliveries, so a notice queued behind them would arrive
+  only after they are resolved anyway; the preface leads that next delivery. Only
+  rows still in `needs_review` when the peer attaches are listed.
+- `recovery.auto_resume_after_crash` is off by default, also with a project
+  config: an automatic start spends quota the user did not ask for.
+
+## Amendment: deny-default sandbox and capabilities (issue #39)
+
+- The deny-default profile allows exec and reads of the system directories
+  (`/usr`, `/bin`, `/sbin`, `/System`, `/Library`, `/opt`, `/private/etc`, the
+  dyld and timezone databases), the toolchain directories in home, `read_allow`,
+  the project, its external git dirs, the selected developer dir (`xcode-select
+  -p`) and temp; writes as before; a short list of mach services (directory
+  lookups, logging, notifications), plus name resolution and TLS trust when
+  network is on, the trust being the public CA bundles allowed by exact path
+  after the denies (the `*.pem` key deny matches them); no brokers that act
+  outside the sandbox (LaunchServices, SecurityServer). The denies at the end (credential
+  stores, the denylist, `.agenthub`, git hooks and config) are shared by both
+  bases.
+- The issue's allowlist proxy for `local.bash_network` is not built here: with
+  the flag on, network is allowed as in 0.9 and earlier. It is left for a
+  follow-up issue.
+- `local.sandbox` ("deny-default" | "allow-default") is machine-local, since
+  "allow-default" widens the sandbox.
+- Capabilities: `propose`, `assign` (a proposal naming another peer as owner),
+  `remember`, `important`. A peer not listed in `capabilities` has all of them,
+  which keeps today's behaviour, and a listed peer whose value is not a list has
+  none; the console user and the hub are never limited. `remember` gates the
+  `hub_remember` tool only, not the notes the hub keeps of done summaries and
+  review verdicts. Every refusal, a malformed entry and an unknown capability
+  name are logged.
+  `important` is checked where messages are admitted, the others in the task
+  operations, so in-process tools (the local worker, Pi) are covered too.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "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.8.1",
+  "version": "0.10.0",
   "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",