@staix/agent-hub 0.34.1 → 0.35.0

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.34.0 and control protocols 16 through 17. Live verification
+This guide describes ahub 0.35.0 and control protocols 16 through 17. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Agent-operated live verification
@@ -1040,8 +1040,8 @@ plugin stale when the module changed after setup, so run `ahub setup` again afte
 
 ## Install and start
 
-Use Bun 1.4.2 or newer. Source checks and CI use the version pinned in
-`.bun-version` (currently 1.4.2). Install the released package and install its Claude
+Use Bun <!-- facts:bun-floor -->1.4.2<!-- /facts:bun-floor --> or newer. Source checks and CI use the version pinned in
+`.bun-version` (currently <!-- facts:bun-pinned -->1.4.2<!-- /facts:bun-pinned -->). Install the released package and install its Claude
 channel plugin:
 
 ```bash
@@ -1055,6 +1055,20 @@ ahub up
 `ahub init` writes the project configuration and managed instruction blocks.
 Run it after an upgrade when those blocks need refreshing.
 
+`ahub up` waits for authenticated readiness. After 12 seconds, a verified live
+child that is still pending produces a `still starting, pid N` message on stderr;
+the CLI keeps waiting and confirms the retained runtime when it becomes ready.
+At 120 seconds it reports unconfirmed readiness and exits unsuccessfully, leaving
+the daemon running. Run `ahub status` and inspect `hub.log` before another start.
+An owned child observed to exit before readiness produces an error; a cancelled
+operation cannot confirm startup.
+
+Each completed daemon startup writes one `startup timings ms:` line to `hub.log`,
+with fixed phase names and durations. The three event-seed consumers share one
+lossless streaming pass; abandoned snapshot bodies are not read for startup.
+The [startup receipt](verification/2026-11-07-daemon-startup-1232.md) separates
+seed I/O from bounded usage-rollup I/O and records the isolated measurements.
+
 Settings flags (#1100) set the main project settings without a file edit.
 `--agents <a,b,...|none>` (`start.agents`) and `--autonomy inherit|off` (whether a
 new project inherits the machine autonomy preset) go to the untracked
@@ -1655,6 +1669,7 @@ token counts, never message bodies or task titles.
 ahub report --since 7d          # turns, busy time and tokens per peer, messages, overlaps, task events
 ahub report --since 7d --json   # the same numbers as JSON
 ahub report --by task           # tokens, turns and wall time per task and class, with the unattributed share
+                                # and, from #1278, what the person was asked per task (permissions, questions, completions, CLI refusals, minutes from recorded latencies only), with the unattributed remainder apart
 ahub export --since 24h         # the raw events as JSON lines, for your own analysis
 ahub report --dogfood [--since 7d|<iso>] [--json]   # read-only scorecard: flow, quality, cost, delivery, performance, adoption
 ```
