@staix/agent-hub 0.12.19 → 0.12.21

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

@@ -89,7 +89,8 @@ Facts below are tagged **verified** (measured on 2026-09-19 on the owner's Mac)
 7. Quota relay hands open tasks to the `local` peer first, then waits for the window
    reset for judgment-heavy classes. Task-level escalation on verification failure.
 8. Safety defaults: cross-peer text is framed as untrusted; permission prompts stay on
-   unless `--unattended`; ports bind loopback only; Kimi ACP permission requests are
+   unless `--unattended` or an operator-selected permission mode (issues #240,
+   #242); ports bind loopback only; Kimi ACP permission requests are
    relayed to the hub console. Loopback is not enough on its own (any web page can open a
    WebSocket to 127.0.0.1), so the control WS requires a per-run token and both hub
    servers refuse requests that carry an `Origin` header (amended in M1).
@@ -97,8 +98,9 @@ Facts below are tagged **verified** (measured on 2026-09-19 on the owner's Mac)
 10. Shared memory reuses claude-mem as the single store; the hub never runs its own
     memory database. Native capture stays where it exists (Claude hooks, Codex plugin,
     Kimi transcript bridge); the hub captures only the local worker and adds
-    cross-platform recall, task-scoped briefs and explicit shared notes. The bus still
-    passes messages, never transcripts.
+    cross-platform recall, task-scoped briefs and explicit shared notes. Hub tool calls
+    are not captured; Tasks alone decides what screened tool text reaches memory.
+    The bus still passes messages, never transcripts.
 
 ## Design
 
@@ -279,9 +281,10 @@ peer. Peer ids claimed over the control WS must not be `user` or a hub-managed a
   injection is dropped for the same reason as `dynamicTools`.
 - PII (amended in M4): a task matching `signals.pii_patterns` is owned by `local` or by
   nobody; its envelopes are `private` (console tail and `hub.log` print a stub), lists show
-  `[pii]` to everyone but `local`, `ahub task show` is the one place the console reads it; the
-  reviewer is the console user; `local` answers such a turn to the console only, keeps it out
-  of its history, refuses it when the only gateway is off campus (Cloudflare Access), and
+  `[pii]` to everyone but `local` inside a PII turn; `ahub task show` is the one place
+  the console reads it. The reviewer is the console user; `local` answers such a turn
+  to the console only, keeps it out of its history, refuses it when the only gateway
+  is off campus (Cloudflare Access), and
   nothing reaches claude-mem (no brief, no note, no capture), because claude-mem's observer is
   a cloud model (verified: `/api/health` reports `ai.provider: claude`).
 
@@ -486,7 +489,8 @@ inside a peer.
 ### Safety
 
 - Untrusted framing on all cross-peer text; standing instruction once per session.
-- `ahub claude` and `ahub codex` keep normal permission prompts. `--unattended` opts into
+- `ahub claude` and `ahub codex` keep native permission defaults unless the person
+  selects a permission mode (issues #240, #242). `--unattended` opts into
   `--dangerously-skip-permissions` (Claude) and `--dangerously-bypass-approvals-and-sandbox`
   (Codex 0.154.0 documents this flag, not `--yolo`) and prints a warning.
 - Kimi and local tools: cwd-scoped, secrets denylist (a secrets directory, `.env*`, keys).
@@ -496,7 +500,7 @@ inside a peer.
 ### Configuration and state
 
 - `.agenthub/config.json` (roles, ports, filter tiers, watchdog), `.agenthub/routing.toml`.
-- `.agenthub/state/` gitignored: `hub.pid`, `status.json`, `control-token` (0600, per run),
+- `.agenthub/state/` gitignored: `status.json` (with the daemon's pid and process signature, #226; daemons up to 0.12.20 also wrote `hub.pid`), `control-token` (0600, per run),
   `hub.db` (tasks, messages, budget; from M4), `hub.log`, `switchyard.toml`, `checkpoint.md`.
 - Env: `AGENTHUB_STATE_DIR`, `AGENTHUB_OMNIROUTE_URL`, `OMNIROUTE_API_KEY`,
   `AGENTHUB_SWITCHYARD_BIN`, `AGENTHUB_UNATTENDED`.
@@ -763,7 +767,8 @@ session modes (`default`, `plan`, `auto`, `yolo`) but nothing per server or tool
   `hub_send` or a task tool, are answered with their `allow_once` option by the
   hub, without a console prompt, and logged by tool name only. This matches the
   `approval_mode = "approve"` Codex already gets for the same tools. Every other
-  request keeps the console path; `allow_always` is never chosen automatically.
+  request keeps the console path unless the person opts into the permission modes
+  below (issues #240, #242); `allow_always` is never chosen automatically.
 - For the other tools, the console payload falls back to the streamed argument
   text once it is a complete JSON object. A partial stream stays unresolved and
   keeps `allow_always` withheld.
@@ -776,6 +781,68 @@ session modes (`default`, `plan`, `auto`, `yolo`) but nothing per server or tool
   configured server of the same name, so only the hub's `agent-hub` server can
   produce the approved names.
 
+## Amendment: operator permission modes (issues #240, #242)
+
+- Modes: ask leaves native decisions unchanged; ask-when-needed uses native
+  Kimi/Codex policies or scoped Claude/Pi/local grants; never-ask suppresses
+  prompts within each peer's existing execution boundaries.
+- Runtime CLI permission changes are refused from ordinary agent shells.
+  Never-ask needs --yes; console mode selection needs a separate y. These
+  policy/role checks do not contain a hostile same-user shell: Kimi can clear
+  markers, use --yes or read the control token and impersonate the console.
+  The security and operations guides name that boundary explicitly.
+- permission_modes defaults merge per peer across config files. Automatic
+  effects stop at ask-when-needed. Never-ask from an applied untracked config remains ask until
+  a person's source-labelled console y at hub start; no boot --yes applies it.
+  Git-tracked mode defaults are ignored and never offered for confirmation.
+  Every non-ask start logs mode and source (config file or runtime choice). Successful
+  runtime changes clear pending config confirmations; startup choices are reconciled
+  under the peer fence before a new adapter is exposed to bus delivery. Runtime changes and
+  confirmations remain daemon-local and expire on stop.
+- Newly added native peers replay their non-offline state to drain queued work,
+  publish state telemetry and persist sessions. Offline/absent ask clears only
+  the hub choice. Unattended metadata is saved after successful startup, and
+  concurrent joined starts with different flags are refused. Refused default
+  confirmation remains handled until state changes; Esc defers without declining.
+- Kimi mapping requires the actual Kimi Code CLI identity: yolo for
+  ask-when-needed, auto for never-ask, default for ask. Another ACP agent starts fresh or resumed as unmanaged: its reported mode is
+  untouched, and runtime changes are refused until its table exists. Set-mode replies precede prompts;
+  missing ids/refused startup changes fail. A timeout is unknown/offline and
+  the owned process group stops, so a late reply cannot restore a live peer.
+  Loaded non-default Kimi modes are reset for project ask.
+- Codex overlays on-request/never on every outgoing turn/start without changing
+  sandbox fields. Ask restores a known native policy once after an accepted
+  turn; rejected restoration remains pending. Unknown native baseline refuses
+  restoration. Actual native unattended flags, not broker-wide flags, govern
+  the refusal to change a bypassed session.
+- Claude ask-when-needed allows only Read/Edit/Write/MultiEdit/NotebookEdit/LS
+  and bounded Glob/Grep targets resolved with realPath beneath project root,
+  outside .agenthub/.git/.claude/.codex/.qwen/.kimi/.pi/.mcp.json. Missing/nonresolving or escaping targets,
+  protected case aliases, symlinks and uncertain wildcard/filter targets yield
+  no decision. Never-ask answers allow; ask and transport errors decide nothing.
+  Merged/generated settings are 0600 state files passed by path, never inline
+  in argv. Preview writes no settings file. The owning launcher removes its settings file
+  after native exit; earlier active or unknown launchers retain theirs. Verified
+  dead wrapper and native identities permit crash fallback cleanup. Without
+  separate native identity proof, prior files remain for manual inspection.
+- Permission-only Claude PreToolUse never drives busy state. Only the former
+  observation purposes retain native turn bookkeeping. Hook identity/purpose
+  are launch/session bound; unverified hook status reads unverified.
+- Pi/local read never asks. Ask-when-needed grants write/edit inside the project, outside the shared native
+  configuration segments (.claude/.codex/.qwen/.kimi/.pi/.mcp.json, compared folded and by the path within the
+  project) and never through a hard link; bash and mutating
+  git retain console approval. Never-ask grants once, retaining sandbox and
+  path guards; no mode gives allow-always. ACP tools have no hub sandbox and
+  the never-ask confirmation names that difference.
+- Console-role permission and permission_default requests are additive;
+  ordinary tools/conductor/messages cannot change or confirm modes. Status
+  includes non-ask/unverified/unknown mode state and pending defaults; facts
+  replies include permission and authenticated projectRoot. Unknown requests
+  are answered, so PROTOCOL remains unchanged. permission_mode events retain
+  schema 1 and include only peer/from/to, never tool arguments.
+- Live benign Kimi/Claude results and unverified Codex/Pi limits are recorded
+  in docs/smoke.md. No extra account prompts accompany these review corrections.
+
 ## Amendment: approval notifications and timeout (issue #5)
 
 - A waiting permission request raises one macOS notification (`osascript`) with
@@ -986,15 +1053,19 @@ session modes (`default`, `plan`, `auto`, `yolo`) but nothing per server or tool
   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`.
+  would wait stores that owner as the task's reserved owner (issue #207 below
+  replaced the refusal this bullet first specified).
 - 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.
+  run, once an attached peer can take it, outside recovery operations. An offer
+  is used up only by an assignment, after an approval and on the timer alike;
+  failed dependent reads, ready writes or assignments do not escape a saved
+  approval. Their notices are best effort because notification can read the
+  same unavailable board. An ownerless task stays eligible once a peer can take it.
 - 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`).
@@ -1360,14 +1431,59 @@ approval. Deny is direct. Pending requests include expiry and are withdrawn by
 Panels expose Peers, Approvals, Tasks, Queue and Events with bounded polling and
 Unicode cell widths, fall back below 80x24, and restore terminal state on exit.
 
+Whole-board progress (#246) uses one pure `taskProgress` function shared by the
+console and hashed dashboard script. It reads only public id/state/deps fields;
+PII stubs count like other tasks. Waiting partitions proposed tasks whose public
+dependencies are not approved, including unknown dependencies. Approved/all gives
+the done fraction (zero on an empty board). Four stages are proposed, in progress,
+in review and approved; changes requested returns to stage two and is marked.
+The console Tasks panel has a 20-cell ASCII summary bar and fixed four-cell row
+meters, preserving width and color-off geometry. Cells and percentage round down;
+count labels use importance order changes requested, review, waiting, in progress,
+proposed, then unknown when nonzero, and drop only from the end. The stream count is in the fixed footer,
+from existing all-state status counts; it makes no board fetch and retains a
+row-one scroll region for terminal scrollback. Loading/failed reads never imply
+confirmed empty progress. Dashboard filters affect rows only, not totals. Its
+full-width stacked SVG and stages have text equivalents; the existing signature
+guard prevents unchanged snapshots from mutating the progress live region.
+System/Light/Dark choice is applied as `data-theme` before first paint, persists
+in a one-year host-scoped `SameSite=Strict` cookie through guarded access and
+follows OS CSS preference on System. Cookie port independence shares the choice
+between hub starts and projects. The shared model is injected before the page's
+own inline script/style CSP hashes, with no new control message or CLI JSON change.
+UI public rows expose optional public-view deps for waiting. This is additive
+metadata enrichment of the existing ui_snapshot payload, not a changed control
+message envelope/operation, so it does not bump PROTOCOL. Unknown task states
+count in an explicit unknown bucket with stage zero; no NaN or prototype-key
+updates are permitted. Approval fraction is derived from counts/total at display
+time, avoiding a redundant floating-ratio field.
+
 Console semantic colors (issue #201) use spans with a fixed terminal-native
 palette: cyan information, bold cyan active/selected labels, green availability
 and success, yellow attention/waiting, red failure/intervention, and restrained
 bright-black metadata. Offline peers, ordinary titles, action details and body
 lines use the default foreground. Existing labels, selection markers and
-confirmation prompts remain sufficient without color. Stream headers use event
-structure for their tone; body text is never parsed for meaning or passed
-through as terminal styling. Denial requests and observed expiry/cancellation
+confirmation prompts remain sufficient without color. Console stream headers
+color meaningful tokens only (#239; dated issue Decisions): Claude bright blue
+(94), Codex bright cyan (96), all other peers default; `task` magenta (35, never
+bold), numbers bold default foreground (1), task references magenta underlined
+(4;35), and other issue references underlined default foreground (4). No token
+SGR equals a state or peer SGR. Green/yellow/red remain states/approvals/failures,
+cyan remains navigation. Case-insensitive `task #N`, `Task #N`, `[task #N]` and
+`[review #N]` identify task references; unbracketed prose `review #N` remains an
+issue reference. Ordinary words keep default foreground;
+there is no hashing or user theme.
+Only hub-written peer slots, state words and structural markers receive their
+semantic tones; title words and markers cannot choose them. Numeric tokens have
+whole-token boundaries, so UUIDs and ISO identifiers stay plain. Legacy notices
+lack typed reference ranges: the task/review prefix heuristic is bounded by a
+`ponytail:` comment; other `#N` tokens use the issue tone until structured notice
+spans classify assign/which references. Header text crosses `terminalText` before tokenization. Wrapped headers normalize
+tabs to spaces first; plain headers retain their original tabs in both color modes. Wrapped spans retain the source classification. After a projection
+miss on the first physical header, only structural tones remain. A missed
+continuation and all later continuations are fully plain. Projection advances
+a span index through the source once, keeping long permission titles bounded. Bodies and every
+command-output line stay plain. Denial requests and observed expiry/cancellation
 are red; an answered remote closure lacks option-kind metadata and is not
 guessed to be a denial.
 
@@ -1377,13 +1493,66 @@ checks even for redirected stream output, without enabling panels or raw mode;
 never disables styling. Invalid values fail with usage text before connection.
 Plain `renderConsole` remains available, while `renderConsoleLines` exposes
 semantic spans. Geometry is computed from sanitized plain Unicode text before
-painting. `paint` sanitizes every span, inserts only fixed palette SGR sequences
+painting. Wrapping breaks at whitespace and splits only a word longer than a whole
+line; a wrapped line's continuations start four columns deeper than
+its source line; a source indent and a continuation indent are both capped at half the width, so wrapped peer text in the stream
+never starts at a column where hub-written lines start (#212). `paint` sanitizes every span, inserts only fixed palette SGR sequences
 and resets each styled span. Interactive exits, signals, disconnect and errors
 retain the console restoration sequence. No new dependencies, protocol changes,
 polling or redraw triggers are added. Tail, logs and machine-readable output
 remain unchanged. Native light/dark readability and idle-CPU observations are
 separate smoke evidence, not inferred from fake-terminal tests.
 
+Console layout (issue #213) separates the panel header (the project root's
+directory name, since the registry id is a hash, then the tabs), the body and
+the footer with ASCII `-` rules, and puts one rule above the stream footer; the
+console emits no box-drawing or other ambiguous-width glyph. The active tab is
+bracketed; the Approvals and Queue tabs count pending requests and
+`needs_review` deliveries. Peers, Approvals, Tasks and Queue are tables: a
+header row, columns two spaces apart sized with `Bun.stringWidth` from every
+row (at most a third of the width), the last column taking the rest. Peers' LINK
+column reads `tools-only` when the optional `toolsOnly` status field (#205) is
+present. Zero counters read `-`, durations `45s`, `12m`, `3h05m` or `2d03h`, and
+resets and pauses are relative. Detail views and the Approvals panel's request
+block put labels at column 0 and values one column past the longest label; a
+list puts `- ` before each item, and every other line of a value (its own
+newlines, wrapped continuations) starts two columns deeper, so untrusted text
+passes neither for a label nor for an item. Only a field's own string shows as
+written: every agent-written string below it (nested pairs and lists, list
+items) and every option name or id in the Approvals block, the prompts and the
+stream's permission line is JSON-quoted unless it is a plain word starting with
+a letter, so `;`,
+`,`, `)`, quotes and newlines in it cannot pass for hub structure. Values show
+no JSON objects, epoch milliseconds or ISO times. Allow options keep one line
+each; `d deny` always stays in view, options that do not fit are counted on a
+`(more)` line, table rows give way, and a cut title is marked `(more)` in the
+label column. The selected request is tracked by id: only the first request is
+selected on arrival, `[`, `]` and j/k move the selection, `a`, `d` and `v` act on
+it alone, and its detail is rendered from the live request. When it closes, the
+selection and its detail clear with a notice; `a`, `d` and `v` act on nothing
+until `[`, `]` or j/k select again, so a request that arrives as the person
+reacts is never acted on. Everything pending on a request belongs to the
+selected one, checked after every key and every prune: an option choice or
+confirmation for another request is dropped, an open detail follows the
+selection from its top, and the option prompt names the request. `a`, `d` and
+`v` act only while the request list or its detail is shown, and a task or
+delivery detail that arrives after the person moved to another panel or row is
+dropped; with a task, delivery or peer detail open, the row keys act on the item
+the detail shows, by its id. A pushed request's agent-supplied fields are kept as
+strings, so a malformed one cannot throw on a draw. The key table is modal: only
+`?`, Escape and `q` act under it, and a paste is dropped. Offline peers keep the default foreground, also
+when selected, and a tab counts as one space when a line is cut. The footer
+hint lists only the keys valid in the mode, panel and state, and `?` shows a
+key table grouped by panel (in stream mode it is printed into the stream, as
+`v`'s copy of a request is, without entering the Events buffer). Errors and refusals take the failure tone, informing notices (a closed or
+missing selection) the attention tone. A notice clears at the next key, or once 10 s have passed when the
+existing 1 s tick redraws. In the stream, `v` prints the selected request with
+the push's framing, and `:` command output lines start at column 4. `fit`
+measures a cut line as `paint` prints it, so a cut that ends a span in
+`[agent-hub` cannot widen the line with a `> ` marker. A context reading in the
+console stream and Events panel shows its measurement time as local time, as
+event headers do; `ahub tail` and `ahub status` keep the ISO time.
+
 Agent shell CLI calls connect as the detected peer in tools mode. Hub launches
 set `AGENTHUB_PEER_ID`; the pinned installed Codex shell injects
 `CODEX_THREAD_ID` after environment filtering, and Claude uses `CLAUDECODE`.
@@ -1534,3 +1703,404 @@ only. The path guard, denylist and sandbox still apply to each call; the
 dashboard still offers Pi only deny; unattended mode still picks `allow_once`;
 the local worker keeps allow and deny. The console and `ahub permit` already
 handle more than one allow option, so the control protocol is unchanged.
+
+## Amendment: Claude sessions without channel evidence (issue #205)
+
+Claude Code without `--dangerously-load-development-channels` drops channel
+notifications without an error, so a plain `claude` session used to mark every
+push `accepted` and show none of them.
+
+- Evidence: `ahub claude` passes the flag and, in the same launch, sets
+  `AGENTHUB_CHANNEL=1` in Claude's environment (`nativeLaunchEnv`);
+  `peerChildEnv` removes the marker from every other native child. The plugin's
+  MCP server inherits Claude Code's environment (a local check on 2026-10-09,
+  not a live smoke: a plain session's plugin server inherited a shell-only
+  `AGENTHUB_*` variable, and the plugin's `.mcp.json` sets no env), as it
+  already does for
+  `AGENTHUB_STATE_DIR` and `AGENTHUB_PEER_ID`. Only the value `1` counts. With
+  the marker the server keeps
+  the push and settlement contract of "Live channel settlement" unchanged.
+  Without it (a plain `claude`, an IDE session, or the flag passed by hand) the
+  session attaches tools-only.
+- Decision: the launch marker is sufficient evidence, and no positive readback
+  is required before the first `accepted`.
+  - The marker and the flag come from the same launch, so the marker shows that
+    this Claude process got the flag. A readback would add per-push proof of
+    display, which stays out of scope: `accepted` means the bridge handed the
+    notification over, and `hub_delivery_done` or a correlated reply settles
+    handled work.
+  - A readback (a native turn citing the pushed id) would hold every first
+    delivery until the model chose to answer, and a session that never answers
+    would look the same as one that never rendered.
+  - The existing launch identity (`AGENTHUB_INSTANCE_ID`, `AGENTHUB_LAUNCH_ID`)
+    is not used: `ahub claude` sets it only when a daemon is already running at
+    launch, so an `ahub claude` started before `ahub up` would lose pushes it
+    can show.
+  - Limits: the marker is inherited by the session's own shell children, so a
+    plain `claude` started inside an `ahub claude` session reads as
+    channel-capable (it also inherits the peer id and takes the peer over); so
+    does `claude -p` run by a hook or script inside such a session, with its
+    state dir and peer id. The marker is per process while the flag names MCP
+    servers: `ahub claude --mcp-config <candidate>` without
+    `--strict-mcp-config` loads channels only for `server:agent-hub`, yet the
+    installed plugin server in the same process also sees
+    `AGENTHUB_CHANNEL=1`. A session started with the flag by hand reads as
+    tools-only and is pointed to `ahub claude`.
+- Tools-only attach: the server declares tools only, sends `channel: false` in
+  its `peer` hello and lists `hub_inbox` but not `hub_delivery_done`. It never
+  reports `accepted`: a `deliver` it is handed anyway goes back as a
+  `needs_review` receipt. The daemon attaches its `WsPeer` as `pullOnly`; a
+  push drain needs the peer deliverable (`Bus.deliverable`: not held, idle, not
+  pull-only), checked at each loop and again after condensation, so a plain
+  session that takes the peer while a push is condensed gets nothing. Its
+  messages stay queued and count as `queued`. Board routing still treats the
+  peer as attached.
+- `hub_inbox` sends `inbox`. The daemon answers "not attached yet; retry"
+  between welcome and attach, and refuses it for a session with pushes.
+  `Bus.pull` is held by every hold a drain respects (`Bus.held`: recovery, an
+  uncertain delivery, a console, budget or conductor pause), though unlike a
+  drain it does not wait for the peer to be idle; a held pull journals nothing
+  and the refusal names the hold and the next action. Otherwise it takes what one
+  push delivery would (the preface, then `take`'s batch of at most ten,
+  important first; the reply says how many still wait) and checkpoints it like
+  a push, so queued journal rows of the same envelopes (an operator retry) are
+  grouped into it, then marks it `completed`, reason `read through hub_inbox`,
+  in the same transaction: the tool result that returns them is the readback,
+  so nothing waits in `accepted`. What it hands over is registered (and moved
+  to the newest end of the cache) for `reply_to` like a push, and a read clears
+  the peer's failure streak as a completed push does. If that journal write fails, only this peer's queue
+  and preface are put back (every pause stays) and the bus stops with
+  `delivery journal unavailable`. A refused or failed `resolveDelivery` likewise
+  puts back only that peer's queue and preface and keeps every pause. Queue
+  contents change in place, preserving arrays held by a suspended drain; only
+  the constructor and recovery restore reload a bus snapshot. A pull is not a native turn and is not
+  counted as supervision. The row is completed at hand-out, before anything
+  shows the model saw it: a reply lost on the way, a tool call cancelled with
+  Esc or a plugin that dies loses the batch (a `ponytail:` ceiling in
+  `Bus.pull`), and `ahub queue resolve --action retry` refuses a terminal row.
+  The completed row keeps the envelopes, so the operator reads them with `ahub
+  queue show <id>` and sends what matters again.
+- Who holds the peer: an `ahub claude` session takes it from a plain session
+  as any newer hello does, a standing-by one included (its standby check does
+  not wait for a holder that status reports `toolsOnly`); attach clears
+  `pullOnly`, the waiting queue is pushed to it, and the plain session stands by
+  (close 4000). A plain session
+  never takes it from a session with pushes, attached or still arriving: its
+  hello is closed with 4000 and it stands by the same way, so an IDE or plain
+  `claude` with the user-scope plugin cannot strand the channel session's
+  unsettled deliveries. It attaches once that session leaves.
+- Status: `status.json` peers carry `toolsOnly`, a line naming the state and the
+  next action (`ahub claude`); `ahub status`, the console footer and the
+  dashboard show it.
+- Control protocol 16 adds the hello `channel` field and `inbox`. Recovery
+  sources add protocol 15 (0.12.17 through 0.12.19); the transition from a real
+  0.12.19 hub is not yet proven.
+## Amendment: owner and reviewer read their task (issue #208)
+
+`hub_task_show` stays a conductor tool, and a task's current owner and current
+reviewer may also call it for that task. They get exactly the conductor's
+view: `publicConductorTask` over `Tasks.publicView(task, true)`, so the whole
+history with its done summary and check line, notes that match a PII pattern
+withheld, and a PII task as a stub with no history. Any other peer is refused
+with the conductor-role error, whatever the task. That refusal is about the
+tool, not a secret: the view holds nothing private beyond the PII stub, and the
+control op `task_show` (`ahub task show` from an agent shell) already returns
+the same public view to any peer. These reads write no conduct audit event, as
+task list polling does not. `hub_status` stays conductor-only.
+
+## Amendment: reserved owners and proposer redirects (issue #207)
+
+- `reserved` is a nullable text column on `tasks`, added to existing boards
+  like `plan` and `deps` (old rows reserve nobody). `hub_task_propose` with an
+  `owner` and an `after` that still waits stores the owner there instead of
+  refusing; the capability check for naming another peer is unchanged. With
+  nothing left to wait for, a named owner is assigned as before.
+- The reservation is an input of `assign()`, read from the task, so `ahub
+  route explain` and assignment agree. When no candidate list is given, the
+  reserved owner is the only candidate if `blocked()` passes it; otherwise the
+  trace says why it is not honored and routing proceeds through the class
+  peers. PII, capability limits (`local_allowed`, Pi's context limit),
+  exclusions, failing peers and offline or paused peers all pass it over, so a
+  PII task still goes to `local` or nobody.
+- Lasting exclusions are refusals only: a decline records the owner it was
+  declined for in its history entry's `from` (also when the console declines
+  for that owner), and an escalation with reason `rejections` (a reviewer's
+  repeated changes_requested) or `manual` (by hand) records the owner it took
+  the task from the same way. `excluded()` reads both (older decline rows name
+  only the decliner), so those peers stay out of every later reroute and of
+  `route explain`: the reservation never hands the task back to them. The
+  hub's own escalations after a failed delivery or inference
+  (`delivery_failed`, `inference_failed`), and an owner released as gone, moved
+  by the idle sweep or relayed for its budget, exclude that owner only from
+  that move's own reroute: none of these is a refusal, so a later reroute may
+  give it the task again from its reservation. A person's explicit assign
+  (`ahub task assign`, the dashboard) is not blocked by lasting exclusions and
+  clears an agent's reservation, so a later reroute does not hand the task to
+  the agent's choice; the conductor's and a proposer's assigns respect the
+  exclusions and keep the reservation.
+- A named candidate list (console or conductor assign, escalation, budget
+  relay, the idle sweep's auto-reassignment of its suggestion) replaces the
+  reservation; the idle sweep's step-3 suggestion itself is an `assign()`
+  without candidates, so it consults the reservation like routing does. A task
+  that waits shows its reservation in the trace before the readiness check,
+  which then stops; the trace says whether routing would honor it only once
+  the task is ready. `route explain <id>` also names it in the header. The
+  reservation stays after it is honored or passed over.
+- Passing over a reservation is a console and hub.log notice naming the
+  reserved peer and the reason, from assignment and from the idle sweep's
+  suggestion alike, and the assignment's history note keeps it, appended to a
+  note the caller gave (a gone owner's release). Only news is said: nothing
+  when the reserved peer is the owner the task moves away from (its decline,
+  escalation, release or idle sweep), and nothing once it refused the task for
+  good (the decline or escalation said that). The reserved peer is not
+  messaged.
+- `Tasks.assignTo` on a task that waits records a `reserved` event with reason
+  `manual` and changes the reserved owner instead of the silent no-op it was;
+  this applies to the console, the conductor and a proposer alike. The release
+  timer treats a `reserved` last event like `blocked`.
+- `hub_task_assign` stays a conductor tool, and the task's proposer (the `by`
+  of its first history entry) may call it while the task is `proposed` and its
+  history has no `accepted` entry: a decline or a release puts a task that was
+  worked on back in `proposed`, and that task is no longer the proposer's to
+  redirect. Handing it to another peer needs `assign` when the proposer has a
+  capabilities entry; redirecting to itself does not. The conductor needs
+  `assign` for any assign when it has a capabilities entry. The proposer path
+  is refused while the last owner or reservation change of the task
+  (`assigned`, `reassigned`, `escalated`, `unassigned`, `reserved`) that the
+  hub did not make itself was made by the console user: a person's assign or
+  reservation stands until the conductor or the console moves it, also after
+  the hub carried it out or passed it over. The id is taken as `Tasks.need()`
+  takes it, a whole number or a digit string. Any other non-conductor peer, and
+  the proposer once the task was accepted or a person moved it, get the
+  conductor-role error. A proposer's redirect goes through `Tasks`, keeps the
+  proposer as the actor with reason `manual` (on the `reassigned` or `reserved`
+  entry), and writes no conduct audit event; during a PII turn it is refused
+  like the conductor's.
+## Amendment: ahub reset (issue #214)
+
+`ahub reset [--all] [--yes]` returns a project's hub to a clean state. It is
+human-only (the CLI identity gate refuses it from an agent shell) and a dry run
+unless `--yes`: the dry run reads `hub.db` read-only (with `immutable=1` when
+`hub.db-wal` or `-shm` is absent, so it creates neither) and prints delivery ids,
+peer names and counts per category, never task or message text. With `--yes`
+it stops a running hub through `stopProject`, the path `ahub kill` takes, then
+acts on the stopped state directory.
+
+- Refusals, each before anything changes: the machine's recovery lock is held
+  (`recoveryLock()` read directly: a reset is never part of an operation, so
+  `AGENTHUB_RECOVERY_OPERATION` does not let it through as it lets the
+  operation's own processes through `assertLifecycleAvailable`); no
+  registration matches this root and state directory, running or not (`ahub
+  up` registers a stopped project; when this root is registered with another
+  state directory the error names `ahub --project <id> reset` instead, since
+  `ahub up` would register the default directory and orphan that state); the
+  hub's ownership is not verified (any inspection state other than stopped, running
+  or stopping); a running hub reports a recovery operation whose phase is not
+  `released`; `--all` with a state directory other than the literal
+  `<root>/.agenthub/state` (an override or symlink elsewhere would cross file
+  systems or pull outside state into the tree); `--all` when `.agenthub` or
+  the state directory is not a real directory of this user, when
+  `.agenthub/archive` exists as anything else (a symlink could carry hub.db,
+  PII included, out of the project), or when its `.gitignore` is not a regular
+  file (a symlink would truncate the file it names). These are checked before
+  the stop and again right before the rename (`archiveProblem`); a hard-linked
+  `.gitignore` is replaced by a temp file and rename, never written through.
+  Checked, then renamed by path: a symlink swapped in between still wins
+  (marked `ponytail:`; `renameat` on a held descriptor would close it).
+- Between stop and act: after `stopProject` the CLI takes the project's
+  registry claim (`Registry.claim` with its own pid and process signature), the claim a daemon must
+  hold to run, and checks that no manifest names a daemon whose pid is alive
+  or uncertain (`processLiveness`, the rule `inspectProject` uses, #226); either failing
+  means a hub started in between and nothing is reset. A reset's claim carries
+  the instance prefix `reset-`, so losing the claim to a concurrent reset says
+  so. A crashed daemon's manifest (`status.json`, `control-token`, `hub.pid`
+  with a dead pid, after SIGKILL or the forced shutdown exit; an empty or
+  garbled `hub.pid` beside a dead `status.json` included) does not count: the runtime reset
+  removes it and `--all` archives it. With the claim held, the CLI checks the
+  machine's recovery lock again, so an upgrade or recovery that took it in
+  between does not run beside the reset. The claim is released when the reset
+  ends; a reset that dies leaves a dead or reused pid with its signature, which the next claim takes over.
+- Failures: the plan is read only for the dry run, so `--all --yes` archives a
+  state directory it cannot read as it is (its dry run says what it could not
+  read). A failure after the stop says how far it got. A runtime reset that
+  cannot read the state (a corrupt `hub.db`, malformed JSON or valid JSON of
+  the wrong shape, which `planReset` checks as the journal would, a journal the
+  constructor refuses: root mismatch, corrupt metadata, too many rows) fails
+  the same way on a rerun, so its error points to `--all`; any other runtime
+  failure is finished by a rerun, every step being idempotent. `--all` prints
+  the archive path as soon as the rename happened; a failure before it says
+  the hub is stopped and nothing was moved. JSON and SQLite errors are printed
+  by class and code only (`failureText`): a parser's message can quote the
+  data it choked on, envelope bodies and task text included.
+- Runtime scope (default): the CLI opens the journal as a new instance, which
+  turns the stopped run's dispatching and accepted rows into `needs_review`,
+  and settles every `queued` and `needs_review` entry of `Bus.queueList`,
+  including queue entries without a row, with `resolveDelivery(..., "discard",
+  "reset")`: one `resolution_history` entry each. It clears manual holds
+  through the bus, deletes the `budget_pauses` and `conductor_holds` rows and
+  removes `sessions.json`, `claude-session.json` and `claude-context.json`,
+  and a crashed run's manifest.
+  The board, turns and touches, execution budgets, logs, `events.jsonl`,
+  `cli-audit/`, recovery records, `pi-sessions/` and configuration stay.
+- Full scope (`--all`): the state directory is renamed, unchanged, to
+  `<root>/.agenthub/archive/state-<YYYYMMDDTHHMMSSZ>/` (0700); an existing
+  target refuses the move. The archive directory gets a `.gitignore` of `*`
+  (checked on every `--all` and rewritten when it differs) because `hub.db`
+  holds task text, PII included; turn snapshots exclude `**/.agenthub/archive/**`
+  as they exclude the state directory, also when the user's index tracks it or
+  the `.gitignore` is gone; and `.agenthub/archive` is a
+  `DENY_SEGMENTS` entry (`src/local/deny.ts`), so the local worker's and Pi's
+  path guard, seatbelt profile and memory capture refuse it like
+  `.agenthub/state`. A new 0700 state directory (created with `recursive`, as
+  the status line tee may have re-created it) holds only a copy of
+  `project.json`; the project id is the hash of its root,
+  so the registration and id are unchanged. Archives are never pruned.
+- Output says that claude-mem is not touched and that attached Claude Code
+  sessions must be relaunched with `ahub claude`. The control protocol is
+  unchanged: reset never talks to a running hub except to inspect and stop it.
+
+## Amendment: model-based PII screen (issue #198)
+
+- `routing.toml` `[signals] pii_screen = "off" | "local"`, default `off`; any other
+  value fails the load like a bad pattern. With `off`, or with `constraints.pii =
+  "off"`, nothing changes and no screen call is made.
+- Order. With `local`, `Tasks.propose` screens the task's title, detail and plan
+  text right after the pattern check and before triage. "Held as private" is met
+  by holding the task back entirely: until the verdict it is not on the board, so
+  no envelope, notice, triage call, brief or note of the hub's can read it. The
+  local worker never captures hub tool calls (#230), so a proposal's arguments
+  cannot bypass the verdict through capture. Writing it as
+  a PII task first was rejected: a PII task opening lifts every silent turn-free
+  cohort for good and switches facts off (#107, #108), so every proposal would do
+  that. The proposal's tool call waits for the verdict, as it already waits for
+  triage: for an ordinary task at worst the screen (8 s), triage (8 s) and a brief
+  (2 x 2 s), 20 s; for a task the screen marked PII, triage first runs its own
+  on-campus probe (two 4 s rounds when the gateway stalls), so about 24 s. Both
+  stay under the plugin's 30 s control timeout. `hub_task_done` and `hub_review`
+  put the screen (8 s) ahead of their existing waits, such as the briefs
+  `releaseDependents` fetches for the tasks an approval releases.
+- The screener (`screenPii`, `src/hub/inference.ts`): the on-device model when
+  `mlx.enabled` and it can be had (`ensureMlx`, loopback only; a legacy MLX runtime
+  is started the way Pi's relay starts it and keeps running until `ahub models
+  stop`), else the gateway's `local.fixed_model` only while the
+  daemon's `onCampus()` holds, with `onCampusOnly` so the client refuses an Access
+  host once more before transport; never the Switchyard sidecar. One call per item,
+  an 8 s deadline over the whole call, and a generation slot of its own: it asks
+  for one without waiting (`acquire(abort.signal, 0)`: one look, then
+  `MlxBusyError`); with all taken (Pi generating, another screen) it uses the
+  campus gateway when `onCampus()` holds and otherwise waits for the slot under the
+  deadline. On campus the device gets 60% of the deadline: an error reply or a
+  device still loading then hands over to the gateway within the rest; off campus
+  it keeps the whole deadline. `max_tokens` 32, temperature 0 and `reasoning_effort: "none"` on both
+  paths, so a reasoning model does not spend the budget thinking. The
+  prompt frames the text as data and carries Korean and English examples and hard
+  negatives. The answer must be exactly `clear` or `pii <category>` with a category
+  from `name, student_id, phone, address, grade, health, other`.
+- Fail closed: an answer outside that form, a timeout, a failed or missing model,
+  an off-campus gateway, or text over 6000 UTF-8 bytes (every token is at least a
+  byte, so text and prompt fit the 8k on-device context; Ollama could otherwise
+  judge cut input) is `unknown`. `pii` and `unknown` add the `pii` signal,
+  so the task takes the whole existing PII path (local or nobody, user review,
+  private envelopes, redacted views, no claude-mem). A pattern match is PII without
+  a call. The source is recorded as a `screened` history entry (`pii: regex`,
+  `pii: screen, <category>`, `pii: unknown, <reason>`, `clear`) and a `pii_screen`
+  event; an unknown verdict is a console and hub.log line with the task id and the
+  closed reason only. `route explain` on a draft does not call the screen and adds
+  a trace line saying a proposal would. The cost of `unknown` is the cost of any PII
+  task, even if a re-screen clears it later: it lifts every silent turn-free cohort
+  for good and turns facts off while open, and off campus triage is not asked, so a
+  classless proposal that is not a claim is refused with an error naming that.
+- Re-screen. Off campus with the device slot taken, the verdict is `unknown`. A
+  task whose last `screened` entry is `pii: unknown` (not `too long`, which a
+  second look cannot change), that is still `proposed` and that no peer ever owned
+  (no history entry carries an owner) has had nothing private sent anywhere, so
+  `Tasks.rescreen()`, on the daemon's 60 s release timer (one task per tick, the
+  least tried first, at most 10 tries per task in a hub run, in memory), screens it
+  again. `clear` lifts the `pii` signal through `Board.update` (a `screened` entry
+  `clear, screened again`), notifies by task, and routes it through the class
+  peers (a named owner or a claim is not remembered; a reserved owner, #207, is
+  offered first as `assign()` always does); `pii` settles it; another `unknown`
+  changes only the event record. A task an owner took (`local`) keeps its PII path,
+  also after it was declined back to nobody: its review notes, summary and decline
+  reason were never screened.
+- Free text (#69): the done summary, the review note with its unmet items, a
+  budget hand-off (once per hand-off, however many tasks it moves) and a
+  `hub_remember` note go through the same screen on an ordinary task when they
+  match no pattern; a match is recorded as a `regex` verdict without a call. The
+  call's cheap checks (owner, state, verdict, a running check, memory enabled) run
+  first, then the screen, then the checks again on a fresh read. An escalation's
+  reason is the hub's own text and stays pattern-only. `pii` or `unknown` withholds the
+  item exactly as a pattern match does (stubs, no memory note, no summary line in
+  completed-change or integration notices; `hub_remember` is refused). The board
+  keeps the text and marks the history entry `withheld: true`, so public views,
+  later reviewers, held cohort notices and `ahub ask` keep withholding it after a
+  restart without another call. The check output tail of a done note, a plan given
+  at accept, a decline reason, refs (paths, branch) and context checkpoint
+  summaries stay pattern-only.
+- Calibration (AC4): `test/fixtures/pii-screen.json` holds synthetic Korean and
+  English positives across the categories and hard negatives (roles,
+  placeholders, field and function names, ports, codes); none is copied from the
+  prompt, and its account, passport and resident numbers have impossible lengths
+  or dates. `bun scripts/pii-screen-eval.ts [--project <dir>] [--out <file>]` screens
+  each item once, in order, through `screenPii` with the project's configuration
+  and reports recall, recall as handled (pii or unknown), precision, the unknown
+  rate, held negatives, category agreement and latency. The bound, fixed here
+  before any measurement: the model itself labels at least 90% of the positives
+  `pii` (an unknown verdict counts as a miss). The report goes to
+  `docs/verification/`; the script exits 1 under the bound.
+
+## Amendment: research records (issue #247)
+
+- Opt-in per project (`research.enabled`, off by default). When a task is approved, the daemon builds its record from
+  the project's `events.jsonl` with the same function `ahub research backfill` uses (`taskRecords` in
+  `src/hub/research.ts`), so live and backfilled records agree, and appends it to the machine-wide store
+  `~/.agenthub/research/<sha256(project id)[0:16]>.jsonl`. Records hold ids, states, counts, tokens and times only,
+  because the events do; schema and fields: [research](../research.md).
+- The board has no terminal state but `approved`, and it is final, so each approved task gets one record; a person's
+  later verdict (`ahub task label`, including `abandoned`) is a separate label record bound to the task's proposal
+  time. A task is keyed by project, id and proposal time, because `ahub reset --all` restarts the ids and the store
+  keeps the older records. Measures (success, first pass, rework, check failures over checks run, tokens and wall time
+  per task) are derived when reported, never stored.
+- The record counts everything attributed to the task, the turn that approved it included: that turn ends after the
+  approval and its usage arrives later, so the writer waits until no open turn is attributed to the task (polled every
+  10 s, at most 30 minutes; a stopping hub writes once its peers have stopped). The first record written for a
+  task is final; a label binds to the current board's task, else to the store's only record with that id, or with
+  `--created` to a named one from before a reset. Task events carry the board's move `reason` (a closed
+  list) so reassignments are counted by reason.
+- Recording never blocks or fails the task flow: the writer runs after the board event, and a failure is one
+  hub.log line per run. ponytail: it reads the whole events file for each record; an incremental per-task index
+  if that file grows large.
+- Agents may read the measures and export; backfill and labels are a person's (identity gate).
+
+## Amendment: proven Pi tool refusals and idle exit recovery (issues #254, #255)
+
+- A trusted guard uses `PreEffectToolRefusal` only when that operation has performed no task or board effect; PII screening and its telemetry record may precede the refusal. Pi receives the same `error: <message>` refusal as the control client, and its session/call receipt is `done`. Initial task ownership/dependency/state checks and conductor entry peer/mode/assignment/escalation validation opt into the type; shared helpers default to ordinary errors, and conductor checks after an awaited release validation stay ordinary. Generic errors, board readback failures after a write, and receipt settlement write failures remain uncertain/pending and are never repeated. A legacy pending row has no pre-effect proof in its stored fingerprint/state/result, so startup preserves it; neither present board state nor a matching error message establishes historical refusal.
+- Each Pi owner reports one exit with cause, exit code or signal, whether startup completed, whether a turn/tool was active, whether teardown was expected, and the last validated tool name only. TUI shutdown/owner-loss and verified stop teardown lack observed OS status and record unknown. A successfully stopped claimed TUI owner reports once; a never-owned launch reports no invented exit. Internal teardown notices direct inspection and `ahub pi`, without claiming a person requested them. Console notices name the next action or automatic-start state; headless code 0 is still an exit and settles active deliveries as uncertain.
+- With `pi.auto_start`, an unexpected idle headless exit attempts its verified persisted session once in a 60 s window. The daemon owns the attempt/window across adapter replacements, blocks throughout an in-flight attempt, and rearms the 60 s window when that attempt settles. It checks current-owner identity, completed startup, turn/tool inactivity, start serialization, shutdown and recovery before and after awaited receipt drain/session capture. Missing or invalid persisted state leaves Pi offline with `ahub pi` guidance, with no fresh-session fallback. A second exit inside the window stays offline. Requested stops, stale owners, startup failures, active turns/tools and native terminal exits never trigger this automatic path; crash recovery's existing #66 behavior remains separate.
+## Amendment: benchmarks (issue #251)
+
+- `ahub bench` runs a person's suite file (tasks with a starting commit, an optional setup and a verify command)
+  against the peers attached to a hub, in a project opted in with `bench.enabled`, because every attempt resets the work
+  tree (`git checkout --force --detach <commit>` with HEAD checked against the pin, `git clean -ffdx -e /.agenthub`, then a
+  clean-tree check). Before
+  anything changes the runner requires the project to be the root of its repository, nothing tracked under `.agenthub/`
+  (in any letter case) in the tree or in any suite ref, every ref to be a commit, which it pins for the run, and a
+  clean tree. The runner is a console client: it proposes each
+  task as the console does and polls the board, so the task flow is unchanged and no new control request exists.
+- `setup` and `verify` run in their own process group, bounded; the group is stopped at the bound, on an interrupt and
+  when the command exits. An approved attempt's measures come from #247's `taskRecords` for the task proposed last with
+  that id, read once the turns started since its proposal have ended (waiting only while their peers are busy or
+  paused, at most 10 minutes, outside the attempt's duration); a timeout, an error, an interrupted wait, a wait that
+  runs out with the turn still open, or a hub status that cannot be read while it is open leaves none, never partial
+  ones. The fingerprint lists only the peers attached at the start.
+- Results go to `~/.agenthub/bench/<run>.jsonl` (ids, outcomes, exit codes, counts, times; never suite text or command
+  output). A run's state comes from its end record or its runner's liveness (`processLiveness`). Comparisons are
+  derived when asked: an arm is every run of it that is over (a stopped run included), runs of different suites or
+  suite versions are not mixed unless asked, and each difference has a seeded 95% bootstrap interval, inconclusive
+  below five attempts counted for that measure per arm (errors are not counted for pass rate or wall time).
+- A task that times out stops the run, because an agent may still work in the tree the next attempt would reset.
+  ponytail: a board state to withdraw an open task would let the run continue. The fingerprint holds what the hub's
+  status reports (a requested model for Pi, permission modes once #242 lands); ponytail: read each peer's launch
+  settings for the rest.
+- The dashboard snapshot carries run summaries and per-arm measures only. `bench run` is a person's (identity gate,
+  wherever `--json` stands); reading results is not. Schema and commands: [bench](../bench.md).