@staix/agent-hub 0.12.31 → 0.12.32

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.12.31 and control protocol 16. Live verification
+This guide describes ahub 0.12.32 and control protocol 16. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Agent-operated live verification
@@ -120,7 +120,7 @@ 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
+The operational tabs change with digits 1 to 5 or 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 or
@@ -135,7 +135,7 @@ the stream; only the header is tab-flattened before tokenizing. Body lines retai
 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
+Peers, Approvals, Tasks, Queue and Settings 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
 meter keeps a fixed column at the right edge.
@@ -146,6 +146,7 @@ meter keeps a fixed column at the right edge.
 | Approvals | ID PEER LEFT TITLE |
 | Tasks | ID STATE OWNER REVIEWER CLASS AGE TITLE STAGE |
 | Queue | ID PEER STATE REV AGE |
+| Settings | GROUP KEY VALUE SOURCE APPLIES |
 
 The MODE column appears only when at least one peer has a non-`ask` mode.
 Zero counters and unknown values read `-`. Durations read `45s`, `12m`, `3h05m`
@@ -1436,6 +1437,16 @@ override them.
 
 ## Settings from the dashboard and the terminal
 
+In `ahub console`, press `6` for Settings. Existing operational-tab arrow cycling
+is unchanged; from Settings, Left returns to Events and Right to Peers. Select a
+row and press `e` to edit: value, daemon preview, nonempty reason, then `y`. Press
+`u` to preview and confirm undo. Undo binds the key and exact undo-record digest;
+if another write replaces that record, preview again. For busy roster removal,
+the panel names `ahub roster remove <peer> --now`, which explicitly stops an owned
+runtime or detaches a native session during its active turn; the panel does not force it.
+Esc cancels, and pasted confirmation text cannot
+write. This panel uses the current authenticated daemon connection.
+
 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:
 
@@ -1447,17 +1458,21 @@ 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 settings reload               # validate and apply the complete four-file candidate
 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 |
+| Permissions | `permission_modes.<peer>` (the default mode) | `config.local.json` | next peer 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 |
+| Start | `pi.auto_start` | `config.local.json` | next startup/recovery auto-start decision; never starts a peer merely on reload |
 | 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 |
+| Switches | `research.enabled`, `approvals.notify`, `snapshots.enabled` | `config.local.json` | live, without disturbing an active turn |
+| Switches | `coordination` | `config.local.json` | newly created tasks only |
+| Switches | `task_sweep.enabled`, `.auto_reassign`, `.interval_s`, `.unaccepted_min`, `.idle_min`, `.review_min`, `.ready_min`, `.ladder_min` | `config.local.json` | live; reschedules the sweep timer |
+| Routing | `tasks.wip_limits.<peer>` | `config.local.json` | live |
 | Roles | `planner` (the one peer that plans) | `config.local.json` | at once |
 
 - Writes go only to `.agenthub/config.local.json` and `.agenthub/routing.local.toml`,
@@ -1470,8 +1485,28 @@ ahub ui --settings                 # dashboard with a 15-minute settings session
   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`).
+- A row shows running and file values, source and apply class (`live`, `next use`,
+  or `restart`). Pending restart keys and reasons also appear in status, console
+  and dashboard, including startup-only blocks outside the editable registry.
+- Settings writes and undo, the dashboard Reload configuration button and
+  `ahub settings reload` use one complete validation/apply path. Debounced changes
+  of config.json, config.local.json, routing.toml and routing.local.toml use it too,
+  including atomic file replacement. Invalid candidates apply nothing and emit
+  one bounded error notice. Valid but unauthorized keys retain their accepted value and are reported per key; other eligible changes still apply. Recovery/shutdown hold reloads.
+- Individual writes and undo publish only the named setting. Other file edits remain unapplied.
+- `ahub settings reload` lists guarded keys with complete before -> after values (including full argv) and any planner/conductor holder effect. It requires an interactive terminal and exact `y` within 30 seconds before adopting them. Oversized previews remain unapplied and must be split or reduced. Candidate bytes or accepted state changes invalidate that confirmation. Watchers and ordinary dashboard reloads never confirm a raise.
+- Privacy tightening (local PII constraints/screening, added PII patterns, nonholder role reductions and explicit capability-list narrowing) is automatic, including tracked files. A planner/conductor holder change is guarded even when a role list shrinks; deleting a restricted capability entry restores all capabilities and is guarded. Reload checks the actual files' Git provenance. Changed machine-local or raising
+  values from tracked/unverifiable files are refused; an ordinary dashboard or
+  watcher cannot adopt unrelated raising local edits. A settings session cannot
+  adopt routing fields outside its editable registry. Existing confirmation and
+  roster lifecycle fences remain; use the confirmed roster setting for membership.
+Pi relay model aliases (`pi.dgx_coding`, `pi.dgx_fast`) and `routing.pi` retain their running values until restart, because existing native sessions use the published relay catalogue and context contract. Routing policy changes apply to future decisions; local model/target changes apply at the next peer or sidecar creation.
+
+- Runtime/client ownership still requires restart for memory handles and sync,
+  gateway/MLX, runner/check commands, profile/tool contracts, converters, existing
+  session privacy/sandbox policies, the terminal provider and benchmark environment.
+  The exhaustive reasons are in the issue #439 spec amendment. A pending file value
+  is not applied to the running consumer. Coordination creation pins last for the daemon lifetime; a restart re-pins retained rows to its startup mode.
 - `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
