@staix/agent-hub 0.12.22 → 0.12.24

package/docs/operations.md

@@ -1,8 +1,25 @@
 # Operations guide
 
-This guide describes ahub 0.12.22 and control protocol 16. Live verification
+This guide describes ahub 0.12.24 and control protocol 16. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
+## Command output
+
+`ahub status`, `board`, `budget`, `doctor`, `projects`, `queue list`, `turns` and `report` print shared console tables and labelled details.
+`status --all` uses the projects table. `queue show`, `models status` and `budget execution status` show labelled fields; add `--json` for the raw fetched document.
+`report --by task` keeps the attribution and coverage sentences with section headings and aligned counters.
+Use `--json` for scripts; it returns the fetched data without color, and `status --json` keeps its existing document.
+In `projects --json` and `status --all --json`, an unavailable hub that explicitly refuses an inspection for SQLite contention also carries `failure: { "code": "database_busy" }`; it is additive metadata alongside the neutral `error` sentence.
+Text columns are a human interface, not a scripting contract. An identifier accepted as a command argument is whole wherever its available column can hold its own length:
+turn ids, queue ids, project ids, execution budget ids and ids in labelled views. Only status's informational settlement and hold ids are shortened;
+`status --full` keeps those whole too. Identifiers in suggested commands are always whole.
+
+`--color=auto|always|never` uses the console palette. Auto colors only a TTY with `TERM` other than `dumb`
+and empty `NO_COLOR`; pipes and redirects stay plain. Color never replaces a state or level word.
+TTY width is its columns (at least 80). A pipe uses a positive integer `COLUMNS` when supplied, otherwise rows
+are complete and unwrapped. Long fields wrap within their column; when whole metadata words and the readable flexible-column minimum do not fit, table bands retain every field. Each band carries the row id; when it cannot share a line with the metadata, a per-row id banner links them. Labelled two-column views keep each label beside its value, wrapping the value instead of separating labels and values into bands. In `turns`, the time and state cells wrap at word boundaries only when the file list needs the room and the listing gets shorter for it. When `projects` bands, the task list stays with the state columns in the first band and the second band is always PROJECT and ROOT. Console children receive the console's width
+minus its four-column indent and remain uncolored.
+
 ## Command help
 
 `ahub help`, `ahub --help` and `ahub -h` print the commands grouped by section;
@@ -47,6 +64,34 @@ its footer. The active tab is bracketed, as in `[2 Approvals]`, so it reads
 without color. The Approvals tab counts pending requests and the Queue tab
 counts `needs_review` deliveries, in the attention and failure tones.
 
