@staix/agent-hub 0.12.23 → 0.12.24

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.12.23 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
@@ -63,6 +63,25 @@ a three-line footer, separated by ASCII `-` rules; the stream has one rule above
 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
@@ -148,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
@@ -226,7 +299,7 @@ Launch that peer with `ahub claude` for channel pushes, or select `codex` in
 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 a peer in the start mode a person set for it (see
-"Start modes"): local, Kimi and a headless Pi or Codex start at once; for a
+"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
@@ -622,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),
@@ -915,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
@@ -996,6 +1093,75 @@ 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
@@ -1016,7 +1182,7 @@ ahub ui --settings                 # dashboard with a 15-minute settings session
 | --- | --- | --- | --- |
 | 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` (`tui` or `headless`) | `config.local.json` | that peer's next 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 |
@@ -1070,7 +1236,7 @@ A peer that has a TUI the hub attaches to starts in it by default (issue #269).
 | 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 | headless (ACP) | it has no TUI the hub attaches to |
+| 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.
@@ -1102,6 +1268,53 @@ A peer that has a TUI the hub attaches to starts in it by default (issue #269).
   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.
@@ -1354,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
@@ -1401,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.23), 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.23 ahub upgrade --to 0.12.23 --dry-run
-bunx --package @staix/agent-hub@0.12.23 ahub upgrade --to 0.12.23 --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.23 (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 |
 
@@ -1447,14 +1660,14 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.23 --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.23 --yes
+ahub upgrade --to 0.12.24 --yes
 ahub recovery status [<operation-id>]
 ahub recovery resume [<operation-id>]
 ahub recovery abort [<operation-id>]
@@ -2092,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.
 
@@ -2296,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.