@@ -1484,10 +1519,11 @@ ahub ui --settings                 # dashboard with a 15-minute settings session
   `.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.
+  reload refuses the guarded candidate and the Settings row identifies the file.
 - 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
+  `ask`, turns `pi.auto_start` off, sets a start mode back to `tui`, sets a WIP
+  limit to 0, turns `task_sweep.enabled` or `.auto_reassign` off and changes
+  the other Switches. 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
@@ -1913,21 +1949,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.31), 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.32), 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.31 ahub upgrade --to 0.12.31 --dry-run
-bunx --package @staix/agent-hub@0.12.31 ahub upgrade --to 0.12.31 --yes
+bunx --package @staix/agent-hub@0.12.32 ahub upgrade --to 0.12.32 --dry-run
+bunx --package @staix/agent-hub@0.12.32 ahub upgrade --to 0.12.32 --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.31 (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.32 (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 |
 
@@ -1959,17 +1995,18 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.31 --dry-run
+ahub upgrade --to 0.12.32 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.31 --yes
+ahub upgrade --to 0.12.32 --yes
 ahub recovery status [<operation-id>]
 ahub recovery resume [<operation-id>]
 ahub recovery abort [<operation-id>]
+ahub recovery reattach <operation-id> codex|claude|pi
 ahub recovery dispose [<operation-id>] --fresh-session <peer> --reason <text>
 ahub recovery dispose [<operation-id>] --stop-and-archive --reason <text>
 ```
@@ -2070,6 +2107,16 @@ through a pipe, the JSON plan, the `ahub: blocker:` lines and the exit codes are
 unchanged. The screens add no way to change an operation: every choice runs one
 of the commands in this section for you, so that command's refusals decide.
 