+The console attention companion (#280) shows waiting, blocked, review, working,
+idle or asleep with separate action/watch counts. `n` selects the exact approval,
+held queue or review row, or prints applicable guidance; it never answers a
+request or runs a command. Editing, choices and confirmation retain their controls.
+`P` cycles the five built-in characters and off for the current console.
+
+Configure `pet` in `.agenthub/config.json` or `config.local.json`; local options
+override shared ones. Defaults are `character: "stai"`, `size: "line"`,
+`glyphs: "auto"`, `blink: true`, `bell: false`. Line preserves the three footer
+rows and prompt position. Mini/full reserve a bounded character rectangle and
+fall back when the terminal is too small. Supported glyphs and character choices
+are described below. `pet: false` or `ahub console --no-pet` disables presentation.
+Unknown options produce one bounded notice and fall back. Only an open approval
+blinks through the existing redraw; `blink: false` disables it. The optional bell
+sounds on an action-count transition from zero, at most once per minute, never
+for a message alone. Plain mode prints the line only when the action count changes.
+Messages addressed to `user` remain attention items until the next key. Drawing
+adds no timer, network request or writable settings path.
+Tabs change with the digits 1 to 5 or with Left and Right (wrapping at both
+ends), never while a command is being edited or a choice is open; under a
+confirmation an arrow dismisses it like any key but y, without moving a tab. A pasted
+chunk can only edit the command line, but a read that holds nothing but arrow
+sequences is that many key presses, so a held key repeats its tab move. In the Events
+tab a row's header line is tokenized and coloured exactly as the same event in
+the stream; only the header is tab-flattened before tokenizing. Body lines retain
+the previous rendering and stay plain, as does command output; colour never changes
+what the panel's text says.
+
 Peers, Approvals, Tasks and Queue are tables with a header row. A column is as
 wide as its widest cell, up to a third of the terminal; the last column takes
 the rest and is cut with `...`. In Tasks, TITLE takes the rest and the STAGE
@@ -78,7 +123,7 @@ prompts, are quoted unless they are a single word starting with a letter, so
 punctuation, a newline or a bare number in them cannot imitate the console's own
 structure. Under the `?` key table only `?`, Escape and `q` act.
 
-Arrow keys or j/k move, Enter opens a detail of labeled fields (relative times,
+Up/Down arrows or j/k move, Enter opens a detail of labeled fields (relative times,
 never JSON), Escape returns, and `?` shows the keys grouped by panel; in the
 stream, `?` prints that table and `v` prints the selected request as its push
 showed it. The footer's last line lists only the keys that act in the current
@@ -122,6 +167,60 @@ OS color preference through CSS. Both inline scripts and the style retain CSP
 hashes; there are no external chart/theme assets. Live theme/readability inspection
 is tracked in `docs/smoke.md` and remains unverified until performed.
 
+The dashboard Office section (#264, phase 1 of 4) draws the same snapshot as a
+static flat office: one desk per peer in a stable slot (claude, codex, kimi, pi,
+local, then others by id; a peer going offline dims its desk and never moves
+another), rooms for the board columns in a fixed order (To Do, Work floor,
+Review, Done shelf as a count only), at most 8 cards per room with "+N more"
+filtering the task list to that state, and at most 12 desks with "+N peers".
+Work-floor cards sit at the owner's desk, marked for rework; a busy peer's task
+bubble names its task only when it has exactly one in progress. Every peer
+condition (idle, busy, offline, paused, waiting on approval) has a glyph and a
+text label, and the scene carries ids, classes, states, kinds, counts and public
+titles only: message bodies, task details and approval titles never enter it.
+The scene adds no timer, frame loop or request and re-renders only when its
+signature changes. A View control offers Off (the default), Flat and
+Isometric; the choice is stored in a second host-scoped loopback cookie `agent-hub-office` with the
+same attributes as the theme cookie, and blocked cookie access defaults to Off
+without preventing operation. Desks and cards are focusable buttons; activating
+one scrolls to and highlights the matching list row, and a list row highlights
+its desk or card on focus and hover. The scene performs no action: every control
+stays in the lists. The View control's third option, Isometric (phase 4),
+renders the same model through the same code path with the grid coordinates
+projected (x' = (x - y) cos 30, y' = (x + y) sin 30): tiles become
+parallelograms, cards and labels stay upright, and the DOM order and
+accessible names are identical to Flat. Switching the view jumps to the new
+projection without animating; the settle rule and reduced motion apply
+unchanged. The live browser look is tracked in `docs/smoke.md` and
+remains unverified until performed.
+
+Motion (phase 2): card moves between rooms and desks, message arcs between
+desks (from the hub or the console they start at an anchor point), delivery
+warning marks and the busy latch all follow the snapshot. Motion is CSS only:
+transitions on transform and opacity (at most one second), keyframe fades for
+the transient marks. Arcs and marks hold, then fade out ten seconds after the
+event, timed at render from the model's timestamps; expired nodes purge on the
+next changed render or their own animationend, never on a timer. Arcs expire on
+the snapshot's own envelope clock, so an unchanged snapshot re-renders
+identically and writes nothing to the DOM. The scene goes straight to final
+positions on the first snapshot, after a project switch, after a snapshot gap
+over three seconds, or when one snapshot brings more than six transitions.
+`prefers-reduced-motion: reduce` removes all scene transitions and animations.
+Event reasons and bodies never enter the scene; arcs carry from, to, kind,
+priority, the task ref and the dropped flag only.
+
+Snapshot fields (phase 3): three additive optional fields, so older pages and
+older daemons mix freely and `PROTOCOL`/`EVENTS_SCHEMA` stay unchanged. A peer's
+open turn (`since`, `task`, `attribution`) names the busy bubble's task exactly
+instead of the single-in-progress-task heuristic, and a turn still open while
+the peer is paused adds a "finishing a turn" line under the Break sign. A task's
+`checking` flag draws a check-running mark on its card, which stays at its
+owner's desk (rooms follow states only). Warning `links` (overlap from the
+board's overlap test, cohorts, and recent turn-end conflicts the daemon keeps in
+a bounded in-memory list) draw dashed lines between the desks they name, labeled
+with kind and task ids; all three carry task and peer ids only, and a PII task
+never joins a link.
+
 Console color policy is `--color=auto|always|never`, with `auto` as the default.
 Auto enables color only when both input and output are TTYs, `TERM` is not
 `dumb`, and `NO_COLOR` is empty or absent. Explicit `always` overrides these
@@ -199,10 +298,12 @@ Launch that peer with `ahub claude` for channel pushes, or select `codex` in
 `roles` and launch `ahub codex`. The conductor splits work into owned tasks,
 observes `hub_status`, moves stalled work and obtains review before reporting
 results and open decisions. It does not implement the tasks it handed out.
-`hub_peer_start` starts local, Kimi or headless Pi; requests for native TUIs
-return the `ahub` command for the person to run, after validating it through
-the shared launcher planner. The wrapper plans again at launch when native
-endpoints are available. `hub_peer_hold` and `hub_peer_release`
+`hub_peer_start` starts a peer in the start mode a person set for it (see
+"Start modes"): local and headless Kimi, Pi or Codex start at once; for a
+TUI peer the hub opens a terminal running the fixed `ahub <peer>` command,
+after validating it through the shared launcher planner, and when it cannot
+open one the call fails with that command for the person to run. The
+conductor cannot choose the mode. `hub_peer_hold` and `hub_peer_release`
 manage only holds placed by that conductor. Assignment also requires `assign`
 when the conductor has an explicit capabilities list.
 
@@ -351,7 +452,7 @@ Managed launchers attach native peers to the project daemon:
 ahub claude
 ahub codex
 ahub kimi
-ahub pi --mode headless --backend auto
+ahub pi                 # its TUI; --headless for the background peer
 ahub local
 ahub local --model <served-model-id>
 ```
@@ -380,7 +481,19 @@ A delivery in `needs_review` holds later deliveries to that peer. The console an
 the hold once, and status, task assignment and route explanations name its delivery id.
 Inspect it with `ahub queue show <id>` and explicitly choose `completed`, `retry` or
 `discard` through `ahub queue resolve`. Reassignment or approval of its task never
-resolves an uncertain delivery automatically.
+resolves an uncertain delivery automatically. The same rule holds on every path that
+assigns a task (#297): once the move is saved on the board, a failed delivery prints
+exactly one console notice ("the move is saved... delivery is not confirmed"), printed
+where the error is thrown, and the caller (a peer in its turn, or the CLI) still gets
+its error. Two exceptions, by construction: a move superseded while the assignment was being prepared, meaning a later history entry that moves or settles the task (another assignment, an unassign, the owner's accept, done, approval, close; the hub's quiet bookkeeping such as a late check result or a reviewer change does not supersede), is
+the caller's error as before, with no notice naming either owner; and a claim is its own hand-over, so its
+accepted write and line stay outside the delivery rule (its overlap and routing announcements to earlier
+owners are deliveries and share it). The repair is always
+to look for a queued or needs_review delivery with
+`ahub queue list --peer <owner>` (then `ahub queue show <id>`, or the accepted entry in
+`ahub task show <id>` if the journal itself is down) and then send the assignment again
+with `ahub task assign <id> <owner>`. Nothing resends automatically: a blind resend can
+duplicate a delivery that actually left.
 
 Reviewer candidates follow `[classes.review].peers`, then attached peers with a
 `reviewer` role in `roles`. The owner cannot review its own task. If none is available,
@@ -582,6 +695,30 @@ ahub research backfill             # build this project's records once from even
 ahub task label 12 reverted        # a later verdict (ok, regressed, reverted, incomplete, wrong, abandoned)
 ```
 
+## Hub memory
+
+The hub keeps its own memory in `~/.agenthub/memory/` beside claude-mem ([how it works](memory.md)): notes saved
+against an open task are short-term; when the task is approved its decisions, contracts and fails become long-term.
+Task briefs, session-start recall and `ahub ask` read it first, and the dashboard has a Memory section.
+
+```bash
+ahub memory                              # this project's entries, newest first
+ahub memory search parser                # every word must match
+ahub memory show 1a2b3c4d                # one entry, its provenance and edges
+ahub memory forget 1a2b3c4d              # a person's; also promote, demote, supersede, rebuild
+```
+
+`"memory": { "native": false }` in `.agenthub/config.json` turns it off for a project.
+
+Between your machines, through a private git remote, with long-term tasks that span them:
+
+```bash
+ahub memory sync --remote git@github.com:you/agent-hub-memory.git   # once per machine; then every 10 minutes
+ahub goal new "native memory"                                        # a long-term task
+ahub goal                                                            # open ones, who holds each and until when
+ahub goal take 1a2b3c4d --force                                      # take one over from another machine
+```
+
 ## Benchmarks
 
 In a git repository kept for benchmarks (`"bench": { "enabled": true }` in its `.agenthub/config.json`, a clean tree),
@@ -644,7 +781,7 @@ ahub undo <turn> --yes --context  # Codex's latest turn: also drop it from Codex
   has not removed yet included, and a PII file left in the project is
   snapshotted by later turns like any other file. Keep PII files in an ignored
   directory.
-- A turn the hub stopped in the middle of shows as `(no end snapshot)` and
+- A turn the hub stopped in the middle of shows the state `no end snapshot` and
   cannot be undone.
 - Claude's turns are not recorded: its channel shows the hub no turn boundary.
   Claude Code's own checkpoints cover its edits, though not its shell commands.
@@ -875,7 +1012,7 @@ denylist (Pi and local), or native vendor boundaries (Claude and Codex).
 | --- | --- | --- | --- |
 | Kimi Code CLI | ACP yolo | ACP auto | ACP default |
 | Codex | on-request for every outgoing turn/start | never for every outgoing turn/start | Restore the known native policy once, then stop overriding |
-| Claude | Allow resolving project file tools outside .agenthub/.git/.claude/.codex/.qwen/.kimi/.pi/.mcp.json | Hook allow for every tool | No hook decision |
+| Claude | Allow resolving project file tools outside .agenthub/.git/.claude/.codex/.qwen/.kimi/.kimi-code/.pi/.mcp.json | Hook allow for every tool | No hook decision |
 | Pi and local | Grant write/edit outside native agent configuration paths; read never asks; shell/git writes ask | Grant each tool once within the existing sandbox/guard | Normal approval handling |
 
 Kimi's map applies only to the actual Kimi Code CLI identity, not another ACP
@@ -956,6 +1093,246 @@ permission_mode (peer/from/to) with no tool arguments under events schema 1.
 The optional control requests preserve PROTOCOL; an older hub answers unknown
 and the CLI advises upgrading.
 
+## Change the participating peers while the hub runs
+
+`ahub roster` lists every known peer, whether it participates, its start mode,
+current state, queued messages and open tasks. `ahub roster --json` is the same
+ordered catalog view for scripts. Status and the console keep their existing lazy
+rows; an off-roster peer is shown only while it has retained messages, an uncertain
+delivery or open work, with the words `off roster`.
+
+```bash
+ahub roster
+ahub roster remove kimi --yes         # print the preview, confirm and remove
+ahub roster remove kimi --yes --now   # stop a busy owned runtime before handing work over
+ahub roster add kimi
+ahub settings set roster.kimi false --preview
+ahub settings set roster.kimi false --yes
+```
+
+These are person's commands and use the same settings preview, write and undo as
+the dashboard's Roster settings. An ordinary dashboard session may remove a peer;
+adding requires `ahub ui --settings` or a person's terminal. Removal requires the
+peer id as confirmation. Without `--now`, a busy peer is refused. A conductor
+holder cannot be removed until its role is moved.
+
+Removal fences membership, stops hub-owned runtimes or detaches sessions in a
+person's terminal, and then hands work over. The removal preview and result name
+the peer whose existing work the person must stop in that retained terminal;
+the preview names the roles offered and those with no eligible replacement; the
+result lists the saved owner/reviewer moves and every assignment that stays. No stop notice is forced into
+a detached session and nothing bypasses the journal. Codex 0.146.0
+exits its TUI on the close-4000 disconnect and does not reconnect automatically.
+Its app-server and proxy remain available; after `ahub roster add codex`, run
+`ahub codex resume <thread-id>` (the full id is printed in the preview, removal
+result and return) or `ahub codex resume` to select its previous native session. Removal never closes
+the terminal window itself. The Claude channel retries and reconnects on return.
+Pi return retains the verified owner's monotonic generation even after refused
+native activity while detached; it shares no personal output and invalidates any
+cached empty-session resume proof after that activity.
+It leaves queued and held deliveries, and existing manual or budget pauses,
+untouched. The queue listing names `off roster` as the membership hold. Returning
+and starting the peer makes retained queued messages available again; held
+uncertain work still needs the existing queue resolution command. A detached
+personal Pi TUI with a live owner still blocks controlled recovery as `pi is not
+settled`; end that retained TUI before restart/upgrade. The hub does not declare
+a live native owner settled or close it implicitly during preparation. Open owner and
+reviewer work, including ownership of `in_review` tasks, is offered through the
+existing reassignment path; a transferred review keeps its review state. If nobody can
+take it, its assignment stays and a notice names the person's next action. Task
+text in a notice uses its public title, so a private task remains a stub. A stop
+that is unconfirmed leaves the roster saved and reports that permission reset and
+handoff were not attempted; reapply the removal after checking the runtime.
+
+A hub task, verdict, review or budget message addressed to an off-roster peer
+stays in its retained queue, with one public notice to the person. Task operations
+use the current owner and reviewer after reassignment. A mixed addressed audience
+receives the on-roster copies now and retains the off-roster copies; the sender
+sees the existing notice field (or a decision note for native answers). Broadcasts
+exclude off-roster peers; a person or agent addressing only removed peers is
+refused before publishing. The dashboard roster undo has its own peer-id
+confirmation and optional active-turn stop checkbox.
+
+Without a roster setting, participation keeps the previous defaults. An explicit
+`roster.pi` overrides `pi.enabled`; otherwise that legacy switch continues to
+control Pi starts. External peer ids remain governed by their existing admission
+rules. A runtime permission override is cleared on removal and the configured
+default governs the next attachment. Config file edits outside the authorized
+roster setting do not change running participation: they take effect at the next
+hub start. The tracked config can provide defaults and config.local.json can
+override them.
+
+## Settings from the dashboard and the terminal
+
+The dashboard's Settings section and `ahub settings` show and change the same
+closed list of settings (issue #269). Run them from a plain terminal:
+
+```bash
+ahub settings                      # every setting: value, source file, when it applies
+ahub settings get permission.kimi
+ahub settings set routing.classes.implement.peers codex,kimi,pi --preview
+ahub settings set routing.classes.implement.peers codex,kimi,pi
+ahub settings set permission_modes.kimi ask-when-needed
+ahub settings set research.enabled inherit   # remove the machine-local value
+ahub settings undo                 # put back the file the last write changed
+ahub ui --settings                 # dashboard with a 15-minute settings session
+```
+
+| Group | Keys | Stored in | Applies |
+| --- | --- | --- | --- |
+| Permissions | `permission.<peer>` (the mode now) | the running hub only | at once |
+| Permissions | `permission_modes.<peer>` (the mode at hub start) | `config.local.json` | next hub start |
+| Start | `peers.pi.start_mode`, `peers.codex.start_mode`, `peers.kimi.start_mode` (`tui` or `headless`) | `config.local.json` | that peer's next start |
+| Start | `pi.auto_start` | `config.local.json` | next hub start |
+| Routing | `routing.stay_switch`, `routing.classes.<class>.peers`, `.escalate_to`, `.route`, `.pi_backend` | `routing.local.toml` | at once |
+| Switches | `research.enabled`, `approvals.notify`, `snapshots.enabled`, `coordination` | `config.local.json` | next hub start |
+
+- Writes go only to `.agenthub/config.local.json` and `.agenthub/routing.local.toml`,
+  the machine-local files (`ahub init` ignores both in git). The shared
+  `config.json` and the hand-written `routing.toml` are never rewritten, and a
+  machine-local file that is committed to git is refused. Each write is read by
+  the hub's own loader first and replaces the file atomically.
+- `routing.local.toml` overrides `routing.toml` key by key and may hold only the
+  routing keys in the table. `ahub route explain` and the Settings rows name the
+  file each value comes from. `--preview`, and the dashboard's Preview button,
+  show `ahub route explain` for the open tasks before and after, or what a
+  permission mode grants, and save nothing.
+- A row shows the value in force, its source file, when it applies, and for a
+  value read at hub start what the next start will read (`Pending restart`).
+- `ahub settings undo` (the dashboard's "Undo last write") puts back the one
+  previous version of the file the last write changed. It refuses when that
+  file was edited since, and when it would put a stored never-ask back (set it
+  again with its confirmation instead). A mode changed for the running hub is
+  not a file: set it again instead. Setting a value it already has, or
+  removing one that is not set, writes nothing. A project with no
+  `.agenthub/config.json` gets no first config file from a settings write
+  (any config file turns the project defaults on): run `ahub init` first.
+- A project initialised before 0.12.23 has no `.gitignore` line for
+  `.agenthub/routing.local.toml`: run `ahub init` again, or add it. A
+  `permission_modes` value is read only from a file git confirms nobody
+  committed (config trust); where the hub will not read what was written, the
+  reply and the Settings row say so.
+- Authority: a dashboard opened with `ahub ui` reads settings, lowers a mode to
+  `ask`, turns `pi.auto_start` off, sets a start mode back to `tui` and changes
+  the Switches group. Everything
+  else needs `ahub ui --settings`, whose session may raise for 15 minutes, or
+  `ahub settings` in a terminal. `never-ask` needs the peer id typed in the
+  dashboard, or `--yes` in the terminal, and a stored never-ask default still
+  waits for `y` in `ahub console` at each hub start. Tool approvals stay
+  deny-only for Pi and local in every session.
+- Commands and binaries, credential files, gateway URLs and the local worker's
+  reach are never editable here: edit `.agenthub/config.local.json` yourself.
+- Every change is announced in `hub.log` and open consoles with its source and
+  recorded as a `settings` event. `ahub settings` needs a running hub; an older
+  hub answers the request as unknown and the CLI advises upgrading. The unified
+  dashboard (`ahub ui --all`) acts as an ordinary session.
+
+## Start modes: TUI by default, headless as opt-in
+
+A peer that has a TUI the hub attaches to starts in it by default (issue #269).
+
+| Peer | Default | Headless |
+| --- | --- | --- |
+| pi | `tui` | `ahub pi --headless` (or `--mode headless`), or `peers.pi.start_mode: headless` |
+| codex | `tui` (`ahub codex`) | `peers.codex.start_mode: headless`: a hub-made start runs the app-server only |
+| claude | `tui` (`ahub claude`) | none |
+| kimi | `tui`, pull-only (`ahub kimi`) | `ahub kimi --mode headless`, or `peers.kimi.start_mode: headless` |
+| local | headless (hub-native) | not applicable |
+
+- **You type the command:** `ahub pi` opens Pi's TUI in that terminal.
+  `--headless` and the start mode setting are the two ways to ask for the
+  background peer. `ahub settings set peers.pi.start_mode headless` writes the
+  setting; it applies at Pi's next start.
+- **The hub starts the peer** (the dashboard's Start control, `pi` typed in
+  `ahub console`, the conductor's `hub_peer_start`, `pi.auto_start`): it
+  follows the peer's start mode. For `tui` it opens a terminal running the
+  fixed command `ahub <peer>`, through a terminal provider:
+  1. `terminal.open` in `.agenthub/config.local.json`, an argv in which one
+     element holds `{command}` (the quoted command line to run); `{title}` and
+     `{cwd}` are replaced too. Examples:
+     `["tmux", "new-window", "-n", "{title}", "{command}"]`,
+     `["wezterm", "start", "--cwd", "{cwd}", "--", "sh", "-c", "{command}"]`.
+     Only a config file nobody committed may set it, and it is not a setting
+     the dashboard or `ahub settings` can write. It is read at hub start.
+     `{command}` is quoted for a POSIX shell; `{title}` and `{cwd}` are raw,
+     so give each an argv element of its own.
+  2. Orca, when the hub runs in an Orca worktree or an earlier `ahub <peer>`
+     launch of this project recorded one (the path recovery uses).
+- **No provider:** the start is refused with the command to run by hand. It is
+  never downgraded to headless. `ahub settings` lists each start mode, and the
+  dashboard's Start control says which mode a start will use and where its
+  terminal comes from.
+- **Dashboard Start:** the control is locked while its request is in flight. A confirmed answer unlocks it immediately, so a retry reaches the hub's own 30-second terminal reopen guard and shows any known refusal. The unified dashboard waits 35 seconds, covering a terminal provider's 30-second cap plus a 5-second response margin; a slower headless start can still end unconfirmed while the hub continues. Check the Peers panel before retrying. An unconfirmed unified-dashboard start holds that peer's control for the shared 30-second reopen bound, or until its `starts` snapshot confirms attachment, across redraws and project switches within the same hub instance; the row states the retry bound. The project-local dashboard keeps its usual confirmed-answer behavior. Other forwarded actions keep their 10-second wait; the manager opens no settings session.
+- The conductor cannot choose the mode: `hub_peer_start` takes the peer's own.
+- Recovery restores each peer in the mode its recorded session had. After an
+  unplanned stop, a Pi that ran in a terminal is reported with its command and
+  is not replaced by a headless one unless headless is its start mode.
+
+### Kimi in its own TUI
+
+`ahub kimi` runs Kimi in the person's terminal by default. The launcher atomically
+merges only `mcpServers["agent-hub"]` in `.kimi-code/mcp.json`, keeping foreign
+entries and fields. It contains machine paths and the peer identity, not a token.
+`ahub init` ignores that file when it is untracked; a tracked file is still written
+with a warning. `--print-command` shows the change and command without writing.
+The configured `kimi_cmd` must be a single executable or end in exactly `acp`;
+the TUI uses the executable or drops that final word. Other wrappers are refused
+with the headless command rather than guessed.
+
+The TUI is pull-only. Its model reads `hub_inbox` at the start of work and before
+reporting, and shares results explicitly with `hub_send`. Status, the console and
+the dashboard show `pull-only`, the waiting count and the last inbox read. Messages
+and important markers do not push or interrupt it. There is no hub busy state,
+watchdog, console approval, hub permission mode, context reading, automatic quota
+pause/handoff, shared final answer or session resume. Read quota and approve tools
+in Kimi's own TUI; a person can pause the hub queue by hand. End the native terminal
+session there, not with `ahub stop kimi`.
+
+Automatic routing never picks a pull-only owner or reviewer, even as the only
+candidate. A proposer can name the owner or claim its own task; a person or the
+conductor can name an owner or reviewer with
+`ahub task assign <id> kimi --role owner|reviewer`. A waiting task reserves its
+named owner; naming its reviewer is refused until dependencies are approved.
+A named review waits in the same inbox. Queue holds and pauses refuse a pull with
+the reason; an unaccepted assignment still follows the existing release deadline.
+
+To switch to ACP, end the attached TUI and run `ahub kimi --mode headless`: the
+person's command removes only the hub's project MCP entry before starting ACP.
+A daemon-made headless start refuses a stale entry with that command and never
+edits the project file. To switch back, stop the headless peer with `ahub stop kimi`
+then run `ahub kimi --mode tui`. The peer id, queued messages and open tasks remain;
+the ACP session is not resumed in the TUI. Agents cannot switch modes.
+
+Projects with no explicit Kimi start mode also move to this default on upgrade.
+The coordinating upgrade command announces it once; to keep ACP, run
+`ahub settings set peers.kimi.start_mode headless`.
+
+Source preflight checked Kimi Code 2.1.1 at
+[f67e6398](https://github.com/MoonshotAI/kimi-code/tree/f67e6398fb3210ad8ace970e2dfd5bcc984ed61f):
+trusted ACP workspaces read the user, repository-root and project MCP files, and a
+passed session entry connects beside the project entry. Its model request path
+uses tool definitions and managed AGENTS instructions, not MCP initialize
+instructions. Folder trust, real TUI tool discovery and the model round trip are
+still unverified live; see `docs/smoke.md`.
+
+### Migration from 0.12.22 and earlier
+
+Pi's default changes from headless to its TUI.
+
+- `ahub pi` in a terminal now opens the TUI. For the background peer run
+  `ahub pi --headless`.
+- A project with `"pi": { "auto_start": true }` used to get a headless Pi at
+  every hub start. To keep that, set the start mode once:
+  `ahub settings set peers.pi.start_mode headless` (or add
+  `"peers": { "pi": { "start_mode": "headless" } }` to
+  `.agenthub/config.local.json`). Without it the hub opens Pi's TUI in a
+  terminal at start, or, with no terminal provider, says
+  `pi.auto_start did not start Pi` with the command to run.
+- Scripts and the console's `pi` command: without a terminal, `ahub pi` asks
+  the hub to open one. Add `--headless` where a headless Pi is meant.
+- A conductor's `hub_peer_start` no longer takes a mode. A call that passes one
+  is refused unless it repeats the peer's start mode.
+
 ## Approvals and pauses
 
 Inspect permission requests in the terminal:
@@ -995,6 +1372,13 @@ 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.
 
+Kimi Code CLI 2.1.1's observed 5-hour usage-limit refusal creates a hard budget reading (`kimi ACP usage-limit refusal`). `ahub status` shows a budget pause and `ahub budget` shows its source and reset estimate. The refusal gives no reset timestamp, so the hub estimates the reset at five hours after it was observed and resumes on the next budget tick after the existing one-minute grace. With `budget.wait_max_min` below that estimate, the existing budget relay automatically hands open tasks to an attached eligible peer; routing skips Kimi while paused. No checkpoint is requested from an exhausted agent.
+`ahub budget resume kimi` overrides the reading so the provider can be tried early. A new provider refusal ends that override and pauses it again; a pending soft checkpoint cannot postpone this hard pause.
+During one hub run, an early override followed by the same window's refusal keeps its earlier future reset bound; a provider's explicit reset remains authoritative. A restored pause without a per-window reading cannot identify that earlier window, so its next refusal starts a new estimate.
+Unread quota resume notices are coalesced without losing their public task moves; the next notice lists moves accumulated across those pauses. An older notice without structured move metadata is kept as public text inside that notice.
+
+A refused prompt with no acceptance or activity is requeued without a review hold. At the estimated reset it is tried again; another quota refusal pauses it again without consuming the poison-envelope retry count. Work that already started remains held for review even while its open tasks move to other peers. After the quota reset its queue stays held: inspect `ahub queue show <delivery-id>` and the associated task, then choose `ahub queue resolve <delivery-id> --action completed|retry|discard --reason "<text>"`. Do not retry work that another owner already took over without inspecting it. If the hub cannot confirm the pause, the refusal is also held instead of spending retries. Other errors keep their ordinary review behavior. Only the observed Kimi 5-hour text is recognised; weekly/monthly limits and other ACP vendors, including Qwen, remain unverified. The recognised text and its provenance live in `src/adapters/acp-quota.ts`.
+
 Quota also shapes routing and handoffs:
 
 - Among peers a task could go to, those with quota readings are ordered by
@@ -1052,8 +1436,8 @@ Only `ahub claude` starts Claude Code with the development-channel flag. A
 Claude session started another way (plain `claude`, an IDE) keeps the hub tools
 but cannot show pushes, so it attaches tools-only (protocol 16, issue #205):
 
-- Its messages stay queued. `ahub status` shows `queued N` and `tools-only:
-  messages wait for hub_inbox; for pushes restart Claude with ahub claude`; the
+- Its messages stay queued. `ahub status` shows the queue count in `Q` and a `tools-only` detail:
+  `messages wait for hub_inbox; for pushes restart Claude with ahub claude`; the
   console footer shows `tools-only: ahub claude` and the dashboard shows the
   status line.
 - The session reads them with `hub_inbox`, at most ten messages at a time plus
@@ -1183,8 +1567,8 @@ can run again), unless the error says the state cannot be read (a damaged
 `hub.db` or journal fails the same way every time): `ahub reset --all --yes`
 archives such a state directory as it is. A full reset names the archive once
 the state directory has moved.
-It never touches claude-mem: notes saved with `hub_remember` are shared memory,
-not hub state. Claude Code sessions attached to the hub lose their hub session;
+It never touches claude-mem or hub memory (`~/.agenthub/memory/`): notes saved with
+`hub_remember` are shared memory, not hub state. Claude Code sessions attached to the hub lose their hub session;
 relaunch them with `ahub claude`.
 
 ## Orphaned daemons
@@ -1230,21 +1614,21 @@ section is what they run.
 
 Upgrade running projects with the target release's own coordinator. It accepts
 a running source on control protocol 9 (0.6.x), 10 (0.7.0 through 0.12.0),
-11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15), 14 (0.12.16), 15 (0.12.17 through 0.12.19) or 16 (0.12.20 through 0.12.22), and only
+11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15), 14 (0.12.16), 15 (0.12.17 through 0.12.19) or 16 (0.12.20 through 0.12.24), and only
 a target on its own protocol, so the target's coordinator fits every supported
 source and carries every recovery fix released up to it. Protocol 8 and older
 (0.5.x and earlier) are refused as `manual-bootstrap-required`. Run from the
 project directory, without replacing the global CLI first:
 
 ```bash
-bunx --package @staix/agent-hub@0.12.22 ahub upgrade --to 0.12.22 --dry-run
-bunx --package @staix/agent-hub@0.12.22 ahub upgrade --to 0.12.22 --yes
+bunx --package @staix/agent-hub@0.12.24 ahub upgrade --to 0.12.24 --dry-run
+bunx --package @staix/agent-hub@0.12.24 ahub upgrade --to 0.12.24 --yes
 ```
 
 | Running now | Coordinator to use |
 | --- | --- |
 | 0.6.x (protocol 9) | the target's, through `bunx` as above |
-| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 through 0.12.19 (protocol 15), 0.12.20 through 0.12.22 (protocol 16) | the target's, through `bunx` as above |
+| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 through 0.12.19 (protocol 15), 0.12.20 through 0.12.24 (protocol 16) | the target's, through `bunx` as above |
 | any supported source, with the installed CLI already at the target | `ahub upgrade` below, which is the same coordinator |
 | 0.5.x or earlier (protocol 8 and older) | not supported: bootstrap by hand with the matching CLI |
 
@@ -1276,14 +1660,14 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.22 --dry-run
+ahub upgrade --to 0.12.24 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.22 --yes
+ahub upgrade --to 0.12.24 --yes
 ahub recovery status [<operation-id>]
 ahub recovery resume [<operation-id>]
 ahub recovery abort [<operation-id>]
@@ -1510,6 +1894,28 @@ next actions").
   restart snapshot.
   A second `resume` while its own hold still stands checks the peers again
   before it closes anything.
+- If a restart stops with `database_busy`, the receipt stays `blocked` and
+  carries `failure: { code: "database_busy", retryable: true, site: [...] }`.
+  Let the other connection settle, inspect `ahub recovery status <id>` and
+  use its offered `ahub recovery resume <id>`. Resume rechecks the source and
+  reconciles a commit that may already have been requested. A busy read while
+  that committed source is stopping stays inside the existing shutdown wait.
+  A stop-and-archive that meets contention instead says to retry that
+  disposition; resume remains refused while abandonment is partway. Successful
+  abort, fresh-session choice and disposal clear the earlier failure annotation.
+  Do not delete database files or start a second operation to bypass the lock.
+  A failed installed-layout CI restart retains bounded, redacted fixture logs,
+  receipt fields (including `commitSent` and failure frames) and file-mode
+  metadata as a per-OS artifact.
+
+  The historical CI receipt (38061057253, attempt 1) kept no throw site or
+  hub log. At its main, status/inspect RPC failures were swallowed and the
+  synchronous catch sent a fixed sentence, so its raw SQLite text could only
+  have come from the commit rejection or the runner's own `registry.db` read.
+  "Resume | wait until the hub settles", without stop-and-archive, means its
+  next inspection saw neither running nor stopped/missing. Which of the two
+  paths, which statement and which holder remain unknown. The controlled
+  rollback-copy reproduction is separate evidence, not that historical cause.
 - When a target hub dies after it started (a crash or a reboot), `resume`
   starts it again from the operation's snapshot while the project's state
   directory still holds it: it records the restart (status shows `restarts`),
@@ -1648,8 +2054,9 @@ crash of one is not reported this way.
   spends no cloud quota), and on a fresh session if that fails, keeping the
   recorded backend and model; the report says which. Malformed records in
   `sessions.json` are skipped. A Pi that ran in a terminal (`--mode tui`) is never started on its
-  recorded session by the hub; the report gives the command, and with
-  `pi.auto_start` a fresh headless Pi starts instead.
+  recorded session by the hub; the report gives the command. With
+  `pi.auto_start` a fresh headless Pi starts instead only when Pi's start mode
+  is headless; with the default (tui) nothing is started in its place.
 - Codex's app-server died with the hub; run `ahub codex` again. Claude Code's
   plugin reconnects by itself while that session is open.
 
@@ -1776,7 +2183,7 @@ whose MLX slot is still busy after that wait goes to `dgx/fast` first (`source:
 so does an enforced tool loop pinned to it (`source: "pin"`); without it nothing moves for load. `dgx/fast`
 never goes first while it is cooling down, or while its own last dispatch failed in any way,
 an error status or a failed stream included, until it succeeds or 30 s pass (`ahub status`:
-`last dispatch failed, no load moves until ...`). No load move or pin happens while the request
+a `dispatch held` detail with a relative time and `no load moves until then`). No load move or pin happens while the request
 runs under an execution budget, and enforced, a load move happens only at a user turn. A moved
 attempt gets 15 s to its response headers after the gateway lookup (OmniRoute's own probe,
 up to two 4 s rounds when no gateway is cached) and is then abandoned for MLX, which serves
@@ -1790,7 +2197,7 @@ consecutive transport or startup failures outside a cooldown (a failure more tha
 the last counted one starts the count over), a relay alias cools down for 30 s, doubling up to
 5 min. A busy MLX slot and timeouts cut short by an execution budget never count; any HTTP
 answer, a success or an error status, proves the transport works and ends the streak and the
-cooldown. `ahub status` shows `cooling down until ...` on the backend line and `events.jsonl`
+cooldown. `ahub status` shows a `cooling` detail with a relative time and failure count and `events.jsonl`
 records `cooldown` events.
 Progress judgements suggest reassignment; they never change task ownership.
 
@@ -1898,7 +2305,12 @@ include the stamped ancestors (CI checks out full history).
 During release preparation, source review precedes restamping. Review each stale
 page against its covered source, correct drift, and use the full SHA of the
 reviewed source commit as `verifiedAgainst`. Record any deferred page and its
-specific unverified claims in the release verification report before tagging.
+specific unverified claims in the release verification report before tagging. Deferred
+pages must still be source-reviewed and current; a deferral is not a stale-stamp waiver.
+The tag gate runs `node scripts/check-docs.mjs --require-fresh` with full history
+before publishing. Stale or nonancestor stamps refuse publication, with the
+release merge-commit instruction; an identical tree and green CI cannot waive this.
+
 Do not advance a stamp solely to clear a notice. Source stamps can name an
 ancestor: the manifest-only follow-up commit need not hash or stamp itself.
 
@@ -1930,7 +2342,8 @@ sequential seeded-guard job. Main and release jobs reuse only a successful full
 PR or push check with the identical Git tree and all three successful jobs. An absent or
 unreadable result runs the main gate again and refuses release. A manual
 `prepare_bundle` dispatch builds reviewable plugin assets without publishing;
-it is never accepted as full-gate evidence.
+it is never accepted as full-gate evidence. A `timing_runs=20` dispatch runs only the daemon, PII screen and ACP
+test files twenty times on macOS, in its own concurrency group; it does not replace the full gate.
 
 ## Preview initialization and native launch
 
@@ -1959,9 +2372,19 @@ ownership, bind servers or start agents, sidecars or models.
 `ahub status`, `ahub tail` and the dashboard show native context occupancy,
 source and measurement freshness. Claude readings come from the status-line
 tee installed by `ahub claude`; Codex readings come from its current thread's
-native token-usage updates. Pi and other unsupported surfaces show unknown.
+native token-usage updates. Kimi readings come from its ACP `usage_update`
+(`{used, size}`, source `acp_usage_update`): context occupancy, not
+consumption, so no token total is counted from it; the adapter accepts the
+update whenever it names the current session, because 2.1.1's source text
+emits it after the turn settles (read from the source, not yet observed live
+through the hub; docs/smoke.md), so the peer may already be idle.
+Pi and other unsupported surfaces show unknown.
 A stale or disconnected reading is unknown, not 0%. Codex's accumulated session
-usage is never used as context occupancy.
+usage is never used as context occupancy. In the tail (`ahub tail` and the
+console's stream) a reading prints once and repeats only when the line changes
+apart from its time: the printed percentage, the freshness, the source, or known
+against unknown. Status, the Peers panel and the dashboard always read the
+latest reading with its time.
 
 Context-triggered checkpoints are disabled by default. To enable them, add
 this to `.agenthub/config.json` and restart the daemon deliberately:
@@ -1973,8 +2396,9 @@ this to `.agenthub/config.json` and restart the daemon deliberately:
 `gate` is a fraction between 0 and 1; 0 disables checkpoint requests.
 `stale_min` must be positive. A reading at or above the threshold records a metadata-only
 event and console notice, then asks an attached Claude/Codex with active work
-for a checkpoint when no checkpoint request is already outstanding. The request
-supplies a `request_id`; include that id with
+for a checkpoint when no checkpoint request is already outstanding (an ACP peer
+such as Kimi gets the event and notice only; no checkpoint request is sent to it
+yet). The request supplies a `request_id`; include that id with
 `hub_checkpoint {summary, request_id}`. Repeated high readings do not repeat
 it until a fresh below-threshold reading or new session rearms the crossing.
 
@@ -2090,3 +2514,422 @@ prompt was accepted but before history was persisted is not treated as empty:
 its delivery is held, and another start refuses until resume history is verified.
 Inspect and settle the held delivery before deliberately replacing that unpersisted
 session by restarting the hub; the stop never silently chooses a fresh session.
+
+A pull-only Kimi TUI has no controlled restore or resume. While it is attached,
+upgrade/restart planning stops before effects and asks the person to end Kimi in
+that terminal and make a new plan. Headless Kimi restoration stays headless even
+though the unset launch mode now means TUI; older targets keep their legacy
+command without a mode flag. Native recovery remains unverified.
+
+Changing a reviewer on a task in review withdraws unread requests and tells the
+former reviewer its request is withdrawn. A delivered request cannot be recalled,
+but a later verdict from that former reviewer is refused by current authority.
+
+Legacy Claude pull-only sessions retain their existing automatic owner/reviewer
+selection; the watched-Kimi exclusion does not disable that review path. After
+first creating the Kimi MCP file, run `ahub init` to ignore the untracked file.
+Init leaves existing ignore bytes alone when no Kimi MCP file exists.
+## Scoped grants for instruction files
+
+`ahub settings set scoped_grants.protect_instructions true` asks a person before
+Pi/local scoped writes and edits to `AGENTS.md`, `CLAUDE.md` and `QWEN.md`, and
+withholds automatic permission from the managed Claude hook. Case, compatibility
+forms and both symlink spellings are checked. The default is false: these project
+documents remain editable under scoped grants. Reads, explicit approval and
+never-ask keep their existing behavior.
+
+Use `ahub settings preview scoped_grants.protect_instructions true` before a
+change and `ahub settings undo` to restore it. It is in the Permissions registry,
+writes only machine-local `protect_instruction_files`, and applies immediately
+in the running hub. A dashboard settings session may change it; an ordinary
+session may turn protection on but cannot weaken it. No agent surface changes it.
+Like other machine-local security defaults, loading it requires git to establish
+that the file is untracked; a dropped value is reported by the settings result.
+
+## SDLC artifact receipts and gates
+
+The initial #257 lifecycle is off without .agenthub/sdlc.toml. Advise shows blockers; enforce checks head-bound review and approval transitions. See [the SDLC contract](sdlc.md) for the fixed stage order, required check names, claimed local receipts, console-only readbacks and pending custom/release/live parts. Owners/reviewers record bounded identities through hub_sdlc_record; these grant no additional authority.
+## Optional Qwen Code peer
+
+Select Qwen per project with `ahub roster add qwen`; it defaults off and is absent
+from default class preferences. `ahub qwen [--mode headless] [--model <alias>]`
+starts its ACP peer. `--print-command` previews; TUI is refused until #286's
+verification. `ahub stop qwen` stops the owned process group. A conductor may start
+it only through the selected roster and existing capabilities.
+
+The supported native ACP identity is qwen-code 0.25.0. A CLI version label alone
+is insufficient: startup verifies its native identity/version and advertised mode
+ids before any prompt. The observed local installation reports CLI 0.25.0 while
+its package/ACP source says 0.24.1; do not call that installation ready. Configure
+`qwen_cmd` only in untracked config.local.json with a verified 0.25.0 executable.
+The provider's tunnel/relay, if needed, must already be available. Startup cannot
+prove network readiness from a version command.
+
+Modes: ask maps to default, scoped frequency maps to auto-edit, never-ask maps to
+yolo. Qwen yolo approves every tool outside any hub sandbox; its own vendor bounds
+apply. Auto and plan are not hub mode mappings. Unknown quota refusals are not
+classified as authoritative quota; until a real pinned refusal is recorded, pause
+by hand. Occupancy is context with a source, never a consumption estimate. Roles
+do not establish that Qwen can reliably replace Kimi before the live leg.
+
+Qwen controlled recovery and automatic crash resume load the recorded conversation with ACP session/load. The emitted launcher passes --session-id; a controlled plan with a missing or unsafe identity refuses before effects. Preview redacts the id. A custom executable argv keeps its wrapper arguments before appended model flags. Native recovery remains unverified.
+
+## Optional Jcode peer
+
+Use ahub roster add jcode, then ahub jcode --mode headless [--model <alias>] [--provider-profile <name>]. The person launcher configures only agent-hub-jcode in .jcode/mcp.json; run ahub init afterwards to ignore the untracked machine-path file. Conductor/dashboard starts read that entry without editing it. Preview starts nothing, and ahub stop jcode stops only the owned private daemon/ACP groups. jcode_cmd, jcode_home and jcode_provider_profile are machine-local and never editable from settings.
+
+Native policy is unmanaged and has NO hub sandbox; no permission_modes.jcode or runtime mode mapping is invented. Quota and consumption remain unknown. Version 0.94.0 cannot prove native session/load identity, so attached Jcode blocks controlled recovery before effects and crash recovery asks for deliberate native reopening. A requested load without an echoed identity refuses; no fresh session is presented as restored. Provider/tool/native teardown receipts remain unverified in the pinned contract report.
+
+# Headless ACP watch (#286)
+
+- A person opens `ahub watch kimi` or `ahub watch qwen` in a second terminal. `--no-thoughts` hides thought items; `--color=auto|always|never` controls colour. `q` or Ctrl+C leaves the view, keeping the peer running. Answer approvals in `ahub console` or with `ahub permit`.
+- Watch replays bounded memory history from this daemon, then displays live updates. It is the hub's read-only view, with no prompt input. It does not read native session files.
+- Kimi's default is its own pull-only TUI (#316). Watch requires `ahub kimi --mode headless`; its own TUI remains visible in its native terminal. Qwen requires roster participation and verified ACP 0.25.0. `ahub qwen --mode tui` remains refused.
+- Protocol stays 16; a same-protocol older daemon answers the new request as unknown, which the CLI reports. No automatic pane opening is included in this slice.
+- Native T0 limits: [ACP watch verification](verification/2026-10-11-acp-watch-t0.md).
+
+# gsd-lite lifecycle guidance (#257)
+
+- Set `workflow = "gsd-lite"` in `.agenthub/sdlc.toml` for the next daemon start; default none preserves the existing flow. Mode advise displays checklist blockers without blocking, while enforce checks them at approval.
+- The task reviewer/person records phase criteria via `ahub sdlc record <id> '<receipt JSON>'`. Existing tasks and predecessor ids must match the board; import does not move owners or edit dependencies. Use the existing task propose `--after` command to create edges.
+- `ahub sdlc status <id>`, `explain <id>` and `export <id>` read the same current board/config projection. Export hashes are projection/config hashes, with no external text, extra authority or verification claim. Schema and example: [SDLC](sdlc.md#gsd-lite-checklist-guidance).
+
+# Catalog session guidance (#295)
+
+- Read available guidance with `ahub role list [--group dev|research]` and `ahub role show <id>`. Each definition identifies its layer and content hash. Doctor reports invalid files/selections without printing their contents.
+- Select up to two ids per peer in `catalog_roles` in the shared/local config, with at least one flow base already held by that peer. Empty local lists clear shared selections. This initial slice applies selections at a new daemon/MCP/adapter start; live assignment/settings and task roles follow separately.
+- Defaults preserve the existing flow. Catalog guidance adds no authority or routing preference. Native ingestion/retention and measured benefit remain unverified. Schema, bounds and source notice: [roles](roles.md).
+
+# Project profiles (#259)
+
+- Initialize new projects with `ahub init --profile research|writing|general`; default dev retains its existing templates and contracts. Profile aliases map to the existing base flow and are displayed beside it.
+- Non-dev plans declare paths, section anchors, source ids and claims. Configure completion checks explicitly in machine-local config; selecting a profile never starts a check or study. Schema, examples and pending converter/policy slices: [profiles](profiles.md).
+
+# Private and read-only data paths (#259)
+
+- Optional pii.paths forces matching declared refs/plans/section files to the on-prem flow before triage and memory, including when ordinary pattern routing is off. Optional data.readonly protects managed local/Pi writes and makes managed commands filesystem read-only.
+- Both lists are empty by default and apply at daemon start. Reads/stdout remain available; command-created files/caches are blocked in read-only mode. Exact path rules, alias handling and evidence: [data policy](data-policy.md).
+
+# Rich-document text projections (#259)
+
+- Configure text_projection only in an untracked machine-local file, with a separate {input} argv argument. Facts uses bounded read-only/no-network conversion and a content/config cache; failure keeps the prior file view and logs a bounded notice.
+- Raw change identity and projected presentation stay separate; private paths never enter conversion. Schema, limits and current surface scope: [text projections](text-projection.md).
+
+# Task catalog guidance (#295)
+
+- A proposal may name `role` from `ahub role list`. The allowed class list is checked in Tasks, and assignment/review notices carry bounded guidance. The role grants no authority and changes no routing decision. Scope and pending person-assignment surfaces: [roles](roles.md).
+
+# Person catalog-role assignment (#295)
+
+- Use `ahub role assign <peer> <id>` or `ahub role clear <peer> [<id>]`, or the dashboard Roles settings group. The selection is bounded to two compatible catalog ids, writes only machine-local settings and applies at the next peer start. Inherit and explicit no roles are distinct.
+- Change an open task's guidance with `ahub task role <id> <role|none>`. Agent shells and peer/tools control clients cannot use these mutation commands. Details and unconfirmed native consumption: [roles](roles.md).
+
+# Document projection review and undo
+
+- Machine-local text_projection also supplies bounded review and reverse undo previews from stored raw snapshots. Task-proposal baselines survive restart and reviewer changes; missing/private/pruned evidence is unavailable. See [text projections](text-projection.md) for caps and converter requirements.
+- Undo remains a raw-file operation: projected text cannot bypass later-edit, concurrency or unknown-turn refusals. Native model/account ingestion remains unverified.
+
+# Opt-in shadow repository
+
+- `ahub init --profile research|writing|general --shadow [--dry-run --json]` supplies hub-owned snapshot/facts/undo storage for a non-git folder. It creates no `.git` entry and never switches an existing Git project.
+- Maintain `.agenthub/ignore` for large/raw data. Snapshot and facts operations leave the shadow index/HEAD alone; raw undo refusal rules remain authoritative. Shadow metadata stays protected from managed worker writes. See [profiles](profiles.md).
+
+# Per-project profile data
+
+- Use `profile_overrides` for class aliases, supported plan selection, role guidance, catalog defaults, managed AGENTS content and advisory example checks. Shared/local maps merge by key; selections/text replace. See [profiles](profiles.md).
+- Refresh instructions with init and restart the daemon/MCP clients to apply their resolved contracts. Existing flow-role and executable-check authority remains in `roles`/trusted `checks`. Native model/account evidence remains unverified.
+
+
+## Staging work in Backlog (#263)
+
+Use `ahub task propose implement "Later work" --backlog --owner codex` to stage
+work without routing it. The owner is a reservation, including when an agent
+names itself. Normal proposal behavior is unchanged without `--backlog`.
+
+The person inspects `ahub board backlog` and `ahub task show <id>`, then runs
+`ahub backlog pull <id>` to put it in To Do. Dependencies still block assignment.
+Ready work uses the existing assignment and delivery-recovery contract; if no
+peer can take it, a later attachment or restart can offer it. Return ownerless
+To Do work with `ahub backlog return <id>`. Owned or started work cannot return.
+
+Ordinary agent task lists and conductor task reads exclude Backlog. Staged work
+is never claimed, accepted, completed, swept, escalated or relayed. PII cards and
+notices use the existing public stub. Planner grooming, five-column views, releases and dates are described below.
+The native planner/two-release smoke remains unverified; board release actions
+never tag or publish software.
+
+
+Pulling Backlog establishes its first execution-proposal boundary for projected
+review snapshots and research records. An initial Backlog row is not an offered
+proposal. Research uses the first pull time and preserves identity across later
+unstarted return/pull cycles; a new backlogged id after reset starts a new record
+generation. Partial work with acceptance/check/review evidence cannot return to
+Backlog even after decline or reassignment leaves it ownerless.
+
+
+## Dashboard project board (#263)
+
+The board displays Backlog, To Do, In Progress, Review / QA and Done from task
+states. To Do separates ready work from dependency, reservation, delivery-hold
+and unavailable-owner waits. Review and Done offer no flow dragging. Owner and
+reviewer names remain readable beside their filled/outlined color markers.
+Urgent tasks display P0 and a star; ordinary legacy tasks display P2.
+
+The legend reads the same live peer status as `ahub status`, with a derived
+owned-work count, active board ids and explicit permission display. Use the agent
+filter or By agent lanes to inspect work. Done shows recent rows first, with
+older rows expandable. At phone width columns stack and controls remain usable.
+
+Drag eligible work onto a peer to assign it, or use its labelled select and
+Assign button. Drag Backlog into To Do to pull it; return only ownerless To Do
+work to Backlog. Each move has a button/keyboard equivalent and reaches `Tasks`
+through the existing authenticated console/dashboard action path. Cards carry
+origin, project, instance and view-generation fences; stale or foreign drags
+are refused. Review/verdict/approval transitions stay with their flow actors.
+
+A hub advertises Backlog support explicitly. Older or unknown snapshots cannot
+silently turn Add to Backlog into an immediate offer. PII cards retain their
+public stub; legend entries contain ids/counts, never task prose. Planning priority/rank, releases, dates, planner grooming/undo and GitHub import
+are described below. Native planner-cycle evidence remains unverified.
+
+
+## Planning and phased releases (#263)
+
+Use `ahub backlog list` to read public staged work, then `ahub backlog plan <id>
+<revision> <fields-json> <reason>` to set rank, priority (0-3), release id, planned
+start/due UTC milliseconds or pin. `pin` accepts true/false; `undo` needs the
+current revision and latest eligible edit. The dashboard provides local-time
+date fields, task/release filters and lanes, and Reload current values when an
+edit is stale. A person's order, pins and frozen scopes protect planner changes.
+
+Create a phase with `ahub release new <name> <goal> <order>`, inspect `list` or
+`show`, and set planned start/cut/ship with `plan <name> <revision> <dates-json>`.
+`activate`, `freeze`, `ship` and `drop` need its current revision. Only a person
+freezes, ships, drops or edits frozen scope. Ship records the first ship time
+only after every member is approved or moved out; it runs no tag or publish.
+The dashboard shows phase progress, blocking dependencies, dates and remaining
+work. Actual task dates come from execution/review/approval history, never input.
+
+Configured planners read `hub_backlog_list` and `hub_release_list`, edit with
+`hub_backlog_plan`, and undo their own latest eligible change with
+`hub_backlog_undo`. Catalog guidance or a caller-supplied role grants no authority.
+PII cards stay stubs, reasons are screened/withheld in public history, and planning
+telemetry records ids/changed fields without prose. #247 task records carry
+optional release, priority, plannedStart and due, retaining unknown legacy data.
+
+Dependency/reservation planning, split/pull WIP limits, batched incoming notices
+and one-way GitHub import are described below. Source checks are recorded in the
+release verification report. Native planner work across two releases remains
+unverified; source and fixture checks do not establish installed live behavior.
+
+Office merge corrections retain the header's view selector when Off hides the
+scene. Activating a card reveals its task if a state filter excluded it; Work
+includes rework. Stable desk slots determine bounds after peers disconnect.
+Reduced motion removes departures immediately and the existing snapshot poll
+prunes transient deadlines without new timers. Explicit unattributed turns have
+no guessed task bubble. Warning caps retain conflicts first and parallel warning
+kinds have separate segments/labels. Physical visual validation remains pending.
+
+
+Planner backlog plans also accept `deps` (at most 64 unique task ids) and
+`reserved` (rostered peer id or null). Dependency/reservation edits require
+unstarted, unowned backlog work even for the person; cycles and missing ids
+are refused before persistence. Planning undo restores previous dependency and
+reservation values at the same revision fence. Editing never routes work.
+
+
+Release date editors invalidate stale revisions and offer Reload current release
+without overwriting unsaved dates. Project changes clear release creation drafts.
+Dashboard release actions use public numeric ids even when labels are withheld;
+`ahub release show <name>` looks up the stored identity on the console and returns
+the screened public projection. Exact-head source verification is recorded in the release report.
+
+
+## Planner WIP pull (#263)
+
+`hub_backlog_pull` takes id, current planning revision and a bounded reason. A
+configured planner with assignment capability reserves a ready To Do slot using
+current routing, roster, class, quota and health constraints. It refuses pins,
+unapproved dependencies, frozen scope and overriding person P0 order/reservations.
+The person uses `ahub backlog pull-ready <id> <revision> <reason>` or Pull within
+WIP on a card. Explicit manual pull/assignment retain their existing authority.
+
+Capacity defaults to one per peer. `ahub settings set tasks.wip_limits.codex 2`
+uses the existing machine-local registry path; integers 0..32 apply at hub start,
+with 0 disabling planner admission for that peer. Stored pending values and
+effective runtime limits remain distinct. Status and the agent legend count
+owned unfinished work plus unowned planner-pull reservations.
+
+Pending unowned, unstarted pull can be undone at its latest owned revision via
+`hub_backlog_undo` or the existing planning undo control, restoring its earlier
+reservation. An ordinary return to Backlog also restores the pre-pull reservation unless a later explicit reservation edit superseded it. Normal release routing offers work only while that reserved peer
+still has capacity; no other peer inherits its slot. Split and one-way import are described below. Native verification remains
+outstanding; exact-head source checks are recorded separately.
+
+
+Planned-date editors preserve loaded UTC milliseconds until their displayed
+value changes, including repeated local wall times during a clock change. Local
+inputs retain seconds/milliseconds and support HTML date years without truncating
+fields; see https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#local-dates-and-times.
+Date-editor source proof is recorded with the exact-head checks.
+
+
+## Backlog split (#263)
+
+Use `hub_backlog_split` with parent id/revision, reason and two to eight part
+objects, or `ahub backlog split <id> <revision> <parts-json> <reason>`. Each part
+has a title and optional detail/class/refs/plan; `after` names existing ids and
+`afterParts` names earlier zero-based parts. The selected task's dashboard Split
+form accepts one title per line and optional sequential dependencies.
+
+The original card remains integration/acceptance work and waits for every part.
+Children retain prerequisite, privacy and phase planning. A person's P0 order
+permits that goal's required predecessors, preventing dependency deadlock.
+Unused unchanged backlog children can be removed by latest split undo; later
+edits, execution, ownership or outside references refuse it. All writes roll
+back together and observers receive changes only after commit. Exact-head source checks are recorded separately; native verification remains
+unverified.
+
+
+The manager allows split screening, the bounded database wait and forwarding margin before declaring a missing reply unconfirmed. Reload the task before retrying an unconfirmed split. Stored role ids survive unavailable catalog guidance. Task memory-reference markers do not supersede assignment or check results, and dependency recovery ignores them.
+
+## One-way GitHub intake (#263)
+
+`ahub board import github --label <label> [--milestone <milestone>]
+[--repo <owner/repo>]` is person-only. Omitted repo is resolved by gh in the
+project directory. The command reads open issues with fixed bounded argv and
+stages up to 32 into unoffered Backlog, retaining canonical repo/issue identity
+across restarts. Repeating intake does not refresh or overwrite existing cards.
+
+The response lists confirmed imported/existing task ids and explicit partial,
+complete and unconfirmed state. A truncated page, time budget or interrupted
+staging is incomplete; repeat safely to reconcile the persisted identity.
+Public cards link to their source; PII cards expose no external identity.
+GitHub comments/labels/assignment/closure are never written. Exact-head source checks are recorded separately. Native verification remains
+unverified; no live account import was performed.
+
+
+`ahub board --columns` groups the same state-derived columns and ready/waiting
+reasons as the dashboard; `--release <name> | --release-id <id>` filters public rows on the hub.
+`--columns --json` returns filtered tasks and column metadata together. Ordinary
+peer reads retain the existing backlog prohibition. Phase views flag public ids
+approved after a known cut outside that release, and separately list unknown
+approval times without inventing dates. Exact-head source verification is recorded in the release report.
+## Global attention and prompt output (#280, phase 3)
+
+`ahub pet` reads the selected project's status file without a control token or
+network connection. It accepts only structural counts/state/first metadata from
+a confirmed daemon owner. Missing, malformed, legacy or unconfirmed data is
+reported as unavailable; it is not an empty live hub. `ahub pet --short` writes
+`ahub!N` when a known action count is positive, otherwise no bytes, including no
+newline. Explicit `pet` reads remain available when the presentation is off;
+normal `ahub status` appends the line only while the project's pet is enabled.
+
+An open recovery lock is read without coordinating the operation. Only the
+shared runner check's observed absence adds an action; unknown remains watch and
+is labelled unknown. A matching daemon recovery watch is replaced once, without
+double counting. A missing hub status is labelled unavailable even when a known
+recovery action can be shown. The output never resumes, aborts or disposes a run.
+
+Person-reviewed tasks contribute review actions; an offline peer holding
+unfinished work contributes one watch item with its lowest task id. The console
+receives those structural facts through its existing authenticated status reply.
+`n` selects an exact visible review task, or prints the task/review guidance if
+that row is unavailable. Offline guidance names status/task reads and an explicit
+assignment command. No command is executed by navigation. There is no extra
+console poll, timer or task-list request for stream mode.
+
+Intentionally person-owned work is not an offline agent. Neither user nor hub
+creates an offline watch item, while person-reviewed tasks remain actionable.
+Status reads only the board's structural id/state/owner/reviewer projection and
+reuses it for retained peer ids, avoiding task body/plan/history decoding.
+
+Planner reservations normalize the same lowercase peer syntax as owner arguments,
+reject reserved pseudo-peers and unknown unconfigured ids, and still enforce the
+roster. Returning unstarted ownerless work to Backlog joins the next planner
+notice batch without waiting for a restart.
+
+Queued planner batches retain bounded ids-only backlog references and recheck
+the board at actual delivery. A batch containing pulled/removed work is discarded
+before reaching the planner; its remaining backlog ids join the next batch. This
+floor also applies during the legacy stale-notice delivery experiment. No task
+text is copied and no routing/ownership state changes.
+
+## Console character choices (#280)
+
+`pet.character` selects stai (default), gyul, lantern, cursor-cat or boxbot.
+`pet.size` selects line (default), mini or full. Mini needs 100 columns; full also
+needs 40 rows, and smaller terminals fall back automatically. `P` cycles the
+built-ins and off for the current console only. `?` lists this under Pet, even
+while drawing is off. The command prompt keeps its original row and width.
+
+`pet.glyphs` selects auto/ascii/blocks; unsupported locales and dumb/linux
+terminals retain the ASCII floor. `pet.blink:false` is static. Neither choosing
+nor drawing a character changes authority, config files, task state or polling.
+Explicit `ahub pet` and text status use the configured line face; prompt tokens
+remain character-independent. Native glyph width and tmux are unverified.
+
+## Dashboard attention character (#280)
+
+The dashboard header draws the configured built-in character independently of
+Office. It uses the same structural needs model as status and the console. The
+accessible button names the character, state and action/watch counts; the tab
+title shows the action count. Activating the button scrolls and focuses the exact
+visible approval/task/peer row, or its related section with fixed id-only guidance
+when the row is filtered or unavailable. It performs no action and changes no
+filters. Legacy snapshots without attention keep the widget hidden.
+
+Only a live approval alternates the two waiting poses once per second through
+CSS. `pet.blink:false` and reduced motion retain a static pose. No new timer,
+request, image protocol or character-file load is added. Project reset clears
+the widget and title. Native/browser visual validation remains unverified.
+With mini/full characters, active console notices remain visible away from the
+character: panel body rows show the bounded wrapped notice, and stream mode
+prints each fresh notice once through the existing local stream. Footer prose
+exclusion and fixed prompt/footer geometry remain. No new request or timer.
+
+Automatic reroutes of planner-pulled work retain WIP and delivery-hold admission
+during offline, budget, roster and idle recovery. Explicit manual assignments
+retain their existing override authority.
+
+
+GitHub intake refuses comma-containing labels rather than allowing gh to split
+one literal label into several filters. WIP capacity excludes owner candidates
+only; eligible reviewers retain normal review routing. An auto-reassigning
+planner idle sweep waits without consuming its final step while no owner has
+capacity. Parent-only memory notes do not prevent unused child undo; child
+reference markers remain protected. Split-part plan schemas follow the selected
+project profile. Terminal tables preserve the visible read for stages and use
+a fresh peer status read on the same authenticated connection.
+
+Integer WIP editors retain a saved pending value, including zero and inheritance, before hub restart. GitHub intake accepts dot-prefixed repository names within the existing bounded owner/repository identity. Split undo also refuses children referenced by another task's persisted phase checklist.
+
+Declining rework returns changes_requested to To Do before rerouting. When a planner-pulled task has no eligible destination capacity, it remains ownerless in To Do and is retried after capacity clears, preserving the declined-owner exclusion.
+
+With no release cut, outside approved tasks are reported under unknown cut evidence, including tasks with a known approval time. A child task execution budget also prevents split undo until the person disables that budget.
+
+Split children retain their initial deterministic and inherited privacy signals across awaited screening. A routing-pattern reload cannot remove those captured signals from an unscreened child at final validation.
+
+If a routing pattern adds deterministic privacy during screening, split history and telemetry use regex-private provenance rather than an earlier clear model result. The same captured final signals determine both the child and its provenance.
+
+Dashboard backlog splits receive a dedicated outer HTTP request bound above manager forwarding, using the shared screening/database bounds and margin. Ordinary action policy remains unchanged. At phone widths, split form grids use one column so native date controls remain inside their panels.
+
+An acknowledged ACP permission-mode change awaits queued cancellation cleanup only when the cancelled prompt response has already been observed. A still-unreported cancelled prompt stays busy under its existing deadline, while mode acknowledgements remain available. A successful mode acknowledgement alone does not prove the peer is idle.
+
+Task idle sweeps ignore body-free memory-reference bookkeeping when finding the last real activity. Saving a task note or goal link does not postpone an idle notice or restart its escalation ladder.
+
+Split reasons preserve deterministic privacy from both initial and final policy checks, including parent privacy. Once withheld, a reason stays withheld in public history even if routing patterns are later removed.
+
+GitHub import rejects labels containing commas or double quotes before invoking gh, since its CSV-style label parser could otherwise select a different literal label.
+
+Ask evidence skips body-free memory-reference markers when selecting the latest task transition and note. The selected note retains the existing withheld and on-campus privacy checks.
+
+GitHub intake checks its staging deadline after every awaited proposal, including the final issue. A confirmed late save returns its task ID with partial=true and complete=false so the operator can read back and resume.
+
+If GitHub intake saves a row but later bookkeeping fails, canonical identity readback preserves the confirmed ID and queues its Backlog notice. The response remains partial; unreadable or missing readback remains unconfirmed.
+
+A later issue lookup or profile-preparation failure also returns the IDs confirmed earlier in the import as partial progress.
+
+Release cut audits return exact counts with at most 32 example IDs per category; the dashboard states how many IDs are shown when truncated. Scope grouping and indexed approval dates avoid scanning each task history for every release. Full audit pagination remains a future extension.
+
+Release cards include task states in their refresh key, so completion of an outside prerequisite updates blocked counts even when the release and audit preview are unchanged.