@@ -1716,13 +1731,15 @@ redistributed (rules: [events](events.md#per-task-usage-reports)).
 ## Research records
 
 With `"research": { "enabled": true }` in `.agenthub/config.json` (off by default), the hub keeps one record per
-approved task in `~/.agenthub/research/`, shared by every project that opts in: outcome, review rounds, rework, failed
-checks, tokens and time per peer and model, never task or message text ([schema](research.md)).
+task that reaches a terminal state (approved or cancelled) in `~/.agenthub/research/`, shared by every project that opts in:
+outcome, review rounds and findings, delivery and merge figures, rework, failed checks, tokens and time per peer and model,
+never task or message text ([schema](research.md)). Unknown values are null and counted, never zero.
 
 ```bash
 ahub research --since 30d          # success, first-pass, rework and check-failure rates; tokens and wall time per task
 ahub research --all --json         # every opted-in project on this machine
 ahub research export --format csv  # the records, for your own analysis
+ahub research export --dataset ~/research-out [--all]  # per-project tasks.jsonl, manifest.json, quality.json: family names only, to a directory in your home outside every project
 ahub research backfill             # build this project's records once from events.jsonl
 ahub task label 12 reverted        # a later verdict (ok, regressed, reverted, incomplete, wrong, abandoned)
 ```
@@ -1824,7 +1841,7 @@ ahub memory forget 1a2b3c4d              # a person's; also promote, demote, sup
 
 `"memory": { "native": false }` in `.agenthub/config.json` turns it off for a project.
 
-The exact-pinned `@staix/agent-mem` 0.22.1 resolves `AMEM_HOME`, then `$AGENTHUB_HOME/memory`, then `~/.agenthub/memory`. An absent `M/profile.json` selects shared v1; an explicit generation selects `M/generations/G` with the package's readonly legacy bridge. All daemon memory consumers and the hub memory/goal CLI use that selected profile. Invalid metadata or a missing selected generation makes native memory unavailable while the bus and board continue; there is no fallback to legacy writes. Inspect the daemon's memory binding/availability before interpreting missing memory as an empty store.
+The exact-pinned `@staix/agent-mem` 0.23.1 resolves `AMEM_HOME`, then `$AGENTHUB_HOME/memory`, then `~/.agenthub/memory`. An absent `M/profile.json` selects shared v1; an explicit generation selects `M/generations/G` with the package's readonly legacy bridge. All daemon memory consumers and the hub memory/goal CLI use that selected profile. Invalid metadata or a missing selected generation makes native memory unavailable while the bus and board continue; there is no fallback to legacy writes. Inspect the daemon's memory binding/availability before interpreting missing memory as an empty store.
 
 The daemon checks its selector at hub operation entry and before candidate/counter writes. It does not hot-switch handles or provide an atomic fence against selection changes during an in-flight core call. Quiesce consumers and close their handles before migration or selection changes; reopen through the supported session-preserving lifecycle afterward. Candidate/counter storage remains `M/candidates.db`, independent of `G`; since agent-mem 0.7.0 `amem review` also lists and accepts candidates on a selected generation. Every running hub using this home needs an authenticated receipt: a matching ready binding, or a generation-capable unbound receipt (`disabled` when native memory is off, `unavailable` when opening failed) proving it holds no memory handle. An unbound daemon and zero running hubs are quiesced for memory; a stale bound handle, unreadable registry or unknown runtime is not ready. Existing JSON memory/goal results remain unchanged; the additive binding receipt belongs to daemon status, profile-check and the decay object. This source integration does not authorize installing a new runtime, migrating real memory, restarting sessions or claiming real-machine sync/capture receipts. Migration/deactivation and their limits belong to [agent-mem](https://github.com/STAIxBWLB/agent-mem); see [the hub profile contract](memory.md#selected-memory-profile).
 
@@ -2442,6 +2459,73 @@ 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.
 
+## Live peer model overrides (#1317)
+
+From a plain person terminal, select the next model of a supported peer without
+restarting the peer or reloading project configuration:
+
+```bash
+ahub model set claude-impl claude-sonnet-5-5
+ahub model set codex gpt-5.1-codex
+ahub model clear claude-impl
+ahub model list
+ahub model list --json
+```
+
+Use a model id available through the peer's existing provider.
+Model ids are one bounded token: letters, digits and `._:/@+-`, at most 128 bytes,
+no spaces and no leading dash. Agent shells and every hub-tool caller are
+refused, including list; a conductor role does not grant person authority.
+The dashboard Peers action uses a person settings session and preview/confirm,
+not an agent command or an ordinary dashboard permission escalation.
+
+An override is desired runtime state in `hub.db`. It survives daemon restart;
+`ahub reset` clears it with runtime state. Precedence is override, instance
+model, launch model, then native default where that surface supports them.
+Clear restores the existing lower-priority selection. For Codex app-server,
+an explicit client model always wins over hub injection. A `turn/start` model
+becomes the native thread default, so clear may retain that current default;
+it does not recover an earlier model. Raw/pull-only native TUI attachments remain
+unsupported. A retained former override is labelled `native thread default (was override)`;
+a rejected start leaves the next start free to sample a corrected selection.
+The model and its source appear in `ahub status` and JSON output. An unknown native default remains
+unknown. `pending next turn` means the desired value has not been acknowledged
+at an eligible boundary; it does not claim the current turn changed models.
+
+Changing a desired value during a turn leaves that turn unchanged. Steering and
+local tool rounds keep the captured selection. If the person changes it twice
+before the next turn, only the last desired value is selected there. A stale
+callback cannot mark a newer desired value or another adapter owner applied.
+
+T1 supports headless Claude implementer turns, supported Codex app-server turns,
+fresh codex-review spawns, the local worker and Pi. Native account/provider
+availability is still the backend's responsibility. Headless Kimi Code CLI 2.5.2
+also supports next-turn selection through its receipt-backed ACP model setter.
+It requires the existing native identity admission, an exact-version receipt,
+an owned current session and advertised model choices. Clear restores the
+validated session baseline. Kimi reviewer isolation and version qualification
+are separate and unchanged.
+
+Jcode, Qwen, other Kimi versions and native TUI forms remain `unsupported live`.
+The [Jcode headless fixture](verification/2026-11-08-jcode-0991-model-setter-1317.md)
+passes, but does not fence a shared TUI turn across native failover. The
+[Qwen 0.26.9 setter fixture](verification/2026-11-08-qwen-0269-model-setter-1317.md)
+fails restoration of the original model. Neither enables a production setter.
+A refused set writes no new override and never restarts a process. Follow the
+reported cause and `ahub restart <peer>` guidance for unsupported forms.
+
+This does not make `instances.*.model` or `*_cmd` live or editable by agents.
+Their existing machine-local tier 3 confirmation and restart behavior remains.
+The plural `ahub models` still manages the existing local model service; it is
+separate from the singular per-peer `ahub model` command. `model_change` records
+ids and the next-turn boundary, never prompts or credentials.
+
+Model display is bounded to 512 local identities. If legacy sessions exceed the
+view budget, list refuses explicitly and status/dashboard mark model data
+unavailable; they never call a truncated list complete. Close unused native
+sessions, clear obsolete overrides and follow the restart guidance. Single-peer
+set/clear remains usable and no process is restarted automatically.
+
 ## Settings from the dashboard and the terminal
 
 In `ahub console`, press `6` for Settings. Existing operational-tab arrow cycling
@@ -2990,6 +3074,14 @@ 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`.
 
+On Kimi 2.5.2 (compat entry `kimi-tui`), the launcher also installs a launch-scoped
+plugin under `plugins/managed/agent-hub` in the Kimi home (`KIMI_CODE_HOME`, default
+`~/.kimi-code`) and removes it when the TUI exits (#1282). Its hooks let a turn you
+started there settle into a result (`ahub results`), always private, once the native
+transcript shows the turn ended and no native background task is running or unknown. This adds no push,
+steer, watchdog or quota handoff. Another Kimi version, or a plugin setup that
+fails, prints the cause and launches the plain TUI without completion receipts.
+
 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
@@ -3099,6 +3191,8 @@ Unread quota resume notices are coalesced without losing their public task moves
 
 A refused prompt with no acceptance or activity is requeued without a review hold. At the estimated reset it is tried again; another quota refusal pauses it again without consuming the poison-envelope retry count. Work that already started remains held for review even while its open tasks move to other peers. After the quota reset its queue stays held: inspect `ahub queue show <delivery-id>` and the associated task, then choose `ahub queue resolve <delivery-id> --action completed|retry|discard --reason "<text>"`. Do not retry work that another owner already took over without inspecting it. If the hub cannot confirm the pause, the refusal is also held instead of spending retries. Other errors keep their ordinary review behavior. Only the observed Kimi 5-hour text is recognised; weekly/monthly limits and other ACP vendors, including Qwen, remain unverified. The recognised text and its provenance live in `src/adapters/acp-quota.ts`.
 
+The gate is `budget.gate`, 0.99 by default (#1292; 0.9 before). A peer whose fresh quota window reaches the gate is asked to checkpoint, then paused and its work handed over. It resumes when every fresh window is under the gate minus 0.1, or at the reset. A release cut is also held while any window has no more headroom than 1 minus the gate. At 0.99 a soft pause leaves about 1% of the window for the checkpoint turn; a provider's hard refusal still pauses at once. `budget.gate` is a registered setting (a number from 0 to 1): set it with `ahub settings set budget.gate <value>` in a terminal or in an `ahub ui --settings` session. An ordinary dashboard session and the conductor cannot set it. The value goes to `config.local.json`; the running hub uses it from the next quota reading, with no restart. A project created before #1292 has `"gate": 0.9` in its tracked `.agenthub/config.json` (the init template wrote it), and that value overrides the default: remove the key there to follow the default, or set the machine-local value.
+
 Quota also shapes routing and handoffs:
 
 - Among peers a task could go to, those with quota readings are ordered by
@@ -3549,7 +3643,119 @@ The data-only [manifest](../scripts/compat-receipts/manifest.json) and [per-leg
 
 Optional model/TUI behavior explicitly left unverified by a model-free receipt is not a new admission leg. `codex-review` requires its separately authorized model-backed tool-call proof. `agy` has no public install source. `qwen-dual` requires real-model and TUI work and its current receipt does not name the OS. The manifest records acquisition metadata separately from historical native-binary evidence; no CLI installation or COMPAT change is made by this audit.
 
-For CI-opened PRs, the person still chooses between explicit `check.yml` dispatch with GITHUB_TOKEN and a GitHub App installation token. Dispatch avoids an additional App secret but needs Actions write permission in the publisher and exact-head evidence; it does not run the separate PR-only closing-refs/routing-receipt workflows. An App token lets normal PR events start checks, with person-owned scoped credentials confined to the publisher. Neither route is enabled here. Current [GitHub documentation](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow) also describes approval-required PR runs for GITHUB_TOKEN automation; that is not unattended CI. See the audit for permissions, queue and gate trade-offs.
+For CI-opened PRs, the person selected `GITHUB_TOKEN` with explicit `check.yml` dispatch on `compat/<id>-<version>` (2026-11-07). The publisher needs `actions: write` for dispatch in addition to its branch, PR and issue permissions. No GitHub App credentials are used. Dispatch supplies exact-head check evidence; it does not trigger the separate PR-only closing-refs/routing-receipt workflows. The T0 audit retains the alternative App-token trade-offs as history. Current [GitHub documentation](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow) also describes approval-required PR runs for GITHUB_TOKEN automation; that is not unattended CI. See the audit for permissions, queue and gate trade-offs.
+
+### Automated receipt workflow (#1248 T2)
+
+After merge, `agent-compat.yml` runs daily and can be dispatched with `dry: true`
+(the manual default). The watcher emits validated ahead/version and verified-ID
+JSON directly; matrix construction never parses report prose. At most eight IDs
+are considered, with two hosted jobs at once. An unspecified manifest OS stays
+not-run rather than receiving an invented native-platform proof.
+
+The candidate matrix has only `contents: read`, no supplied secrets, checkout
+credentials disabled and a 20-minute job bound. It runs the disposable harness and
+uploads JSON/Markdown even for failed or not-run legs. A separate trusted read-only
+job validates the summaries and builds the embedded COMPAT bundle from repository
+source. It never imports candidate JS or Markdown. The publisher downloads that
+job's immutable artifact ID and validates descriptors, byte hashes, identities,
+complete leg sets and trusted manifest policy again.
+
+The candidate CLI and receipt writer share a job and OS user. A malicious release
+could overwrite its own `summary.json` before upload with a well-formed eligible
+forgery; preparation cannot detect that forgery from the data alone. An eligible
+receipt is a compatibility signal, not a security attestation of the release.
+The person's PR and release review is the real admission gate; the automation
+never merges its verification PR.
+
+Only the publisher has contents/PR/issues write and Actions dispatch permission.
+It executes first-party Node code and `gh` REST calls, with no package install,
+build or candidate execution. All required legs must pass and trusted `autoAdmit`
+must allow the ID; artifact `eligible` alone is not evidence. It changes only the
+exact COMPAT row, its receipt and prepared plugin assets on `compat/<id>-<version>`.
+Existing bot branches are checked for manual drift; unknown collisions refuse,
+updates append without force, and verification PRs are never auto-merged. A newer
+same-ID PR supersedes an older one only after the replacement and its check
+dispatch succeed.
+
+Other results update closed-cause receipt blocks in the exact-title drift issue.
+Confirmed verified IDs remove their stale blocks, while still-drifting or unknown
+IDs retain their evidence. Report text never supplies those identities. Dry mode
+still performs isolated proof and read-only build/artifact work, then prints the
+planned GitHub changes without creating/updating branches, PRs, labels or issues.
+It is not native compatibility qualification on the person's Mac.
+
+See the [T2 verification report](verification/2026-11-07-compat-workflow-1248.md)
+for the data/credential boundary, fixtures and final committed-head evidence.
+
+### Isolated receipt harness (#1248 T1)
+
+Run `bun scripts/compat-receipt.ts <id> <exact-version> --out <new-owned-directory> --disposable-runner`
+from the checkout on a GitHub-hosted runner or disposable Linux container. The
+explicit flag is required; a local personal Mac is refused even with a temporary
+HOME. The runner VM/container must be destroyed after the job. The command writes `summary.json` and `receipt.md` without
+changing COMPAT, trust on this machine, or any workflow. Its exit codes are 0 for
+a completed pass, 1 for failure, 3 for required work left not-run, and 2 for invalid
+input/output. `eligible` also requires the manifest's admission policy; a pass
+alone never overrides the Codex/agy policy or a required model/TUI leg.
+
+The installer binds exact npm metadata and SRI before installing the verified
+local tarball into its private prefix, with empty user/global npm configs and a
+private cache. Release assets must match their tagged SHA-256 digest and checksum
+before bounded extraction; absolute/traversal/link/nonregular archive entries and
+size/count excesses refuse. No global installer or caller credential environment
+is used. Normal npm lifecycle behavior is not silently disabled; this does not
+certify an unreviewed lifecycle proof. Isolation uses fresh HOME/XDG/tool homes and
+an allowlisted environment, not a claim of kernel confinement for every installer.
+
+Proof APIs load in a separate worker after that environment is established. The
+Codex backend's real production preparation is reused, including empty and
+ambient fixtures; its returned model `exec` command is never started. Kimi private
+configuration, exact host inventory and broker refusals are separate from native
+tool dispatch. Committed Claude transport/wrapper producers are imported through
+`runpy`, with optional exact-version/runtime-path inputs; their historical defaults
+and behavior assertions remain intact. No prepare evidence-description string is
+used as an execution-time proof.
+
+| Proof family | T1 can run | Explicit not-run work |
+| --- | --- | --- |
+| Codex reviewer | Committed production prepare, actual metadata/native-canary checks and launch configuration assertions | Model-backed hub call, separate control artifact and human source review |
+| Kimi reviewer | Committed prepare/inventory/broker plus promoted native two-tool loop, Write positive/negative controls, preload guard and producer group cleanup | Human source review; unsupported native platform |
+| Claude implementer | Committed Write/Bash/rewrite and host-wrapper producer groups | Human upstream-impact review; unsupported launcher forms |
+| Pi | Artifact acquisition only in this core | Historical top-level producer needs import-safe/candidate-version extraction |
+| Qwen ACP | Promoted ACP identity/session/mapped-mode and actual published permission-handler producers, preload controls and group cleanup | Human lifecycle/source review; Linux does not replace required macOS arm64 |
+| Jcode | Reconstructed isolated serve/ACP/MCP, fixed-stream steering, telemetry and owned-group checks | Human source comparison; native macOS qualification remains unverified. The 0.99.1 Linux control is not qualified: telemetry identity and strict persisted-context binding fail; see the [reconstruction receipt](verification/2026-11-07-jcode-receipt-reconstruction-1248.md) |
+| agy and qwen-dual | Policy and unavailable/manual-leg reporting | No public agy installer; account/model/TUI or unspecified-platform legs |
+
+Every manifest leg appears as pass, fail or not-run with a cause and next step.
+Missing producers are not inferred from configuration or other host tests. Partial
+receipts cannot qualify a candidate while required work is missing. Source/lifecycle
+semantic review is not a fetched-diff pass. Synthetic loopback fixture sentinels are
+not real provider API keys; parent account/model variables never reach a worker.
+
+Default execution deadlines are 15 minutes overall, 3 minutes for installation
+and 2 minutes per proof-worker/group. Owned-process teardown has a separately
+bounded 10-second allowance, included in the JSON wall-time bounds. Output verification/publication has a
+separate 16-second allowance included in the total; elapsed time is sampled before
+publication. The summary
+separates `ownedStopConfirmed` from `processCleanup: proven|unproven` and gives its
+reason. An empty leader process group cannot prove lifetime cleanup: a helper can
+detach into a new group with ignored pipes and survive its launcher. Detected
+survivors and an unconfirmed owned stop fail the run. Producer cleanup legs assert
+that the native group they started stopped, using their original receipt evidence;
+they retain that pass or fail independently of harness lifetime cleanup. Native
+lifetime cleanup remains unproven in T1 and is reported without gating eligibility.
+A passing receipt with eligible policy and confirmed owned stop can be eligible
+while lifetime cleanup is unproven, provided no survivor was detected. The private
+workspace is kept until runner destruction; its location is reported only on stderr. A portable
+process supervisor belongs to a separate follow-up. Disposable runner lifetime is
+the containment boundary, not fresh HOME or process-group emptiness.
+
+The output directory is held open before installation. Exclusive, no-follow
+writes are relative to that handle, so replacing an ancestor cannot redirect the
+receipt. The receipt excludes raw native stdout/stderr and private prefix paths.
+No PR is created by T1. The [T1b producer report](verification/2026-11-07-compat-receipt-producers-1248.md) maps the promoted Kimi and Qwen modules to their original receipts. Publisher integration is T2. The [Jcode reconstruction](verification/2026-11-07-jcode-receipt-reconstruction-1248.md) retains its failed native control legs and unverified Mac qualification.
+
 
 ## Upgrade and crash recovery
 
@@ -3625,7 +3831,7 @@ or the plugin is older than the daemon it installed (#1179). It prints nothing w
 | Runtime | Control protocol window | Legacy status field |
 | --- | --- | --- |
 | 0.12.20 through 0.25.0 | 16 only | `protocol: 16` |
-| 0.26.0 through 0.34.0 | 16 through 17 | `protocol: 16`, `protocolMin: 16`, `protocolMax: 17` |
+| 0.26.0 through 0.35.0 | 16 through 17 | `protocol: 16`, `protocolMin: 16`, `protocolMax: 17` |
 
 New clients choose the highest common protocol. The protocol window remains 16
 through 17, so the published protocol-16 client and channel plugin remain usable; unrelated feature
@@ -3633,7 +3839,10 @@ capabilities still require their own labels. A disjoint window refuses with 4426
 The compatibility-floor `protocol` field remains readable by old clients.
 
 Release N-1 is counted in minor versions, separately from this protocol window
-(#1164, family contract entelecheia/ai-workspace#70). For 0.34.x, N-1 is 0.33.0,
+(#1164, family contract entelecheia/ai-workspace#70). For 0.35.x, N-1 is 0.34.1,
+the latest published patch of 0.34.x (exact `@staix/agent-mem` 0.22.1, control
+protocol 17 with descriptor floor 16). Every patch on 0.35.x keeps that release
+baseline. For 0.34.x, N-1 is 0.33.0,
 the latest published patch of 0.33.x (exact `@staix/agent-mem` 0.22.1, control
 protocol 17 with descriptor floor 16). Every patch on 0.34.x keeps that release
 baseline. For 0.33.x, N-1 is 0.32.0,
@@ -4395,6 +4604,97 @@ and doctor. Every route without the `hub/` prefix, including named legacy routes
 and `sy/` selections, uses the fixed alias with one warning. Loading or reloading
 never rewrites the operator's routing files.
 
+#### Optional adec decision route (#554)
+
+The optional `decision` route calls a separately managed, loopback-only
+`adec serve` using the [agent-decide route contract](https://github.com/STAIxBWLB/agent-decide/issues/4).
+The hub never starts or configures that service, reads its credentials, or calls
+its model directly. This backend is selected explicitly:
+
+```toml
+[hub_routes."hub/decision"]
+type = "decision"
+decision_backend = "adec"
+decision_mode = "shadow"
+policy_id = "ahub.chat"
+adec_endpoint = "http://127.0.0.1:8740/v1/route"
+decision_timeout_ms = 8000
+efficient = "fast"
+capable = "coding"
+candidates = [
+  { alias = "fast", efforts = ["low", "medium"] },
+  { alias = "coding", efforts = ["high"] },
+]
+```
+
+Select it by editing the existing `[local] route` or class `route` to
+`"hub/decision"`. Do not append a duplicate `[local]` table. Ordinary routes,
+class `fixed_model` selections and a person's explicit model override retain
+their existing behavior; an explicit model bypasses this route.
+
+Omitting `decision_mode` means `off`: no decision request or evidence is built.
+This delivery supports `shadow` only. It records the proposed alias/effort,
+margin, latency and decider while keeping the exact existing stage heuristic
+model, effort and conversation. `enforce` is explicitly refused at config load:
+`decision_mode enforce is not available yet; use shadow; tracked in #554`.
+There is no dormant application path or gateway effort plumbing. No route is
+enabled by default or deployed by this feature.
+
+The configured alias/effort list has at most 26 pairs. Aliases narrow the adec
+policy; efforts are an additional hub-side response allowlist and are not sent
+as a policy override. Align the lists with the service policy: an unconfigured
+effort is refused as `outside_options`, keeping the heuristic. The request
+cannot add a policy candidate. The service assembles its question and
+owns its hard rules, margin threshold, in-memory pins and fallback. A valid
+`fallbackApplied` pair is recorded as the service's proposed fallback even when
+`abstain` is true. Every proposal, failure and `no_candidate` keeps the hub
+heuristic unchanged. An HTTP 400 is a caller/configuration
+error; inspect the policy id and allowed pairs. Transport errors, timeout,
+malformed responses and an out-of-list pair also keep the hub heuristic, with a
+closed reason in the route event. A failed service is not asked again in the
+same user turn. Operational diagnostics contain a closed cause and repair step,
+and are emitted once per state/configuration change; a successful reply resets
+the diagnostic so a later recurrence is visible. Per-call route records remain
+available for outcome correlation. The default total timeout is 8 seconds (configurable from 1 to
+30000 ms), covering headers and the full bounded response. Redirects, ambient
+proxies, credentials and browser headers are not used. Endpoint URLs accept only
+HTTP numeric loopback with `/v1/route`, without userinfo, query or fragment.
+
+Each eligible tool round carries the same opaque, route/session/user-turn-bound
+`turnId`. adec therefore reuses its pin while rechecking current hard rules.
+The hub does not send a proposal as `current`: no pair is applied in shadow,
+and the native/default effort is unknown. Explicit model selections bypass the
+service.
+Changing a service, provider, model, version or policy threshold requires a new
+shadow period. The hub does not recalibrate a remote policy. The optional decider `version` is recorded when configured on the service;
+otherwise it stays unknown and is not inferred from the model id. Moving
+`latest` version aliases are refused.
+
+Evidence is a bounded data projection, never the forwarded conversation: a
+capped latest-user task fragment, the last assistant/tool tails, screened tool
+names and numeric stage dimensions. Whole selected sources pass the current
+public-view pattern/private-path/secret checks before UTF-8/JSON byte caps.
+Tool arguments, system/developer instructions and older history are not sent.
+The total evidence cap is 8 KiB; candidate and response payloads have finite
+bounds too. Evidence is labelled untrusted data, not instructions; injection
+resistance is not claimed. Review-observer-excluded and remote turns skip adec.
+A PII/private turn needs positive `onCampus()` before any evidence build or
+service call. Even on campus, its evidence is dimensions only, its context size
+is redacted to 0, and its separate `pii`/`private` flags reach adec so the service
+can enforce on-prem candidates/decider rules. The ordinary gateway campus and
+execution-budget checks still apply. Current board/turn privacy and observer
+facts are checked again across admission, campus and service awaits. A changed
+or unavailable authority refuses the stale turn instead of turning into a
+service-error fallback; inspect current task policy and retry. A returned proposal is checked again before telemetry. The original gateway
+execution path and its privacy/budget checks are unchanged. Source text, tool arguments, credentials
+and server error prose never enter route events.
+
+This delivery is the adec consumer slice of #554. The direct System One backend,
+enforcement application, optional stage classifier and manual offline triage
+evaluation remain separate unimplemented legs. Offline fake-service tests establish protocol and shadow
+behavior; no routing gain, native service/model run or production rollout is
+claimed.
+
 Migrate the retired settings as follows:
 
 | Retired setting or route | In-process replacement |
@@ -4574,18 +4874,18 @@ durable-delivery retries remain the journal's responsibility.
 
 ## Documentation source verification
 
-`docs/verified.json` maps README, the current security, operations and quickstart
-pages, and every agent note to a full source commit and explicit covered paths.
+`docs/verified.json` maps README, every page directly under `docs/` and
+`docs/addons/`, and every agent note to a full source commit and explicit covered paths.
 A stamp records a human check of the cited paths, symbols, numeric limits and
 operational commands. It does not certify live deployment or prove prose
 correctness automatically. Specs, changelogs and the smoke ledger retain their
-own dated evidence and are outside this manifest.
+own dated evidence and are outside this manifest; so does the retired GSD analysis.
 
 `node scripts/check-docs.mjs` also runs in `scripts/check.sh`. Missing manifest
 coverage, unresolved or nonancestor commits, removed source paths and a README
 status version different from `package.json` fail the gate. Source commits since
 a stamp and uncommitted covered changes produce sorted stale notices without
-failing it. Counts are commits touching any covered path, rather than file or
+failing it; CI's `decision` job repeats them as warnings on every pull request. Counts are commits touching any covered path, rather than file or
 line counts; an unrelated commit leaves the document fresh. Git history must
 include the stamped ancestors (CI checks out full history).
 
@@ -4653,10 +4953,11 @@ makes `scripts/check.sh` run slice `i` of the full suite through `bun test --sha
 every test file in exactly one shard and balances them by the recorded per-file times; shard 1 also runs the docs check, typecheck, role check, bundle freshness and
 package contents, so each of those runs once per gate, and the others install and test. Each shard runs under the same 1500 s backstop as Linux inside a 25-minute job
 limit, and its last line is `check: OK (shard i/n)`. The required check `check (macos-latest)` is an aggregator job that passes only when every shard passed (or an
-identical-tree full proof was reused), so branch protection and the reuse proof read the same names as before. `AHUB_CHECK_SHARD` is the full suite only: it cannot be
+identical-tree full proof was reused), so branch protection and the reuse proof read the same names as before. A stacked pull request (base not `main`) runs no macOS shard, and its `check (macos-latest)` fails with "macOS shards deferred", naming the base (#1307): GitHub allows 5 macOS jobs at once on this account, and such a PR is rebased and rerun once it targets `main`. A PR retargeted to `main` without a new commit gets its macOS run by a push, or by `gh pr close <n> && gh pr reopen <n>`; `gh run rerun` replays the old base and defers again. `AHUB_CHECK_SHARD` is the full suite only: it cannot be
 combined with `--changed`. A shard execs the system git once before its tests (`AHUB_CHECK_WARM_GIT`, default `/usr/bin/git`; a failure of it is ignored), because the first execs of `/usr/bin/git` on a fresh hosted macOS runner outlast the 1000 ms some tests give it. `scripts/test-timings.json` is advice for balance, never a list of tests: a file missing from it still runs (Bun gives it the median time).
 Regenerate it from a green macOS leg when the shards drift apart: `gh api --allow-escape-sequences repos/<owner>/<repo>/actions/jobs/<macOS shard job id>/logs`
-for each shard, or from one unsharded leg's log, then `bun scripts/make-test-timings.ts <log>`.
+for each shard, or from one unsharded leg's log, then `bun scripts/make-test-timings.ts <log>...`, or `bun scripts/refresh-test-timings.ts` for the newest green run (#1257).
+A red CI job gets one rerun of its failed jobs on the same head, then an investigation; the weekly flake ledger issue and the rerun policy are in `docs/agent-notes/tests.md` (#1257).
 The `closing-refs` workflow fails a PR whose title, body or commit messages would make
 GitHub close an issue the text only mentions (`Refs #N`, a negated or qualified keyword);
 an issue linked only in the sidebar passes (#760).
@@ -5001,11 +5302,11 @@ Native policy is unmanaged and has NO hub sandbox; no permission_modes.jcode or
 
 ## Optional Antigravity (agy) peer
 
-Antigravity is optional and off roster by default. Use `ahub roster add agy`, then run `ahub agy` in a terminal: it runs the Antigravity CLI as a fresh pull-only TUI in that terminal. It accepts the 1.4.x line: 1.4.2, 1.4.7 and 1.4.12 are the verified versions ([1.4.7 receipt](verification/2026-10-26-agy-1.4.7.md), [1.4.12 launcher nonce receipt](verification/2026-11-03-agy-1.4.12-launcher-nonce.md)), any other 1.4.x launches with a stderr warning (agy updates itself; set `AGY_CLI_DISABLE_AUTO_UPDATE=1` for a live run, #1140), and other versions are refused (#589) unless the person trusts that exact version with `ahub agents trust agy <version>` (#691). The running hub must advertise `native_hook_launch`; an older hub refuses before any write with an upgrade-or-restart remedy. Only the person's launcher starts it: conductor starts are refused, there is no controlled restore or resume, and a declared agy extra instance is refused when the config loads (#625). Headless/print, resume (`--conversation`, `--continue`, `--new`), `--mode`, `--dangerously-skip-permissions` and `--unattended` are refused until their native mapping is verified; `--print-command` previews without writing.
+Antigravity is optional and off roster by default. Use `ahub roster add agy`, then run `ahub agy` in a terminal: it runs the Antigravity CLI as a fresh pull-only TUI in that terminal. It accepts the 1.4.x line plus exact 1.5.3: 1.4.2, 1.4.7, 1.4.12 and 1.5.3 are the verified versions ([1.4.7 receipt](verification/2026-10-26-agy-1.4.7.md), [1.4.12 launcher nonce receipt](verification/2026-11-03-agy-1.4.12-launcher-nonce.md), [1.5.3 account-free receipt](verification/2026-11-08-agy-1.5.3.md)), any other 1.4.x launches with a stderr warning (agy updates itself, so the launcher sets `AGY_CLI_DISABLE_AUTO_UPDATE=1` for its version probe and the TUI it starts, #1140, #1286), and other versions are refused (#589) unless the person trusts that exact version with `ahub agents trust agy <version>` (#691). The running hub must advertise `native_hook_launch`; an older hub refuses before any write with an upgrade-or-restart remedy. Only the person's launcher starts it: conductor starts are refused, there is no controlled restore or resume, and a declared agy extra instance is refused when the config loads (#625). Headless/print, resume (`--conversation`, `--continue`, `--new`), `--mode`, `--dangerously-skip-permissions` and `--unattended` are refused until their native mapping is verified; `--print-command` previews without writing.
 
 The launcher writes exactly `plugin.json`, `mcp_config.json` and `hooks.json` in `.agents/plugins/agent-hub/`, refusing linked or foreign entries before any write, and removes only its own matching files when the TUI ends. It never writes project-level `.agents/hooks.json` or the person's `~/.gemini` settings. Run `ahub init` afterwards to ignore the untracked plugin directory; a tracked plugin is written with a warning. The native model sees the hub tools under the server name `agent-hub_agent-hub`.
 
-Like Kimi's TUI, agy is pull-only: it reads `hub_inbox` and shares results with `hub_send`, messages do not interrupt it, and automatic routing never picks it. Its roles are capped at implementer and verifier; a plan or review assignment and PII work are refused. Native permissions are unmanaged, with no hub sandbox, hub permission mode, quota source or session resume. Plugin hooks bound to that launch carry the hub's turn facts and report each completed native turn. A native read is recorded as a peer `Read` fact: `view_file` (`AbsolutePath`) in 1.4.2 and `read_file` (`Path`) in 1.4.3; a `StartLine`/`EndLine` range counts as a partial read, never a whole-file view (#555). The live TUI/account leg is unverified ([T0 receipt](verification/2026-10-19-agy-p1-t0.md)). The 1.4.3 T0 re-run keeps 1.4.3 unverified: its `call_mcp_tool` schema and native tool names changed, and the TUI attaches the hub tools only from the second model turn ([1.4.3 receipt](verification/2026-10-21-agy-1.4.3-t0.md), #607).
+Like Kimi's TUI, agy is pull-only: it reads `hub_inbox` and shares results with `hub_send`, messages do not interrupt it, and automatic routing never picks it. Its roles are capped at implementer and verifier; a plan or review assignment and PII work are refused. Native permissions are unmanaged, with no hub sandbox, hub permission mode, quota source or session resume. Plugin hooks bound to that launch carry the hub's turn facts and report each completed native turn. When messages wait at a model boundary (`SessionStart`, `PreInvocation`), the hook adds one count-only line asking it to call `hub_inbox`, never a body or sender (#1280). A native read is recorded as a peer `Read` fact: `view_file` (`AbsolutePath`) in 1.4.2 and `read_file` (`Path`) in 1.4.3; a `StartLine`/`EndLine` range counts as a partial read, never a whole-file view (#555). The live TUI/account leg is unverified ([T0 receipt](verification/2026-10-19-agy-p1-t0.md)). The 1.4.3 T0 re-run keeps 1.4.3 unverified: its `call_mcp_tool` schema and native tool names changed, and the TUI attaches the hub tools only from the second model turn ([1.4.3 receipt](verification/2026-10-21-agy-1.4.3-t0.md), #607).
 
 ## Configured ACP adapters (#451 A3)
 
@@ -5616,7 +5917,7 @@ A headless Claude implementer (#525-4) is declared separately:
 "claude-impl": { "kind": "claude", "roles": ["implementer"], "start_mode": "headless", "worktree": ".worktrees/claude-impl", "permission_mode": "ask" }
 ```
 
-A headless Claude implementer may name its model (#844): `"model": "claude-sonnet-5-5"` on its declaration passes `--model <value>` on every native turn, resumed ones included. It is one bounded word (letters, digits and `._:/@+-`, up to 128 bytes, no spaces and no leading dash) and is accepted only on a headless implementer, only from the untracked `config.local.json`. A tracked-file declaration is ignored with a reason, and the key is tier 3: the dashboard and a settings session cannot read or change it, only the console or your editor. Unset, the argv is unchanged and Claude uses its own default. `ahub status` shows the model on the instance row as `model source`. Declarations are captured once when the hub daemon starts, so a changed or newly added `model` takes effect after a hub daemon restart (`ahub restart`); restarting only the instance keeps the old model.
+A headless Claude implementer may name its model (#844): `"model": "claude-sonnet-5-5"` on its declaration passes `--model <value>` on every native turn, resumed ones included. It is one bounded word (letters, digits and `._:/@+-`, up to 128 bytes, no spaces and no leading dash) and is accepted only on a headless implementer, only from the untracked `config.local.json`. A tracked-file declaration is ignored with a reason, and the key is tier 3: the dashboard and a settings session cannot read or change it, only the console or your editor. Unset, the argv is unchanged and Claude uses its own default. `ahub status` shows the model on the instance row as `model source`. Declarations are captured once when the hub daemon starts, so a changed or newly added `model` takes effect after a hub daemon restart (`ahub restart`); restarting only the instance keeps the old model. For a person-owned next-turn override without changing that configuration path, use [live peer model overrides](#live-peer-model-overrides-1317).
 
 Create and register the attached-branch worktree first; the hub never creates it implicitly. `ahub claude --as claude-impl` asks the hub to start the instance and returns. Idle holds no native child. Task deliveries use a persisted UUID per task: first `--session-id`, later `--resume`. Unscoped chat reuses a session only when exactly one task is in progress for the instance; otherwise it is ephemeral. Positive missing-transcript evidence starts fresh with a notice; unknown read evidence retains the id. Reset includes the per-peer session map. A child inbox read refuses a queued batch attributed to another task and leaves it queued for that task's own session.
 
@@ -5770,7 +6071,7 @@ Native launcher connections retry transport timeouts/unclean closes with bounded
 
 ## amem runtime (agent-mem#13 P4)
 
-The hub exact-pins @staix/agent-mem 0.22.1 for recall, curated evidence and local deterministic capture. No runtime call reaches a claude-mem worker; `memory.worker_url` is ignored. The person's `ahub memory import claude-mem` remains explicit and off by default. Existing profile, alias, PII and private-turn fences still apply. `ask --remember` and context checkpoints propose machine-local candidates, never automatic curated evidence. See [memory integration](memory.md#in-process-recall-and-capture-agent-mem13-p4) for changed behavior and bounded-view ceilings.
+The hub exact-pins @staix/agent-mem <!-- facts:agent-mem-pin -->0.23.1<!-- /facts:agent-mem-pin --> for recall, curated evidence and local deterministic capture. No runtime call reaches a claude-mem worker; `memory.worker_url` is ignored. The person's `ahub memory import claude-mem` remains explicit and off by default. Existing profile, alias, PII and private-turn fences still apply. `ask --remember` and context checkpoints propose machine-local candidates, never automatic curated evidence. See [memory integration](memory.md#in-process-recall-and-capture-agent-mem13-p4) for changed behavior and bounded-view ceilings.
 
 ## Person-run backlog legs (#1176)
 
@@ -6344,7 +6645,7 @@ ahub worktrees tidy --confirm <fingerprint>    # the person's own terminal: re-r
 
 ## Results: what a run you started left behind (#1054)
 
-A run you started (a message you sent to a peer, from the console, `ahub say` or acon) settles into one **result** when the adapter's own signal says it ended and nothing else is pending: no queued continuation, open permission or question, owned child, running check or held delivery. Peers whose adapter declares no settle signal (Kimi in its own TUI, agy, person-typed Codex turns) leave none. Outcomes are `done`, `failed`, `limit` and `interrupted` (the hub restarted mid-run); an explicit stop by you and a budget pause leave no result. A result is **unread** until you mark it read; nothing a snapshot, `ahub status` or `ahub results` reads ever marks one.
+A run you started (a message you sent to a peer, from the console, `ahub say` or acon) settles into one **result** when the adapter's own signal says it ended and nothing else is pending: no queued continuation, open permission or question, owned child, running check or held delivery. Peers whose adapter declares no settle signal (agy, person-typed Codex turns) leave none; Kimi in its own TUI leaves one only when started with `ahub kimi` on the verified Kimi 2.5.2 (see [Kimi in its own TUI](#kimi-in-its-own-tui)). Outcomes are `done`, `failed`, `limit` and `interrupted` (the hub restarted mid-run); an explicit stop by you and a budget pause leave no result. A result is **unread** until you mark it read; nothing a snapshot, `ahub status` or `ahub results` reads ever marks one.
 
 - `ahub results [--unread]` lists them, newest first, unread ones marked `*`: id, `<peer>: <outcome word>` (a private result is `a private result`), when it settled and how long it ran. It prints no prompt and no reply.
 - `ahub results --read <id>` marks one read (it must exist and be unread). `--read-all` marks every unread result of the project. `--unread-last` lights the most recent read one again by deleting its receipt.
@@ -6405,13 +6706,13 @@ Corrupt or unreadable provenance stays unknown and held. The status next step di
 
 A ready memory profile does not prove a successful sync. Read the separate automatic-sync result and timestamp in `ahub status` or Memory. It resets to not run after daemon restart; it is not a machine-global record of manual CLI attempts. Missing remote configuration is the neutral `not-configured` state; an interrupted/stopped attempt is neutral `stopped`. Both keep their safe next step and produce no failure log under `quietSyncError`.
 
-For policy-declined rows, a person runs `ahub memory declined --json` to inspect IDs and safe rule categories, never note text. The pinned agent-mem 0.22.1 public `inspectSyncPolicy` API bounds physical outbound inspection for shared-v1 and generation profiles. A complete result supplies the declined IDs and rules; `complete:false` means the scan is unavailable, stale or over its diagnostic bound, not zero declined rows. The command stays read-only and rechecks its profile binding. No migration or policy edit is performed automatically.
+For policy-declined rows, a person runs `ahub memory declined --json` to inspect IDs and safe rule categories, never note text. The pinned agent-mem 0.23.1 public `inspectSyncPolicy` API bounds physical outbound inspection for shared-v1 and generation profiles. A complete result supplies the declined IDs and rules; `complete:false` means the scan is unavailable, stale or over its diagnostic bound, not zero declined rows. The command stays read-only and rechecks its profile binding. No migration or policy edit is performed automatically.
 
-The hub projects verified withheld/exported counts when a trusted SDK sync returns a successful placement result. That projection is covered by an injected-result fixture, not an activated-store sync. Agent-mem 0.22.1 requires a fresh `placementAttestation` even for an already active v3 store; the default hub supplies no such integration and therefore cannot perform that sync yet. Activation alone does not enable the hub's automatic sync, and no attestation is fabricated. A nonzero withheld count in a successful result is not a transport failure and does not mean those rows were deleted, rewritten or published. Inspect the IDs and rules before deliberately changing any source or approved policy; a forget operation does not remove its original text from physical history.
+The hub projects verified withheld/exported counts when a trusted SDK sync returns a successful placement result. That projection is covered by an injected-result fixture, not an activated-store sync. Agent-mem requires a fresh `placementAttestation` even for an already active v3 store; since 0.35.0 the daemon builds one with the package's own `createPlacementAttestation` on every sync pass and supplies no writer facts of its own, so no attestation is fabricated. A refused attestation is the closed cause `writer` in status, the dashboard and the log: its category, its cause class (`missing`, `changed`, `unavailable`) and the next step (repair the amem install and its host pin, then a person runs `amem migrate --sync-placement --dry-run`). Activation remains a person-run action. A nonzero withheld count in a successful result is not a transport failure and does not mean those rows were deleted, rewritten or published. Inspect the IDs and rules before deliberately changing any source or approved policy; a forget operation does not remove its original text from physical history.
 
-A legacy store without active per-row placement still blocks a sync containing declined rows. Status names inactive placement and the person-only `amem migrate --sync-placement --dry-run` preview, which requires every local writer installation through repeatable `--writer-root` flags. It also names the missing host `placementAttestation` and keeps `ahub memory declined` as the safe inspection step. The native CLI supports activation from 0.22.0; the pinned core is 0.22.1. See the [activation preview and prerequisites](memory.md#automatic-sync-health-1173) before any separately authorized apply. Preview writes nothing, and activation does not migrate layouts, change policy or automatically raise a format floor. The hub does not invoke it or fabricate its proof.
+A legacy store without active per-row placement still blocks a sync containing declined rows. Status names inactive placement and the person-only `amem migrate --sync-placement --dry-run` preview, which requires every local writer installation through repeatable `--writer-root` flags. It keeps `ahub memory declined` as the safe inspection step. The native CLI supports activation from 0.22.0; the pinned core is 0.23.1. See the [activation preview and prerequisites](memory.md#automatic-sync-health-1173) before any separately authorized apply. Preview writes nothing, and activation does not migrate layouts, change policy or automatically raise a format floor. The hub does not invoke it or fabricate its proof.
 
-The bounded diagnostic addresses #1173 AC4; AC5 has result projection only. The core activation command is available, while legitimate fresh host-attestation integration remains necessary for default-host v3 sync. #1173 remains open for that integration.
+The bounded diagnostic addresses #1173 AC4; AC5 has result projection and the host attestation. Whether an activated store syncs on a person's machine is not established by the isolated fixtures.
 
 For a transport or unknown failure, run `ahub memory sync` as a person to see the local diagnostic. Logs keep only the cause class and known declined count, once per unchanged failure episode. Complete declined-ID sets can distinguish a changed failure without placing IDs or bodies in the log; incomplete inspection keeps the set unknown. Existing write-time screening and profile/privacy fences remain. SDK adoption and isolated fixtures do not prove live rollout or a successful sync of the person's memory home.
 
@@ -6444,3 +6745,217 @@ Upgrade the broker, then every room member to a codec-capable release, then reco
 `ahub status` distinguishes local room storage opening from a failed broker
 connection; direct `ahub room status` failures expose only closed cause/action
 metadata. A healthy online link needs no broker repair advice.
+
+## Optional Orca companion contract (#1198 O0)
+
+The [versioned O0 contract](../integrations/orca/host-contract-v1.md) and its
+[capability matrix](../integrations/orca/host-contract-v1.json) describe the
+installed Orca 1.4.252 declarations, pinned primary references and reusable
+fake-host/CLI fixtures. O0 installs no plugin and changes no ahub runtime.
+Worker and frame APIs differ: workspace inventory/navigation are worker-only;
+focused context lacks the exact workspace id, execution host and real root
+needed to select a project. Names and branches are never selection authority.
+
+Terminal focus remains unsupported until a plugin terminal id can be bound to a
+current same-host CLI handle. Workspace navigation and manual `ahub console` /
+`ahub ui` commands remain available independently of a companion. No remote
+loopback URL is opened locally. Native local, remote, Windows and mobile results
+are recorded separately; declarations and fake results do not qualify them.
+The three baseline journeys count procedure actions only, with observed native
+counts still unknown. O1 must record actual open/disable/standalone UI proof.
+
+### Optional Orca companion: chooser and entry points (#1198 O1)
+
+[`integrations/orca/`](../integrations/orca/README.md) holds the optional companion: a manifest, a
+trusted worker and a sidebar panel. It is not in the npm package, no ahub source refers to it, and ahub and
+Orca keep all their own functionality without it. It lists Orca's workspaces, you select one by its exact
+id (a name or branch never selects), and it opens an existing screen: `ahub ui` run as a short-lived child
+with the folder as its working directory only, or a terminal created in the workspace running `ahub console`
+or `acon ui`. A selection binds the id, host id, kind and the folder's real path on this Mac and is
+re-checked against a complete inventory before every effect; a duplicate, missing, truncated or changed
+identity, or a host not declared to be this Mac, refuses visibly and runs nothing. It never passes `--json`
+to `ahub ui`, never approves, assigns, completes, retries, stops or upgrades anything, and keeps no CLI
+output, one-time link or task text in plugin state or logs.
+
+Install is explicit and in an isolated Orca profile first (`orca plugin validate`, `orca plugin dev load`
+with the fingerprint Orca prints); remove it with `orca plugin disable` and `orca plugin dev unload`. The
+fake-host checks are `test/orca-companion-entry.test.ts` and `test/orca-companion-independence.test.ts`.
+A **Show status** button (O2) reads the selected project's public status on a click only: version, tasks by
+state, and peer state with queue length, copied from `ahub status --json` through a closed allowlist so no
+free-text field (task title, a peer's current line, a notice, a path) is read. Offline, unavailable version,
+partial, stale and unknown stay distinct states; there is no poller, no transcript read and no terminal read.
+There is **no terminal focus**: O0 found no proof that a plugin terminal id names an `orca terminal switch`
+handle, so the companion never calls it and never replaces a terminal.
+
+**Platforms (O3).** [`support-matrix.json`](../integrations/orca/support-matrix.json) records one verdict per
+combination and a test enforces that `supported` needs a receipt that no longer says NOT RUN. Today none is
+supported: macOS local is fixture-only, and remote, Windows, browser or mobile and Linux are unsupported, each
+with a person-run receipt template under `integrations/orca/receipts/`. A remote workspace is refused before
+anything runs and shows the existing remote console command to run on that host; a remote loopback link is never
+opened locally. On Windows every workspace is refused (`unsupported_platform`). Where a client has no external
+navigation no link is held. Mobile availability is not inferred from SSH reachability or from Orca's mobile
+pairing option.
+
+**The native open and disable receipt is a person-run leg that has not been run**
+([`native-receipt.md`](../integrations/orca/native-receipt.md)): the action counts in the companion's README
+are procedure counts, remote, Windows and mobile stay unqualified (O3), and there is no focus-existing-console
+action.
+
+## Herdr companion host contract (#1199 H0)
+
+[`integrations/herdr/host-contract-v1.md`](../integrations/herdr/host-contract-v1.md) freezes what an optional Herdr mod may
+rely on, taken from the installed app's own declarations (Herdr 0.1.13, herdr-core 0.1.18, hashes recorded), and records
+what was not observed. It changes no ahub runtime and installs nothing. `exec` is bounded (30 s, 8 MiB) and used for
+reads only. The pane's machine and cwd are a navigation hint: the project root comes from `ahub projects --json` read on
+that same machine, and a remote cwd is never resolved on this Mac. Herdr has no install or disable command, so a mod is
+a folder the person adds and removes, and what removal does to a shown copy is for the H1 native receipt. Existing
+terminal focus is unbuilt until a Herdr terminal can be mapped to an ahub console. The three baseline journeys are
+procedure counts that have not been run in a native window.
+
+### Who owns a pull-only peer (#1310)
+
+`ahub status` (and `--json`) names the current owner of an attached channel peer, beside its standby rows: `<peer> owner: pid <n>; attached <age>; native session <id>`. The pid is what the owner's plugin reported at hello (`pid unknown` when it reported none or an unusable one). `attached` is when the attach finished, not when the hello arrived. The native session reads `unverified` until the hub has verified one through the native-facts path (today agy), and an id that is not a short plain token is never shown. The owner line is absent while a newer session is still arriving, while the peer is offline, and after a detach, so a claimant is never shown as attached, and a takeover replaces the whole line at once. Use it to see who holds a queued peer before running `ahub peer takeover`. It is display only: it never decides delivery, takeover or permission, and `status.json` on disk does not carry it.
+
+### Herdr project and machine entry (#1199 H1)
+
+[`integrations/herdr/`](../integrations/herdr/README.md) is an optional mod: three files the person copies to
+`mods/ahub` in the Herdr app home, which Herdr reads live and which declares `place: none`, so no layout changes.
+It lists the focused space's machine and folder and that machine's registered projects, and opens nothing until a
+row is selected. Open console starts one new tab in the selected space running `ahub --project <id> console`, with the project root
+as the tab's folder. Before every effect it re-reads the space, the machine and the registrations and runs
+`ahub status --json` from the project folder, and refuses a changed, duplicate, offline or unready target. The local
+dashboard runs the existing `ahub ui` and keeps no link or ticket. A remote space gets the console tab or a copyable
+command, never a dashboard link. Remove it by deleting the folder. It starts, stops and upgrades nothing and is not an
+ahub dependency. `herdr-app check` accepts it in a scratch home; the native open and disable receipt is a person-run
+leg that has not been run.
+
+### Herdr status card and existing-console focus (#1199 H2)
+
+The Herdr entry also offers three read-only actions. **Status** reads `ahub --project <id> status --json` from the project folder on the
+selected machine, on a click only, and shows task counts, peer states and queue lengths and the hub version from a closed
+allowlist, so no task or note text reaches it. Missing CLI, timeout, an exit error, no hub running, oversized or
+unrecognized output, an old hub, a partial reading and a stale one are distinct states. **Focus console** and **Peek
+console** (this computer only) accept a terminal only after `hc get` shows it live and running `ahub console` for the
+selected project, exactly one match, rechecked right before a single `pane.focus` or `terminal.peek`, and a focus is
+believed only after Herdr's `focused()` shows it. They never start, replace, type into or close a terminal, and
+Herdr's own working, blocked, done and idle words are shown, never sent to ahub. A console started through a wrapper is
+not recognized and the person uses Open console. The native focus receipt is a person-run leg that has not been run.
+
+### Herdr platform support matrix (#1199 H3)
+
+[`integrations/herdr/support-matrix.json`](../integrations/herdr/support-matrix.json) records one verdict per combination and a
+test enforces that `supported` needs a receipt that no longer says NOT RUN. Today none is supported: macOS local is
+fixture-only, and remote, Windows, Linux and browser or mobile are unsupported, each with a person-run receipt template under
+`integrations/herdr/receipts/`. The remote console workflow is designed (read on that machine, new tab in that machine's space,
+no dashboard link, no remote focus) and exercised against the fixture only, because no remote machine is configured on the
+machine it was built on. On Windows every action refuses. Mobile is not inferred from SSH reachability or a machine being ready.
+[`baseline-comparison.md`](../integrations/herdr/baseline-comparison.md) lays the entry's journeys beside the H0 baseline as
+procedure counts: the entry costs one more action than the baseline when the pane is already in the right project, and its value
+is the verified machine and root, not a shorter path.
+
+## Bounded visual attachments (#1058)
+
+`hub_visual` lets an ordinary local peer or the local worker annotate public work
+with a Mermaid diagram, comparison, table or before/after view. It is a separate
+tool, not extra fields in `hub_send`. Its input is `{payload, task?, to?}` and its
+receipt is `visual <id>`. `hub_visual_show {id}` explicitly reads a retained public
+record in this project. Read-only roles may read; publication still requires the
+ordinary shared-note capability and no-writes admission. Isolated fresh-reviewer
+MCP remains limited to `hub_review` and `hub_task_show`.
+
+The stored payload is the exact acon `VisualPayload` shape. acon owns `ui.visual`,
+its sandboxed Mermaid renderer, table kit and asset route; the hub imports types
+only. The standalone dashboard shows a readable title and text/source. Stream
+stubs and task details load a visual on demand. A missing/older acon visual kit
+keeps the fallback rather than loading another renderer into the hub.
+
+```json
+{"payload":{"kind":"mermaid","title":"Review flow","source":"flowchart TD\nPlan --> Implement --> Review"}}
+```
+
+The four kinds are `mermaid` (`source`, optional `title`), `comparison` (2-6
+`options`, optional `title`), `table` (`columns`, `rows`, optional `caption`) and
+`beforeAfter` (`before`, `after`, optional `caption`). Each comparison option has a
+title, optional summary, up to 10 pros and 10 cons, and optional `recommended`.
+Tables allow at most 500 rows and 12 columns. Column fields are `key`, `label`,
+optional `align: start|end` and `format: text|number|percent`; percent values use
+percent units as acon does. Cells are strings or finite numbers.
+
+Mermaid is self-contained source without a Markdown fence, at most 20 KiB UTF-8.
+The first non-comment line starts with a supported diagram keyword. This is only
+a header check, not parsing proof: acon shows source with a notice when its parser
+fails or the renderer times out. The hub adds no parser or Mermaid dependency.
+
+Hub admission also bounds the entire serialized payload to 1 MiB and each text
+field: title 300 bytes, caption 2000, alt 1000, text side 20 KiB, option summary
+4000, each pro/con 2000, table cell 4000, column key 128 and file path 4096. These
+are hub storage/admission ceilings, distinct from acon's payload type. Every text
+field and record key is screened before sanitization and again afterwards; an
+unsafe key is refused rather than renamed. Oversized or malformed data is refused
+with the field and repair step, never silently truncated or partially stored.
+
+A before/after side is either `{text}` or a project path with alt text:
+
+```json
+{"payload":{"kind":"beforeAfter","caption":"Layout change","before":{"path":"artifacts/before.png","alt":"Previous layout"},"after":{"path":"artifacts/after.png","alt":"Updated layout"}}}
+```
+
+Paths are relative to the canonical hub project, not an inferred peer worktree.
+WebP asset display requires acon 0.1.7 or later (agent-console#81). Older 0.1.3/0.1.4 hosts refuse that MIME type; use PNG or JPEG there. The hub adds no transcoder.
+
+Only a guarded public PNG, JPEG or WebP of at most 8 MiB is accepted; extension
+and byte signature must agree. SVG, secret/PII paths, hub state, outside paths,
+links swapped during inspection and two names for the same physical file refuse.
+The hub replaces paths in the payload with opaque asset ids and records its own
+hash. A later asset read repeats the current guard and hash checks; a changed or
+newly private image is refused as changed since posted. Post it again using a
+current public file. A copied visual id in another project's database does not
+select that project's asset: the acon provider binds the project and instance,
+then rechecks metadata/privacy after the guarded read before returning bytes.
+
+The default audience is the console, with an FYI chat stub. Explicit `to` uses
+local addressed delivery, including `to: "user"` for the console; an empty list
+broadcasts to local peers. An explicit
+remote recipient refuses the whole call, rather than silently dropping that
+target. The stub carries only `[visual <id>] <kind>: <title or caption>` and
+`refs.visual`. Peers receive no source, table/comparison body or inline image.
+This feature adds no visual transport over the cross-network broker.
+
+Publication is refused in a private turn or on a PII task, including when policy
+or task privacy changes during an awaited image read. Current privacy also gates
+show, snapshots and assets after posting. Visual file access combines accepted
+runtime restrictions with the normally merged on-disk candidate policy. A pending
+stricter path rule protects new visual access immediately; a pending weaker file
+cannot remove the accepted restriction. Native sessions retain their existing
+configuration-adoption boundary. The raw visual tool input/result is
+excluded from observer capture even when the call is refused; amem/delivery
+capture retains only the sanitized stub. `events.jsonl` records only id, kind,
+payload byte count, image count and optional task id, never title/source/path or
+image bytes. A visual is explanatory material, not approval or completion proof,
+and a visual-only turn does not clear the task's no-write advisory.
+
+Periodic snapshots and task lists read bounded metadata only. Full payload
+screening happens on an explicit show; image reads still check current privacy,
+existence and hash at the asset route. A moved or deleted image leaves the public
+caption/text/alt record readable but cannot serve its old bytes.
+
+A recovery refusal asks you to retry after `ahub status` shows the hold released.
+Role or membership refusals name the missing authority, and a task/config change
+asks for a retry. If the privacy screen is unavailable, restore the configured screen and retry;
+if the visual exceeds its input limit, shorten the text first. Private context, paths and pattern hits
+retain a uniform privacy refusal. Rate limits are checked before expensive
+screening or file reads and checked again at publication.
+
+Task-bound visuals live with their task. Unbound records expire after 30 days;
+`visuals.retention_days` is an integer setting from 1 to 3650 days, applied live,
+with the normal authority guard on raising retention. Expired/removed records
+are unavailable even before a maintenance prune runs. No documentation stamp or
+real-home policy change is performed by posting a visual.
+
+## Agent-authored records
+
+Headless Record handling follows amem's effective machine and repository policy. Set `records: false` in the amem configuration to disable instruction, capture and Record preference; repository policy can only narrow machine policy. There is no hub-only override. Private or unverified contexts fail closed for capture without preventing ordinary answer routing.
+
+Upgrade every amem consumer sharing a memory home together, including native CLI hooks and embedded hub/plugin copies. A 0.22.1 hook drain silently discards Record format-3 spool entries without a counted loss, and its config parser refuses the `records` key even when false, so set `records: false` only after every consumer is upgraded. The hub exact-pins 0.23.1 and uses its public `recordsEnabled` accessor for the active home and execution repository; it does not upgrade the other consumers automatically. No real home is migrated by the feature's fixtures.
+
+Count-only `records capture`, `records forwarded`, `records brief` and `records recall` diagnostics report accepted/dropped rows or before/after UTF-8 bytes. Record text, anchors, native session IDs and credentials are absent from these diagnostics. An absent registry proof or an unavailable Record source preserves old note content; a privacy or policy change during a read withholds the stale block.