+The screens use the console palette and `--color=auto|always|never`, with the
+same `NO_COLOR` and `TERM=dumb` precedence. Auto colours a suitable TTY; explicit
+always has the console's override behaviour. Raw JSON bypasses colour and width
+handling. Default and never preserve the existing pipe, dry-run, status and
+dispose output byte for byte. Presentation flags go after the command, for
+example `ahub recovery --color=never` or
+`ahub recovery status <operation-id> --json`. An explicit `--json` returns only
+the raw document, without a human suffix. `upgrade --json` reviews a JSON plan;
+`--yes` is still needed to apply it without the interactive review.
+
 The plan screen lists each project with its hub version and, per attached peer,
 its state, how it runs (`TUI` in a terminal the plan bound to its session,
 `headless` as the hub's own process, `own` for a session the hub did not
@@ -2102,23 +2149,35 @@ plan shows the ended agents as offline.
 
 After apply the command stays attached and prints each step as the receipt
 records it, and while a source is being prepared, what it still waits for.
+Each reported step has a status mark and elapsed observation time. Resume lists
+only steps observed on that attempt and says `resuming from ...` once. Its stage
+step really runs again and is labelled `checking retained release`. Waits use
+the coordinator's actual recorded start and deadline, for example
+`[waiting] alpha: restoring Codex and Pi sessions (waiting 2m10s of 10m)`.
+Older receipts without timing metadata say `timing unknown`; updatedAt is never
+used as a substitute. Timing-only save failures log a warning and do not fail
+the operation. Stable waits print only on change and at most once per minute.
+Approval waits point to `ahub console`; native attachment waits point to the
+recorded launch and conversation. Korean text and
+long paths wrap to the measured width on plan, progress and menu screens.
 Enter opens the operation's screen while the runner works on. Ctrl+C leaves the
 command, at any prompt and while following, and never stops the runner: the
-`left:` line names the command that comes back to the screen, with the
-operation's own coordinator, because the installed `ahub` is the older release
-until the upgrade ends. A Ctrl+C between `a` and the start of the operation
+`left:` line names `ahub recovery status <operation-id>`. Use `--verbose` for
+the internal command with the operation's retained coordinator, because the
+installed `ahub` may still be the older release until the upgrade ends. A Ctrl+C between `a` and the start of the operation
 starts nothing. A prompt for a reason that is answered with
 Ctrl+C or the end of input ends nothing.
 
 The operation's screen also opens first whenever an operation holds the lock,
 and for bare `ahub recovery`. It shows the phase and step, each project's phase
-and effect receipts and the error, then the choices that `status` lists under
+and human outcome labels, then What happened / Why / What to do and the choices that `status` lists under
 `next` for the same receipt and live state:
 
 | Key | Runs | Offered when |
 | --- | --- | --- |
 | `r` | `recovery resume`, then follows | resume can get past what is live |
 | `c` | `recovery abort` | no runtime was stopped and no terminal effect or commit request is recorded |
+| `a` | `recovery reattach <id> <peer>` | the recorded detached session is eligible for reattachment |
 | `f` | `recovery dispose --fresh-session <peer>`, after a reason | a Codex or Claude restoration failed |
 | `e` | `recovery dispose --stop-and-archive`, after a confirmation and a reason | every unverified project reads as running, stopped or missing |
 | `x` | `e`, then the reset below | as `e` |
@@ -2128,6 +2187,26 @@ When more than one restoration failed, the second and later peers get
 `f-<peer>`. `s` refreshes the screen, `j` prints the receipt as JSON and `q`
 leaves the operation as it is.
 
+The marked recommendation is a read-only Enter default: refresh the plan, follow
+an active runner, read the receipt or refresh the operation. Apply, resume and
+reattach require their explicit keys; buffered Enter never starts them. Unknown failures recommend
+reading `j` before retrying effects. A wait whose runner cannot be verified is
+shown disabled with its reason, and cannot run a command. Stop, archive, reset
+and fresh-session choices carry a warning and name the consequence before the
+person confirms. Raw receipt keys and the original recorded error are available
+with `j` or `--verbose`. The four preservation failures name the actual failed
+queue, manual-pause, board or budget comparison; an older untyped cause remains
+unknown rather than being guessed from its text.
+
+Completion and stop-and-archive use a human summary on a TTY. It separates the
+outcome, recorded plugin/global installation effects, remaining work and the
+per-peer session commands. An optional fresh read-only inspection names the
+current hub version; a failed reading says `runtime unknown`, never a guessed
+version from the plan. The summary performs no lifecycle action. Use `j` or
+`--json` for the full receipt; JSON is intentionally exempt from human wrapping.
+For a long command, copy the exact single-line value from `j` or the status JSON;
+the width-wrapped human preview is for reading.
+
 While a runner is only waiting for its source to get quiet (step `prepare`, no
 effect recorded), `c` stops that runner and then aborts. It is offered only for
 a runner whose claim carries a process signature that still matches; a claim
@@ -2281,11 +2360,23 @@ next actions").
   unpinned signature too, so it counts as running when this command runs in
   the same time zone and locale as the launcher did. `resume` is refused while a stop-and-archive is partway. A lifecycle command refused by the lock names
   the operation's own `status` command, which lists what to do next.
+- `ahub recovery reattach <operation-id> codex|claude|pi` is person-only, including during live verification: an agent shell cannot delegate it. Name the operation and exactly one peer; session, backend, model and terminal overrides are not accepted. Use the exact operation-coordinator command printed by status or its blocked guidance. It repairs only that peer and leaves the operation blocked; run the offered `recovery resume` command to continue the remaining steps.
+  The CLI delegates only when the retained coordinator supports reattach. An existing older coordinator without that action uses this release's implementation instead; a missing receipt, retained coordinator path or coordinator file prints inspection/recovery guidance and starts no session.
+  A peer that attached and later went offline can be re-restored once when its saved terminal is positively orphaned or missing and no current or older operation launcher may still run. The recorded session id and Pi session file stay fixed; the new terminal binding is saved before waiting for authenticated attachment. A second detach blocks. An unreadable terminal, changed incarnation or worktree, disconnected-only evidence, truncated inventory or live/unknown launcher does not authorize another terminal.
+  Recovery status names the saved Codex thread, Pi session file and Claude session, the terminal evidence, and the applicable reattach command. A different attached conversation remains a strict refusal.
 - `ahub recovery dispose <operation-id> --fresh-session <peer> --reason <text>`
   applies to a Codex or Claude peer whose restoration failed (Pi is refused: a
   restored hub resumes Pi's recorded session). It records the lost session or
   thread id (status shows it under `lostContinuity`) and resumes: the peer
   starts without its old conversation, and the rest is verified as usual.
+  A session the operation already reattached keeps that repaired provenance
+  across target restarts and is never replaced automatically. Its
+  loss can be accepted only after the restoration reported the recorded Claude
+  transcript or Codex rollout as positively missing, naming the checked path;
+  dispose checks that path again before saving the choice and otherwise refuses
+  with "recorded conversation is not positively missing". Under `--live-test`
+  this repaired-session choice is refused even where an ordinary fresh session
+  may be delegated.
 - `ahub recovery dispose <operation-id> --stop-and-archive --reason <text>`
   abandons the operation. It checks every project first and refuses while a
   hub is unreachable, starting, stopping or of another control protocol; `next`
@@ -2332,7 +2423,8 @@ next actions").
   again.
   Start a project whose target ran with that release's CLI (`bunx --package
   @staix/agent-hub@<version> ahub up`), since it may have changed the task
-  database. The global CLI was not promoted.
+  database. The global CLI was not promoted. The archive summary distinguishes completed target startup and plugin installation from remaining global CLI installation, and prints recorded-session commands: `ahub codex resume <thread-id>`, `ahub pi --session-file <path>`, and the Claude reconnect command. On the next `ahub up`, `pi.auto_start` resumes the archived operation's recorded Pi session rather than choosing a fresh conversation. Unknown or conflicting archived identity refuses that automatic resume.
+  That session is kept as a bookmark, `.agenthub/state/recovery-continuity.json`. When its session file can no longer be resumed or does not match it, the hub archives the bookmark and starts no fresh session in that start; the error names `ahub pi --mode <mode> --session-file <managed-file>` for choosing one. An invalid or unreadable bookmark, or session storage that cannot be verified, starts nothing, keeps the bookmark and prints the `mv -n` command that archives it after inspection. The bookmark is retired once Pi attaches with a different authenticated session.
 - Both choices are for a person in a terminal; an agent shell is refused, and
   the reason is kept in the operation's audit. Run each with the command
   `next` or the error prints: the operation's own coordinator, or the release

package/docs/quickstart.md

@@ -17,7 +17,7 @@ ahub setup                                # installs the Claude Code channel plu
 Or use the matching GitHub release:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.12.31
+bun add -g github:STAIxBWLB/agent-hub#v0.12.32
 ahub setup
 ```
 
@@ -30,9 +30,11 @@ and upgrade or crash recovery, see the [operations guide](operations.md). To
 move running projects to a newer release later, run `ahub upgrade` in a
 terminal: it reviews the plan with you, applies it and follows it.
 
-## Upgrading to 0.12.31
+## Upgrading to 0.12.32
 
-Existing Jcode project MCP entries need one refresh before conductor or dashboard starts. Once per project, the person runs:
+The upgrade runs with the target release's own coordinator. If the operation blocks because a restored Codex, Claude or Pi terminal disappeared, the person runs `ahub recovery reattach <operation-id> codex|claude|pi` to relaunch that peer with its recorded session (one relaunch per receipt), then `ahub recovery resume` to finish.
+
+From 0.12.30 or earlier, existing Jcode project MCP entries need one refresh before conductor or dashboard starts. Once per project, the person runs:
 
 ```bash
 ahub jcode --mode headless
@@ -83,6 +85,7 @@ or set `OMNIROUTE_API_KEY`. Name the model in `.agenthub/routing.toml` (`[local]
 | `ahub board` | who has what; `ahub task show <id>` for one task |
 | `ahub task cancel <id> --reason <text>` | close obsolete work without approving it or stopping a native turn |
 | `ahub settings set planner <peer>` | pin the planner; status reports whether it came from settings, roles or the automatic choice |
+| `ahub settings reload` | apply edited config files without a restart; guarded values wait for your `y` in this terminal, and restart-only keys stay pending |
 | `ahub status` | peers, queues, pauses; `ahub budget` for quota windows |
 | `ahub memory profile-check` | a person's read-only check of running memory bindings in the current registry |
 | `ahub ask <question>` | what the board, shared memory and the log say, with the ids the answer rests on |
@@ -93,7 +96,7 @@ More: `ahub help`. How it is built and why: [`docs/specs/2026-09-19-agent-hub-de
 
 ## Shared memory
 
-The hub exact-pins the first-party `@staix/agent-mem` 0.3.0 core. Existing shared-v1 memory remains the default; upgrading does not migrate it. Managed agents use screened `hub_memory_search`, `hub_memory_show` and `hub_memory_graph` tools, or propose a correction with `hub_memory_correct`; only a person accepts candidates through the supported `amem review` path. Generation candidate acceptance is still refused.
+The hub exact-pins the first-party `@staix/agent-mem` 0.3.1 core. Existing shared-v1 memory remains the default; upgrading does not migrate it. Managed agents use screened `hub_memory_search`, `hub_memory_show` and `hub_memory_graph` tools, or propose a correction with `hub_memory_correct`; only a person accepts candidates through the supported `amem review` path. Generation candidate acceptance is still refused.
 
 Before any real generation migration, upgrade every hub sharing that memory home to 0.12.30 or later and check its authenticated binding with `ahub memory profile-check` in each custom registry. Ready bindings prove compatibility, not an atomic live cutover: quiesce consumers and close their handles before migrating, then reopen through the supported session-preserving lifecycle. Invalid or changed profiles disable native memory without falling back to legacy writes; the bus and board continue. See [memory operations](operations.md#hub-memory) for the remaining rollout gates.
 
@@ -110,8 +113,9 @@ contents: inspect them with `ahub tail`, then use `ahub permit <id> <option>` to
 allow. They can be denied on the page. PII task details remain available only via
 `ahub task show <id>` in the terminal. The page also starts a peer in its start
 mode (a TUI opens in a terminal when the hub has a terminal provider) and shows
-the settings; raising one needs `ahub ui --settings` or `ahub settings` in a
-terminal. See the operations guide, "Settings from the dashboard and the
+the settings with a Reload configuration button; raising one needs `ahub ui --settings`
+or `ahub settings` in a terminal, and guarded values from an edited file need
+`ahub settings reload` there. See the operations guide, "Settings from the dashboard and the
 terminal" and "Start modes".
 
 `ahub ui --no-open` prints a one-time link instead of launching a browser. Open it

package/docs/security.md

@@ -11,7 +11,7 @@ agent-hub connects agents that can each run commands. This page says what the hu
 - **Telemetry holds no bodies.** `.agenthub/state/events.jsonl` (issue #40) records envelope ids, routing and sizes, task ids and states, overlapping paths and token counts, and the task id (with a PII flag) that each usage and token record is attributed to. It never records a message body, a task title or detail, and marks private (PII) envelopes and tasks as such. It stays on the machine; `ahub export` only prints it. Two opt-in stores copy numbers from it into your home directory, shared by every project on the machine (directories mode 700, files 600): research records (issue #247, `research.enabled`) in `~/.agenthub/research/` hold per approved task the ids, states, counts, tokens, times and PII flag the events hold, a person's label from a closed list, and a hash in place of the project id; benchmark runs (issue #251) in `~/.agenthub/bench/` hold suite name and hash, arm label, the attached peers' ids, models and permission modes, task ids, outcomes, exit codes, counts, tokens and times, never suite text or a command's output.
 - **Snapshots stay in your repository.** Per-turn snapshots (issue #33) are git objects in the project's own object store, written through a temporary index; nothing is referenced, pushed or copied elsewhere, and `git gc` prunes them. They hold what the work tree held, including untracked files that are not ignored, so keep secrets in ignored files. They carry the repository's own permissions, and nothing caps their disk use but `git gc`. A turn of a peer holding an open PII task is not snapshotted; a PII file left in the project is snapshotted by later turns like any other file. `ahub undo` restores only files whose current content is exactly what the turn left.
 - **The edit hook reads, never decides.** `ahub check-path --hook` (issue #32) reads hub.db and returns context for Claude and a line for you; it sets no permission decision, so your permission rules stay in charge. It names other owners' task ids, titles and states, which then reach Claude's model; PII tasks are left out.
-- **The session record holds identities only.** `.agenthub/state/sessions.json` (issue #37, mode 600) keeps each attached peer's recovery metadata: launch options, session and thread ids, Pi's session file path. No message or task text; loss notices name deliveries by id, sender and public task title.
+- **The session record holds identities only.** `.agenthub/state/sessions.json` (issue #37, mode 600) keeps each attached peer's recovery metadata: launch options, session and thread ids, Pi's session file path. No message or task text; loss notices name deliveries by id, sender and public task title. The Pi continuity bookmark that recovery keeps across stop and archive (`.agenthub/state/recovery-continuity.json`, mode 600, at most 16 KiB) holds identities only too: operation and project ids, the project root, and Pi's session id, session file, backend and model name; a bookmark that is not a private regular file, is larger than that or names another project or operation reads as invalid, which is kept distinct from no bookmark.
 - **Context checkpoints have a separate text record.** Native occupancy readings carry numeric metadata only. An optional context checkpoint persists its summary in `.agenthub/state/context-checkpoint-<peer>.json` with mode 0600 and attempts shared-memory storage when enabled. Completion requires the outstanding request id, current peer/native session and transport generation; new connection claims invalidate old requests. Private turns, every open PII task associated with the peer as owner or reviewer (including pending review), and PII-pattern summaries are refused before persistence or cloud memory. Its text is never broadcast, and context pressure does not pause, reassign or replace the session.
 - **The local worker is boxed in.** Paths are resolved through symlinks and must stay inside the project; a secrets denylist (`.env*`, keys, credential files, the hub's own state and the state archives `ahub reset --all` leaves) applies to its file tools, its git arguments and its memory capture alike; `.git` and `.agenthub` are not writable. Writes, edits, shell commands and mutating git wait for approval unless the operator's permission mode grants them (writes and edits inside the grant filter in `ask-when-needed`, all four in `never-ask`; see below), and the approver sees what will be written or run, with control characters escaped. Everything it executes runs under the macOS sandbox, attended or not. Since 0.10 the profile starts from deny default (issue #39): commands run and read only the system, toolchain and project directories (and the project's git dir and the selected developer dir; with network on, the public CA bundles); no writes outside the project, its git dir and a temp dir of its own (`TMPDIR`, made for each command and removed when it ends; issue #63); no `.git` name at any depth, closing the creation, rename, symlink and gitfile routes to a planted repository, no `config` or `hooks` directly under one nor below the discovered modules root of the project's own `.git` (a submodule's git directory, nested submodules included; every term is anchored below that root, so a directory named `refs`, `config` or `hooks` above the project neither disables the rule nor trips it; a `/refs/` or `/logs/` segment below it keeps refs named `config` or `hooks` writable, and leaves a submodule whose own path contains such a segment uncovered; a submodule whose path has `hooks` as a whole component (`tools/hooks` included) fares worse: the rule matches its whole git directory, so every write there is refused; the discovered git directories, the modules root and every component in between are also refused as targets, closing the rename, replace and symlink routes to the same files), no `commondir` at any depth below one, with every such name matched folded against the code points HFS+ ignores (the fold covers the security-relevant names; on a volume that folds names, folded spellings of the components between `.git` and a submodule's git directory are not matched — the 1024-byte SBPL literal cannot hold a folded path — the same residual the external git dir rules carry since #270), and no `.agenthub` anywhere in the project (in an external git dir the `config`/`hooks` rules cover only its own children and the hooks directory's contents, so refs named `config` or `hooks` still work); a nested repository in bare layout stays open — the directory is the git dir, with no `.git` name to anchor a rule on, and the hub never runs git there, whatever the project root is: its calls are all `-C <project root>` or `--no-index` on temp files, and none descends into a nested directory's git layout, so a planted hook fires only if a person or another tool runs git in that directory themselves; the rules are probed on HFS+, which folds the 16 code points the patterns tolerate, and on a case-sensitive APFS image, which folds nothing (a folded spelling is an inert new file there and the real names stay refused); the cost is that `git init`, `git clone` and `git worktree add` do not run inside the sandbox (add, commit, stash, checkout and gc still do), `git submodule update --init` does not either (its git directory's `config` write is refused), and neither do `git worktree remove`, `git worktree prune` of a stale record, `git clean -ffd` in a project with a nested repository, or `rm -rf` of a directory that holds a `.git` (refusing the unlink is what stops the rename-out route); no network, loopback included, unless `local.bash_network`; with it, only through the hub's egress proxy to the hosts in `local.network_allow` (issue #65), which refuses names that resolve to internal addresses (behind NAT64 with the well-known prefix, by the IPv4 address the answer carries; a network-specific prefix is not recognised), so claude-mem and the Codex app-server stay out of reach (`"direct"` opens everything, until 0.13.0). One channel stays open: `trustd`, which TLS clients need, can fetch a certificate's AIA or OCSP URL on a command's behalf, outside the proxy. The allow-default profile of 0.9 and earlier was removed in 0.12.0 (issue #83); a `local.sandbox` setting is ignored with a note. The shared temp dirs (the user's and `/private/tmp`) are closed. Without the sandbox there is no `bash` tool.
 - **Capabilities are enforced, not suggested.** `capabilities` (issue #39) is checked by the daemon where task operations and messages arrive, so a peer cannot get round it by phrasing. A peer can never answer a permission request: the control link takes `permit` from the console role only, and a message that quotes a permit command is just text. Both bind the hub's own tool paths: a vendor agent with its own shell in the project (Codex, Claude, Kimi) can read `.agenthub/state/control-token` and connect as the console, which only the local worker's and Pi's sandbox prevents.
@@ -23,7 +23,7 @@ agent-hub connects agents that can each run commands. This page says what the hu
 
 ## Native memory authority and profile selection
 
-The portable core is the exact-pinned first-party `@staix/agent-mem` 0.3.0 package; it does not replace the hub's caller identity, PII policy or task-write authority. Deny, hardened git, real paths and process identity are single-sourced in its Node-safe platform entry. Current project privacy is applied by the hub before promotion and again before model-facing reads. Standalone person reads are unscreened, and the standalone `--policy-free` acknowledgement grants no hub or peer authority.
+The portable core is the exact-pinned first-party `@staix/agent-mem` 0.3.1 package; it does not replace the hub's caller identity, PII policy or task-write authority. Deny, hardened git, real paths and process identity are single-sourced in its Node-safe platform entry. Current project privacy is applied by the hub before promotion and again before model-facing reads. Standalone person reads are unscreened, and the standalone `--policy-free` acknowledgement grants no hub or peer authority.
 
 `hub_memory_search`, `hub_memory_show` and `hub_memory_graph` take the project from the daemon, require `memory_read`, refuse private turns and validate UTF-8 input before logs or storage work. Complete records and graph metadata are screened before counts and truncation. Search is at most 20 lines/4 KiB (default 8); show accepts at most 8 ids and returns at most 8 KiB; graph is at most 120 nodes/240 edges/6 KiB (default 60 nodes), with no edge lacking an endpoint. Unknown, ambiguous and withheld ids share one neutral refusal. Arguments and results are excluded from hub-managed capture; this does not govern a vendor's independent transcript or memory hooks.
 
@@ -98,8 +98,11 @@ if that audit cannot be written, the command refuses. The current daemon emits
 `agent_cli` with `delegated: true` and `refused: false`. Allowed-class commands retain the peer identity and capability checks, including
 messages, proposals and reviews. Peer starts, pause and resume may delegate
 operational console authority; task assign/escalate under the flag refuse. `--as-user`, person task labels,
-person-authored planning/release/memory/goal writes, SDLC record, benchmark run
-and the pet composer are refused. No argument text is copied into this audit.
+person-authored planning/release/memory/goal writes, SDLC record, benchmark run,
+`ahub recovery reattach`, a `--fresh-session` dispose that would replace a repaired
+session's conversation (or whose scope cannot be read), and the pet
+composer are refused; presentation flags such as `--color` or `--verbose` before
+the recovery action do not hide it from this check. No argument text is copied into this audit.
 Delegated dashboard restrictions are bound to its server-issued ticket/session:
 operational settings/start/stop controls remain, but message, proposal and
 workflow-history actions refuse even if the body tries to clear the restriction.
@@ -150,16 +153,17 @@ Please report vulnerabilities privately through GitHub's "Report a vulnerability
 - Every request must have the exact listener Host. Every data or action request, including the ticket exchange and snapshot polling, must be POST with the exact listener Origin and JSON content type. Foreign and missing origins, missing or expired sessions, oversized bodies and unknown actions are rejected. There is no CORS support. The only unauthenticated GET is the fixed, data-free HTML shell. No files or paths are served dynamically.
 - Responses are non-cacheable, cannot be framed, suppress referrers, and use a content security policy restricting scripts/styles to the shipped inline content and connections to this origin. Browser text is rendered with textContent, never interpreted as HTML.
 - The browser receives a bounded redacted event stream, peer states and queue counts, public task views, budget windows, pending approvals, the settings rows (closed values and ids, the file each comes from) and each startable peer's start plan (issue #269), benchmark run summaries (issue #251): the newest runs in `~/.agenthub/bench/`, whichever project on this machine ran them, by suite name, arm label, state, the task id in progress, counts, tokens and times, never suite text, and the office view's optional fields (issue #264): each peer's open turn (start time, attributed task id, attribution kind), a `checking` flag on tasks whose check is running, and warning `links` of overlapping, conflicting or cohort tasks (task and peer ids only, never paths, symbols or reasons; a PII task never joins a link, and a private or PII-attributed turn exposes no task id). Private envelope bodies and PII task text never cross this endpoint. Local-worker and Pi approval titles can contain PII, so their details remain terminal-only; the dashboard identifies the request and directs the operator to `ahub tail` before allowing it. Budget checkpoint summaries are also omitted.
-- The closed action list includes permission response, peer pause/resume, console message, task proposal/assignment and the settings actions below (set, undo, preview). Project-board actions add revision-fenced planning, Backlog pull/return/split/undo and release planning/state changes through Tasks; they do not tag, publish or write GitHub state. These use the existing daemon/task paths and budget pause rules. `start_peer` (issue #269) starts a peer from a closed list in the mode a person set, with a command the hub assembles: the request carries a peer id and nothing else. There is no generic control proxy, task-detail read, shell, file access, free-form configuration edit, budget override, launch of a caller-chosen command or daemon shutdown API.
+- The closed action list includes permission response, peer pause/resume, console message, task proposal/assignment and the settings actions below (set, undo, preview, reload). Project-board actions add revision-fenced planning, Backlog pull/return/split/undo and release planning/state changes through Tasks; they do not tag, publish or write GitHub state. These use the existing daemon/task paths and budget pause rules. `start_peer` (issue #269) starts a peer from a closed list in the mode a person set, with a command the hub assembles: the request carries a peer id and nothing else. There is no generic control proxy, task-detail read, shell, file access, free-form configuration edit, budget override, launch of a caller-chosen command or daemon shutdown API.
 - The listener stops with the daemon. Expired sessions must be reopened with `ahub ui`; the page does not silently obtain new credentials.
 
 ## Dashboard settings and the settings session (issue #269)
 
 - Settings are a closed registry (`src/hub/settings.ts`). The dashboard and `ahub settings` can write only its keys, each checked against its own closed values, and only to `.agenthub/config.local.json` and `.agenthub/routing.local.toml`. A file git tracks is never written, so the shared `config.json` and `routing.toml` stay byte-identical; in a repository where git cannot answer, nothing is written either. Commands and binaries (`kimi_cmd`, `codex_bin`, `pi.cmd`, `checks`, `mlx`), credential files and gateway URLs (`omniroute`, `memory.worker_url`), the local worker's reach (`local.read_allow`, `local.bash_network`, `local.network_allow`), `bench.enabled` and `terminal` are refused by name from every surface: they choose what the hub runs or where secrets and task text go.
 - `routing.local.toml` holds `stay_switch` and, per class, `peers`, `escalate_to`, `route` (an id `routing.toml` defines) and `pi_backend`, and nothing else: targets, routes, signals and the PII constraint cannot be set through it. A write is read by the hub's own loader before it replaces the file (temp file and rename), and one previous version is kept for undo.
-- An ordinary dashboard session (`ahub ui`) reads settings, lowers a mode to `ask`, turns `pi.auto_start` off and changes the safe switches (`research.enabled`, `approvals.notify`, `snapshots.enabled`, `coordination`). Whatever can widen what agents do without asking needs a settings session: a non-ask mode now or at hub start, routing, starting Pi with the hub, removing a machine-local value, and undo. `ahub ui --settings` opens one: its ticket marks the session for 15 minutes, after which it is an ordinary session. `never-ask` also needs the peer's id typed as the confirmation, and a stored never-ask default still waits for the console's `y` at each hub start. An undo never puts never-ask back, and removing a machine-local value that uncovers a never-ask in the shared file needs the same confirmation. "Lowering to `ask`" means handing the decision back to the agent's own rules: for Codex that is the approval policy the person configured natively, which the hub does not judge.
+- An ordinary dashboard session (`ahub ui`) reads settings, lowers a mode to `ask`, turns `pi.auto_start`, `task_sweep.enabled` or `task_sweep.auto_reassign` off, sets a start mode back to `tui` or a WIP limit to 0, and changes the safe switches (`research.enabled`, `approvals.notify`, `snapshots.enabled`, `coordination`). Whatever can widen what agents do without asking needs a settings session: a non-ask mode now or at hub start, routing, starting Pi with the hub, removing a machine-local value, and undo. `ahub ui --settings` opens one: its ticket marks the session for 15 minutes, after which it is an ordinary session. `never-ask` also needs the peer's id typed as the confirmation, and a stored never-ask default still waits for the console's `y` at each hub start. An undo never puts never-ask back, and removing a machine-local value that uncovers a never-ask in the shared file needs the same confirmation. "Lowering to `ask`" means handing the decision back to the agent's own rules: for Codex that is the approval policy the person configured natively, which the hub does not judge.
 - A settings session is as strong as the console for these settings and no stronger elsewhere. A mode change is the console's own request with the same refusals; tool approvals stay deny-only for Pi and local; there is still no shell, file, task-detail or launch-command API. `ahub ui --settings` and `ahub settings` pass the same identity gate as `ahub permission`, which is an operating policy, not authentication. The hostile-agent boundary above applies unchanged: an agent with an unrestricted shell as the same user can impersonate the console, and so can open a settings session.
 - Every change writes a `settings` event (the key, the value before and after, the source `dashboard` or `terminal`) and a line in `hub.log` and open consoles; opening a settings session is logged too. The unified dashboard (`ahub ui --all`) forwards settings actions as an ordinary session and opens no settings session.
+- Configuration reload (issue #439). The daemon watches `config.json`, `config.local.json`, `routing.toml` and `routing.local.toml` and re-reads the complete candidate after a change, as the dashboard's Reload configuration and `ahub settings reload` do; an invalid candidate applies nothing. Each changed key is then authorized on its own against its file's actual git provenance. A privacy tightening (local-only PII, the model screen on, added PII patterns, narrower roles or capability lists, unless it moves the planner or conductor) and a safe registered setting apply from any file. Every other change, machine-local fields included, keeps its running value when its file is tracked or git cannot answer. From an untracked file such a guarded change is adopted only by `ahub settings reload` in an interactive terminal, after it lists each guarded key with its full before and after values and the person types `y` within 30 seconds; the confirmation is bound to the file contents and accepted state it was shown for. File watches and dashboard reloads, a settings session's included, never confirm, and no reload changes the roster: membership moves only through the roster setting. Keys whose consumers are bound at start (memory, the gateway and MLX, checks, the privacy and sandbox policy of existing sessions, the terminal provider and others) stay pending until a restart.
 - Start modes. A start the hub makes itself (the dashboard's Start control, `peer_start` from a console child, the conductor's `hub_peer_start`, `pi.auto_start`) takes the peer's start mode. Through settings only a settings session or the terminal can set it to headless; a config file can also set `peers.<id>.start_mode`, the shared one included (it is not a machine-local field: headless was the only form for Pi, Kimi and the local worker before this change, a hub-made headless Codex start is the app-server the hub already ran for it, and a start mode grants nothing a permission mode or a capability controls). For a TUI the hub opens a terminal running `<runtime> <its own entry point> --project <this project> <peer>` (and `--mode tui` for Pi): every word is the hub's own, the command line is those words each quoted for a POSIX shell, and no request field, tool argument or agent message is part of it. In a `terminal.open` template `{command}` is that quoted line and `{title}` and `{cwd}` are raw text for argv elements of their own; each placeholder is substituted once, so a project path that itself contains a placeholder, a quote or `$` stays one word. A provider's own error text goes to `hub.log`, not to the caller. The terminal comes from `terminal.open`, a machine-local command template that config trust refuses from a committed file and that no settings surface can write, or from Orca. The opened terminal's environment carries no agent marker, so `ahub` there has the console's identity. Without a provider the start is refused with the command to run by hand; it is never downgraded to headless. A conductor can start a peer but cannot choose its mode.
 
 ## Multi-project manager (protocol 7)
@@ -192,7 +196,7 @@ conductor holder is refused. Local and Pi scoped tools cannot write `.agenthub`.
 Claude, Codex and Kimi still follow their own file permissions and can edit a
 config file; such an edit changes participation only at the next hub start. A
 live settings write or undo applies its own roster key and does not adopt other
-file edits. External ids outside the known native catalog keep their prior
+file edits, and a configuration reload refuses roster changes. External ids outside the known native catalog keep their prior
 admission rules.
 
 Kimi's pull-only TUI owns its tool approvals and session. The person's launcher
@@ -215,7 +219,7 @@ are in [the configuration inventory](verification/2026-10-11-agent-config-invent
 Instruction files `AGENTS.md`, `CLAUDE.md` and `QWEN.md` remain grantable by default.
 A person can set `scoped_grants.protect_instructions` to true to require approval
 for scoped writes and edits through original or resolved spellings. It applies
-live after a settings write or undo, never changes reads or never-ask, and cannot
+live after a settings write, undo or reload (turning it off from an edited file needs the confirmed terminal reload), never changes reads or never-ask, and cannot
 be set through an agent, tools or conductor surface. Claude's daemon response
 withholds the scoped mode on these writes so an older hook grants nothing too.
 

package/docs/smoke.md

@@ -1901,3 +1901,37 @@ The current source fixture at 6d311a51dccd41d3703079175cac65a487189b15 used the
 This supersedes earlier phone-fixture pending statements only for this source. The old 1bbced04 captures remain historical; no later byte-identity premise is used. Native planner/two-release, accounts, model ingestion and measured effects remain unverified.
 
 The later bounded release-audit preview text is verified by DOM tests, not by a refreshed phone capture. The6d311a51 PNGs remain evidence for their pinned source; see the later-audit note in the phone verification report.
+
+
+## Settings reload and console fixture (#439, 2026-10-17)
+
+Native real-terminal smoke is **UNVERIFIED**. The admitted remote install/test
+attempt exited 75 before running because Python pid 6672 (parent 6671) had no
+verified repository owner. No retry, process kill, user-hub settings change,
+installation or restart was performed. A scripted ConsoleTerminal is fixture
+evidence, not a native PTY or account result.
+
+The implementation fixtures cover the following in disposable projects and temp
+memory homes:
+
+- Console Settings tab, daemon preview, bounded reason, explicit y, undo, stale
+  preview fencing and pasted-y refusal.
+- Dashboard reload/context, running/file values, pending restart reasons and
+  stable drafts; older snapshots remain readable.
+- Real fixture daemon: live switches/WIP and undo, retained pause/queue/instance,
+  actual sweep timer cancellation/rescheduling, atomic rename watcher, snapshot
+  capture on a later turn and pending memory restart without opening a consumer.
+- Whole-candidate JSON/TOML/unknown-key refusal, one error notice, per-key retention
+  of valid unauthorized edits, automatic privacy tightening, scoped write/undo,
+  fingerprint-bound guarded reload confirmation and agent-role request refusals.
+
+To complete the native leg, use a disposable project from a person terminal (or
+an explicitly authorized per-invocation delegation under docs/security.md).
+Open `ahub console`, select Settings with 6, edit a safe switch, inspect its
+preview, enter a reason, confirm y and verify running/file values. Preview and
+confirm undo; verify the restored value through `ahub settings get`. Paste y at
+confirmation and verify no write. Change a sweep interval and confirm the same
+hub instance stays running with its queue and pauses intact. Record the source
+head, terminal and daemon readbacks separately before claiming AC5 native smoke.
+
+For the guarded CLI leg, edit a disposable untracked WIP limit, run `ahub settings reload`, inspect its complete before -> after preview, decline and verify the running limit is retained. Repeat and confirm y, then verify the same instance and queue/pause state. Record this separately from the scripted CLI fixture; the token proves freshness within console authority, and the CLI supplies the person-presence checks.