@staix/agent-hub 0.12.28 → 0.12.30

package/docs/plans/2026-10-16-amem-p2-read-tools.md

@@ -0,0 +1,28 @@
+# agent-mem P2: hub memory read tools contract
+
+Copied verbatim from issue #412 (plan v3, 2026-10-16) so sandboxed peers can read it. The issue is the source; if they differ, the issue wins.
+
+## Collaboration, between agents (from #412)
+
+- **Between agents.**
+  - Stage A: hub read tools `hub_memory_search`, `hub_memory_show`, `hub_memory_graph`, so sandboxed peers read through the daemon. Their contract:
+    - The project is scoped server-side from the caller (`memoryProjectKey`), never passed as a parameter.
+    - The query and every returned title, node, edge, error and count are screened.
+    - Refused in a PII turn, behind their own capability.
+    - Registered in the MCP, Pi and local catalogs; their arguments and results are excluded from capture.
+    - A schema frozen before P2, with every limit finite and counted in UTF-8 bytes. Proposed numbers (policy, adjustable; the requirement is a finite tested contract):
+      - Inputs: query ≤ 200 bytes; show ≤ 8 ids, each 6 to 64 bytes; graph ≤ 8 start nodes, each ≤ 200 bytes, hops 1 or 2. Over-limit input is refused before any work or log line.
+      - Output budget for the whole result, metadata and errors included: search default 8 / max 20 lines, ≤ 4 KB; show ≤ 8 KB; graph default 60 / max 120 nodes and max 240 edges, ≤ 6 KB, fails first.
+      - Truncation is deterministic. A graph never returns an edge without both endpoints. A cut text excerpt is marked incomplete; id, provenance and kind headers are never cut.
+      - `truncated:N` counts only results the caller may see, after screening. Hidden or unscreened rows are never counted or named.
+      - Ids resolve as today: exact id or a unique prefix among project-visible ids, original ids redirected. An ambiguous, unknown or withheld id gets one refusal that does not reveal candidates.
+      - Tests: UTF-8 input and output, oversized input, dense graph, shared and private rows, ambiguous prefix, every eligible result over budget.
+  - Writes stay `hub_remember` with the existing gates.
+
+## P2 row (from #412 Phases)
+
+| Phase | Where | Content | Gate |
+|---|---|---|---|
+| P2 Read tools | agent-hub | `hub_memory_search`/`show`/`graph` per the collaboration contract and its frozen schema. | The schema tests listed there. C3 and capture-exclusion tests for these tools. A live receipt of pi reading through them. No file-read grant. |
+
+Phase rules from #412: each gate names `scripts/check.sh` ending `check: OK`, `bun run build` when hub tools or the plugin change, and reading `docs/agent-notes/` before editing `daemon.ts`, `bus.ts`, `hub-tools.ts` or `main.ts`. Tests that set `AGENTHUB_HOME` restore it.

package/docs/plans/amem-cases.json

@@ -0,0 +1,482 @@
+[
+  {
+    "id": "T01",
+    "mode": "Truth/lifecycle",
+    "symptom": "Readers with different configured TTLs disagree about expiry.",
+    "resolution": "Persist deadlines in entries/settle/demote ops, instead of deriving with reader configuration.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:140"
+  },
+  {
+    "id": "T02",
+    "mode": "Truth/lifecycle",
+    "symptom": "A late note on an already approved task has no correct lifetime.",
+    "resolution": "Settle old approvals and give late short notes their own clock; approved promotable notes can start long.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-native.test.ts:158; test/memory-store.test.ts:320"
+  },
+  {
+    "id": "T03",
+    "mode": "Truth/lifecycle",
+    "symptom": "An explicit short-horizon note is promoted on approval or loses its own deadline.",
+    "resolution": "Keep explicit short intent and deadline through settlement.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-native.test.ts:190; test/memory-store.test.ts:433"
+  },
+  {
+    "id": "T04",
+    "mode": "Truth/lifecycle",
+    "symptom": "A crash between board approval, settle append and promotion loses settlement effects.",
+    "resolution": "Reconcile approvals at startup and finish logged settlement on later reads.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-native.test.ts:169; test/memory-store.test.ts:140"
+  },
+  {
+    "id": "T05",
+    "mode": "Truth/lifecycle",
+    "symptom": "Demoting a promoted copy exposes a hidden long-lived original; repeated promotion chains drift.",
+    "resolution": "Derive the original/copy chain together for demote/forget operations.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:178; test/memory-store.test.ts:197"
+  },
+  {
+    "id": "T06",
+    "mode": "Truth/lifecycle",
+    "symptom": "A superseded settled source expires or fails to return/promote when its replacement disappears.",
+    "resolution": "Retain promotable source, derive replacement liveness and promote held sources on forget/expiry.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:360; test/memory-store.test.ts:379; test/memory-store.test.ts:391; CM #186471"
+  },
+  {
+    "id": "T07",
+    "mode": "Truth/lifecycle",
+    "symptom": "Promotion changes chronology or drops a replacement relation.",
+    "resolution": "Promotion keeps source date/provenance and supersession.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:415; test/memory-store.test.ts:542"
+  },
+  {
+    "id": "T08",
+    "mode": "Truth/lifecycle",
+    "symptom": "Local or separately written supersessions form a cycle.",
+    "resolution": "Refuse local cycle creation; derive a deterministic broken cycle for split writers.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:458; test/memory-store.test.ts:472; CM #186635"
+  },
+  {
+    "id": "T09",
+    "mode": "Truth/lifecycle",
+    "symptom": "An older embedded supersedes relation clobbers a later explicit operation.",
+    "resolution": "Fold both sources chronologically with deterministic time/id precedence.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:485; CM #186788"
+  },
+  {
+    "id": "T10",
+    "mode": "Truth/lifecycle",
+    "symptom": "Notes on tasks never approved remain forever in the active index.",
+    "resolution": "Persist fixed 180-day backstop; keep append-only history.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:584; docs/memory.md:17"
+  },
+  {
+    "id": "T11",
+    "mode": "Truth/lifecycle",
+    "symptom": "Model-written answers or unconfirmed inferred relations become circular evidence.",
+    "resolution": "Exclude ahub ask answers from import/evidence; keep suggestions non-evidence until a person confirms them.",
+    "status": "guard/design",
+    "source": "PR #356; src/memory/import.ts:68; test/memory-phase3.test.ts:23; test/memory-phase3.test.ts:57"
+  },
+  {
+    "id": "D01",
+    "mode": "Duplicate/identity",
+    "symptom": "One claude-mem observation hashes differently on different checkouts or deny settings.",
+    "resolution": "Text-only import associations stabilize content identity across machines.",
+    "status": "fixed-source",
+    "source": "issue #380; PR #389; test/memory-sync.test.ts:188; CHANGELOG.md:26"
+  },
+  {
+    "id": "D02",
+    "mode": "Duplicate/identity",
+    "symptom": "Legacy duplicate import groups survive sync; naive dedupe can overwrite person replacements.",
+    "resolution": "Read-only dedupe plan plus explicit append-only apply, preserve existing replacements and group forget.",
+    "status": "fixed-source",
+    "source": "issue #380; PR #389; test/memory-dedupe.test.ts:33; test/memory-dedupe.test.ts:61; test/memory-sync.test.ts:218"
+  },
+  {
+    "id": "D03",
+    "mode": "Duplicate/identity",
+    "symptom": "Two machines promoting one demoted entry can create two copies.",
+    "resolution": "Deterministic promotion identity independent of promoting process.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:497"
+  },
+  {
+    "id": "D04",
+    "mode": "Duplicate/identity",
+    "symptom": "A previously given short-term id no longer resolves after promotion or on a remote with only the synced copy.",
+    "resolution": "Resolve original ids through promotedFrom, locally and remotely.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:445; test/memory-store.test.ts:522"
+  },
+  {
+    "id": "R01",
+    "mode": "Retrieval/capture",
+    "symptom": "Native own-platform recall repeats context already injected by hooks.",
+    "resolution": "Claude/Codex get other-platform blocks; other peers get combined recall.",
+    "status": "guard/design",
+    "source": "src/memory/recall.ts:15; test/recall.test.ts:11"
+  },
+  {
+    "id": "R02",
+    "mode": "Retrieval/capture",
+    "symptom": "The first platform consumes a cross-platform recall budget.",
+    "resolution": "Split the budget across returned platform blocks and remove repeated legends.",
+    "status": "regression-covered",
+    "source": "src/memory/recall.ts:78; test/recall.test.ts:70"
+  },
+  {
+    "id": "R03",
+    "mode": "Retrieval/capture",
+    "symptom": "A stopped/changed/hung worker could block or fail a turn.",
+    "resolution": "2-second fail-open client returns undefined and logs the dropped call.",
+    "status": "guard/design",
+    "source": "src/memory/client.ts:20; test/memory.test.ts:14"
+  },
+  {
+    "id": "R04",
+    "mode": "Retrieval/capture",
+    "symptom": "Local-worker summarize was skipped as subagent context.",
+    "resolution": "Omit agentId on summarize; live 13.25.1 observation recorded.",
+    "status": "historical-fixed",
+    "source": "src/memory/capture.ts:74; docs/smoke.md:658"
+  },
+  {
+    "id": "R05",
+    "mode": "Retrieval/capture",
+    "symptom": "Unawaited session-end disappears when the process exits.",
+    "resolution": "Await bounded Capture.end at shutdown.",
+    "status": "historical-fixed",
+    "source": "src/memory/capture.ts:83; docs/smoke.md:658"
+  },
+  {
+    "id": "R06",
+    "mode": "Retrieval/capture",
+    "symptom": "A new fail note reaches only the next session, after a peer retries the rejected approach.",
+    "resolution": "Ride notes on the other peers next delivery, newest ten, without a separate turn.",
+    "status": "historical-fixed",
+    "source": "CHANGELOG.md:427 (previous repository #68); docs/smoke.md:1092"
+  },
+  {
+    "id": "R07",
+    "mode": "Retrieval/capture",
+    "symptom": "A failed delivery returns an old preface over a newer preface.",
+    "resolution": "Merge/restore the preface without overwriting newer memory.",
+    "status": "historical-fixed",
+    "source": "CHANGELOG.md:427 (previous repository #68)"
+  },
+  {
+    "id": "R08",
+    "mode": "Retrieval/capture",
+    "symptom": "Generated guidance treats workflow task/review events as reference-only memory.",
+    "resolution": "Distinguish message kinds; only presence recall is reference.",
+    "status": "historical-fixed",
+    "source": "CHANGELOG.md:526; docs/smoke.md:714 (previous repository #11)"
+  },
+  {
+    "id": "R09",
+    "mode": "Retrieval/capture",
+    "symptom": "Observer returns prose twice instead of observation XML and drops queued batches.",
+    "resolution": "Later observation reports lastSuccess and zero consecutiveFailures; exact dropped data recovery was not established.",
+    "status": "historical-partial",
+    "source": "CM #119860; CM #120247"
+  },
+  {
+    "id": "R10",
+    "mode": "Retrieval/capture",
+    "symptom": "Observer allowance/provider failure stops capture.",
+    "resolution": "Historical OpenRouter switch restored processing; ongoing cost and maintenance conflict remained.",
+    "status": "historical-partial",
+    "source": "CM S5886"
+  },
+  {
+    "id": "R11",
+    "mode": "Retrieval/capture",
+    "symptom": "Plugin registration exists but cache runtime, correct home or recall adapter is absent.",
+    "resolution": "Historical cache dependency installation and later dot memory adapter repair; not a current live-readiness claim.",
+    "status": "historical-partial",
+    "source": "CM S6037; CM #197226; MEMORY.md:177; rollout 01a13bd8, lines 35-37"
+  },
+  {
+    "id": "R12",
+    "mode": "Retrieval/capture",
+    "symptom": "SessionStart context hooks run before the claude-mem launcher compilation completes.",
+    "resolution": "Self-heal completes; identical hook rerun exits zero. Missing-PATH/version-cache hypotheses were disproved.",
+    "status": "historical-fixed",
+    "source": "CM S11000; CM #191224; CM #191227"
+  },
+  {
+    "id": "R13",
+    "mode": "Retrieval/capture",
+    "symptom": "Global LIMIT before project filtering starves target imports; repeated runs replay the same window or skip a recreated lower-id source.",
+    "resolution": "Project-aware SQL and persisted cursor advance handled rows; restart reconsiders skips; reset compares selected-project candidate ids.",
+    "status": "fixed-source",
+    "source": "issue #380; PR #389; test/memory-phase3.test.ts:120; test/memory-phase3.test.ts:147; test/memory-phase3.test.ts:171; commit d5738472"
+  },
+  {
+    "id": "X01",
+    "mode": "Project isolation",
+    "symptom": "Unrelated repositories with the same basename share claude-mem recall/import scope.",
+    "resolution": "Native memory origin key fixes its own namespace; claude-mem basename ambiguity remains. Import comment gives no local cure.",
+    "status": "open-ceiling",
+    "source": "src/memory/import.ts:57; docs/smoke.md:1101; src/memory/recall.ts:98"
+  },
+  {
+    "id": "X02",
+    "mode": "Project isolation",
+    "symptom": "Importing the whole superproject chain imports another projects notes under this projects policy.",
+    "resolution": "Import selects only chain.at(-1), the current source project.",
+    "status": "regression-covered",
+    "source": "src/memory/import.ts:45; src/memory/import.ts:54; test/memory-phase3.test.ts:23"
+  },
+  {
+    "id": "X03",
+    "mode": "Project isolation",
+    "symptom": "Native basename/path or unscoped-id lookups collide across projects/machines.",
+    "resolution": "Canonical origin key, local path hash fallback, project-scoped id access and native worktree aliases.",
+    "status": "regression-covered",
+    "source": "test/memory-store.test.ts:140; test/memory-store.test.ts:296; test/recall.test.ts:51"
+  },
+  {
+    "id": "X04",
+    "mode": "Project isolation",
+    "symptom": "A replacement narrows visibility and suppresses an entry for readers that cannot see the replacement.",
+    "resolution": "Reject narrower replacement visibility.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:284"
+  },
+  {
+    "id": "P01",
+    "mode": "Privacy",
+    "symptom": "A done/review/unmet/context summary on an ordinary task carries PII to cloud memory.",
+    "resolution": "Pattern/screen withheld text remains on board; memory and public peer messages receive no private body.",
+    "status": "fixed-source",
+    "source": "issue #69; PR #73; issue #185 / PR #192; CHANGELOG.md:363; CHANGELOG.md:232"
+  },
+  {
+    "id": "P02",
+    "mode": "Privacy",
+    "symptom": "Raw hub tool arguments/results bypass Tasks privacy refusal via local capture.",
+    "resolution": "Exclude task/conductor/hub_send capture, keeping ordinary tool capture.",
+    "status": "fixed-source",
+    "source": "issue #230; PR #237; CHANGELOG.md:188"
+  },
+  {
+    "id": "P03",
+    "mode": "Privacy",
+    "symptom": "An ordinary local turn reads full PII board rows and then captures/repeats them.",
+    "resolution": "Return stubs except during an in-process PII turn; PII turns never capture.",
+    "status": "fixed-source",
+    "source": "issue #230; PR #237"
+  },
+  {
+    "id": "P04",
+    "mode": "Privacy",
+    "symptom": "Private path references in text, refs, symbols or Unicode/space paths reach either memory.",
+    "resolution": "Check private paths before native/cloud writes and in model-facing records.",
+    "status": "regression-covered",
+    "source": "test/memory-native.test.ts:204; test/memory-store.test.ts:556; src/hub/tasks.ts:2293"
+  },
+  {
+    "id": "P05",
+    "mode": "Privacy",
+    "symptom": "A previously accepted/shared/synced note violates the current receiving policy or has sensitive metadata.",
+    "resolution": "Rescreen whole records on model-facing reads, including nodes/project/secret patterns.",
+    "status": "regression-covered",
+    "source": "src/hub/daemon.ts:838; test/memory-store.test.ts:556; src/memory/recall.ts:153"
+  },
+  {
+    "id": "P06",
+    "mode": "Privacy",
+    "symptom": "Invalid unrelated config field silently empties pii.paths for memory CLI reads.",
+    "resolution": "Strict policy load fails closed; malformed present config is distinct from absence.",
+    "status": "regression-covered",
+    "source": "CM S10834; test/memory-store.test.ts:584; src/cli/memory.ts:32"
+  },
+  {
+    "id": "P07",
+    "mode": "Privacy",
+    "symptom": "Promotion sends local short notes to synced long-term storage without a current policy verdict.",
+    "resolution": "PromotionScreen must promote/keep/skip under source-project policy; rescreen task current paths and hold unknown project.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:672; test/memory-store.test.ts:691; src/memory/store.ts:327"
+  },
+  {
+    "id": "P08",
+    "mode": "Privacy",
+    "symptom": "Sync publishes note text to a public remote, or visibility cannot be verified.",
+    "resolution": "Known-public refused; unknown visibility only warns (residual policy limit); forget does not purge Git history.",
+    "status": "guard/design",
+    "source": "PR #354; src/memory/sync.ts:94; test/memory-sync.test.ts:57; docs/memory.md:145"
+  },
+  {
+    "id": "P09",
+    "mode": "Privacy",
+    "symptom": "Tracked project configuration redirects the cloud memory endpoint to receive task text.",
+    "resolution": "Memory endpoint applies only from machine-local untracked configuration, checked by file identity.",
+    "status": "fixed-source",
+    "source": "issue #17; PR #19; CHANGELOG.md:406"
+  },
+  {
+    "id": "I01",
+    "mode": "Index integrity/freshness",
+    "symptom": "Malformed, bad-id, non-string or invalid-time synced lines poison derived state.",
+    "resolution": "Validate schema/content hash/types/time; skip invalid rows and wait for partial tails.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:73; test/memory-store.test.ts:178; test/memory-store.test.ts:542; test/memory-sync.test.ts:159"
+  },
+  {
+    "id": "I02",
+    "mode": "Index integrity/freshness",
+    "symptom": "Truncation or same-size/deep prefix rewrite evades byte-offset indexing.",
+    "resolution": "Hash indexed prefixes and rebuild on shrink/change.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:217; test/memory-store.test.ts:237; test/memory-store.test.ts:255"
+  },
+  {
+    "id": "I03",
+    "mode": "Index integrity/freshness",
+    "symptom": "A durable log append is reported failed when derived SQLite refresh is busy, encouraging duplicate retries.",
+    "resolution": "Return saved id after durable append; mark index stale and log refresh failure.",
+    "status": "regression-covered",
+    "source": "CM S10834; src/memory/store.ts:223; test/memory-store.test.ts:607"
+  },
+  {
+    "id": "I04",
+    "mode": "Index integrity/freshness",
+    "symptom": "Catching the failed refresh without retry makes saved notes permanently invisible to this process.",
+    "resolution": "Read paths ensure freshness and retry a dirty index.",
+    "status": "regression-covered",
+    "source": "CM #187423; CM #187425; test/memory-store.test.ts:607"
+  },
+  {
+    "id": "I05",
+    "mode": "Index integrity/freshness",
+    "symptom": "A long-lived reader misses another processes durable write whose indexing failed.",
+    "resolution": "Compare segment shape on reads as well as local stale state.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:618; src/memory/store.ts:585"
+  },
+  {
+    "id": "I06",
+    "mode": "Index integrity/freshness",
+    "symptom": "Goal/link/lease and suggestion/verdict reads bypass note freshness recovery.",
+    "resolution": "Share ensureFresh across those read families; no new log/index format.",
+    "status": "fixed-source",
+    "source": "issue #378; PR #379; test/memory-store.test.ts:633; docs/verification/2026-10-14-0.12.24-audit.md:24"
+  },
+  {
+    "id": "I07",
+    "mode": "Index integrity/freshness",
+    "symptom": "Idle expiry is hidden by view filtering while index rows still differ from rebuild.",
+    "resolution": "Prune on read so derived rows and rebuild agree.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:511"
+  },
+  {
+    "id": "S01",
+    "mode": "Sync/concurrency",
+    "symptom": "Concurrent first-open or corrupt winning machine.json files yield inconsistent/undefined machine identity.",
+    "resolution": "Exclusive creation then common validated reread; malformed id fails store construction.",
+    "status": "regression-covered",
+    "source": "PR #352; test/memory-store.test.ts:272; test/memory-store.test.ts:360; CM #186471; CM #186474"
+  },
+  {
+    "id": "S02",
+    "mode": "Sync/concurrency",
+    "symptom": "Killed Git leaves index.lock or interrupted merge, hiding subsequent local entries from sync.",
+    "resolution": "Signed machine sync lock serializes Git; clear stale owned Git lock and abort interrupted merge.",
+    "status": "regression-covered",
+    "source": "PR #354; src/memory/sync.ts:31; test/memory-sync.test.ts:159"
+  },
+  {
+    "id": "S03",
+    "mode": "Sync/concurrency",
+    "symptom": "Concurrent pushes or absent/unreachable remote make memory transport fail.",
+    "resolution": "Own-machine segments, pull/merge, one retry after push race; errors return fail-open result.",
+    "status": "guard/design",
+    "source": "PR #354; src/memory/sync.ts:61; test/memory-sync.test.ts:33; test/memory-sync.test.ts:57"
+  },
+  {
+    "id": "S04",
+    "mode": "Sync/concurrency",
+    "symptom": "Two machines claim one goal before synchronization.",
+    "resolution": "Advisory earlier-claim winner with conflict displayed; force resolution by person; broker needed for consensus.",
+    "status": "open-ceiling",
+    "source": "src/memory/store.ts:718; test/memory-sync.test.ts:69"
+  },
+  {
+    "id": "C01",
+    "mode": "Scale/cost/measurement",
+    "symptom": "Promote check and append race with another processes forget/replacement.",
+    "resolution": "Open ceiling: per-machine mutation lock would make check+append atomic.",
+    "status": "open-ceiling",
+    "source": "src/memory/store.ts:335"
+  },
+  {
+    "id": "C02",
+    "mode": "Scale/cost/measurement",
+    "symptom": "Every refresh hashes the whole indexed prefix, O(segment bytes).",
+    "resolution": "Open ceiling: block hash chain if measured scale warrants it.",
+    "status": "open-ceiling",
+    "source": "src/memory/store.ts:392"
+  },
+  {
+    "id": "C03",
+    "mode": "Scale/cost/measurement",
+    "symptom": "Repeated concurrent writers exceed bounded refresh retries.",
+    "resolution": "Open ceiling: five retry levels then deferred work; shared read lock is proposed upgrade.",
+    "status": "open-ceiling",
+    "source": "src/memory/store.ts:430"
+  },
+  {
+    "id": "C04",
+    "mode": "Scale/cost/measurement",
+    "symptom": "Views materialize/filter all rows in process memory.",
+    "resolution": "Open ceiling: SQL filtering when store size warrants it.",
+    "status": "open-ceiling",
+    "source": "src/memory/store.ts:490"
+  },
+  {
+    "id": "C05",
+    "mode": "Scale/cost/measurement",
+    "symptom": "Clock rollback resurrects an expired row after rebuild.",
+    "resolution": "Open ceiling: durable prune entry, instead of wall-clock-only expiry.",
+    "status": "open-ceiling",
+    "source": "src/memory/store.ts:569"
+  },
+  {
+    "id": "C06",
+    "mode": "Scale/cost/measurement",
+    "symptom": "Three-characters-per-token approximation is not an exact token ceiling.",
+    "resolution": "Open ceiling: tokenizer if exact bounds are required.",
+    "status": "open-ceiling",
+    "source": "src/memory/recall.ts:54"
+  },
+  {
+    "id": "C07",
+    "mode": "Scale/cost/measurement",
+    "symptom": "Dashboard Memory recomputes the whole index per poll.",
+    "resolution": "Open ceiling: cache by index revision when measured poll cost warrants it.",
+    "status": "open-ceiling",
+    "source": "src/hub/daemon.ts:3197"
+  },
+  {
+    "id": "C08",
+    "mode": "Scale/cost/measurement",
+    "symptom": "Adoption decisions lack causal effectiveness/cost measurements; brief counts cannot prove a failed approach was retried.",
+    "resolution": "#247/#248/#258 ship counts/arms/report plumbing; controlled arms, field window and manual retry labels remain owed.",
+    "status": "open-measurement",
+    "source": "issue #248 AC2-4; issue #258 AC11; PR #351; PR #356; docs/smoke.md:68; docs/research.md:88"
+  }
+]

package/docs/quickstart.md

@@ -4,7 +4,7 @@ agent-hub lets the coding agents on one machine work as peers in one project dir
 
 ## Install
 
-Needs [Bun](https://bun.sh) 1.3 or newer and macOS (Linux works without the `local` worker's `bash` and `git` tools, which need the macOS sandbox).
+Needs [Bun](https://bun.sh) 1.4.2 or newer and macOS (Linux works without the `local` worker's `bash` and `git` tools, which need the macOS sandbox).
 
 Node alone is not supported. Keep `bun` on PATH even if you install with npm.
 The registry package uses the `staix` organization scope. Install from npm:
@@ -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.28
+bun add -g github:STAIxBWLB/agent-hub#v0.12.30
 ahub setup
 ```
 
@@ -69,12 +69,19 @@ or set `OMNIROUTE_API_KEY`. Name the model in `.agenthub/routing.toml` (`[local]
 | `ahub task propose [--class <c>] <title>` | put work on the board; the hub picks an owner and a reviewer, and the class if you name none |
 | `ahub board` | who has what; `ahub task show <id>` for one task |
 | `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 |
 | `ahub stop <peer>` | stop one headless peer (Kimi, headless Pi, `local`); the hub and the other peers keep running |
 | `ahub kill` | stop the daemon and everything it started |
 
 More: `ahub help`. How it is built and why: [`docs/specs/2026-09-19-agent-hub-design.md`](specs/2026-09-19-agent-hub-design.md). What it protects and what it does not: [`docs/security.md`](security.md).
 
+## 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.
+
+Before any real generation migration, upgrade every hub sharing that memory home to 0.12.30 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.
+
 ## Browser dashboard
 
 After `ahub up`, run `ahub ui` to open the local dashboard. It refreshes the

package/docs/security.md

@@ -7,7 +7,7 @@ agent-hub connects agents that can each run commands. This page says what the hu
 - **Other agents' text is untrusted.** Every message that crosses from one peer to another is framed as untrusted input: a channel tag with `meta.source` for Claude started with `ahub claude`; otherwise a fixed header line (`frame()`, `[agent-hub message from ...]`) with an instruction that says it is untrusted, the plugin's server instructions for a tools-only Claude reading `hub_inbox` and a standing instruction for the others. A message body cannot forge the hub's own headers: such lines are quoted (`sanitize`). Replies inherit a hop count capped at 3, so agents cannot ping-pong forever; neither a digest nor a steer can reset it.
 - **The control link is loopback plus a secret.** The daemon and the Codex proxy bind 127.0.0.1 only. The control WebSocket requires a per-run token (`.agenthub/state/control-token`, mode 600), and both servers refuse any request that carries an `Origin` header: any web page can open a WebSocket to localhost, and browsers always send `Origin`. External clients cannot claim the console user's id or a hub-managed peer's id.
 - **Permission prompts stay on unless an operator selects a permission mode.** `ask` leaves native decisions unchanged. `ask-when-needed` grants scoped Claude file tools or Pi/local writes and edits; Kimi and Codex use their own native policies. `never-ask` requires explicit runtime confirmation or a person's console `y` for a config default at hub start. Until that config confirmation the peer runs in `ask`. Kimi's and `local`'s permission requests are relayed to the console and cancelled after `approvals.timeout_s` (default 120 s) of silence; the macOS notification for a waiting request carries the peer and the tool name only. The one exception is the hub's own tools (`hub_send` and the task tools, matched by exact name): Kimi's requests for them are approved once without a prompt and logged by name, the same trust Codex gets through `approval_mode` in the hub's config. They invoke hub-owned operations rather than arbitrary file or shell tools, and every call passes the hub's own checks. Identity comes from the exact permission title, or from the earlier tool-call title bound to the same call id and resolved against the configured MCP servers when the permission title contains argument JSON (Qwen). Payload text and unrelated display titles never establish identity. For ACP agents, a payload longer than the console shows is marked as cut and never offers a session-wide grant. Pi's write, edit, shell and git write requests are relayed the same way and can be answered `Always allow <tool> until Pi restarts`: later calls of that tool by the same Pi start skip the prompt but stay inside the path guard and sandbox. The grant covers every later call of that tool whatever its payload, is kept in memory only, cannot be given from the dashboard, and each call it allows is logged by tool name. A Pi or `local` request whose call was cancelled or whose turn ended is withdrawn at once: a later answer is refused and grants nothing, an `Always allow` included. One shell command runs without a hub approval: the `!command` a person types in the managed Pi TUI. It stays inside the same sandbox and denylist, and the hub takes it only from the verified owner process of a Pi in TUI mode, while Pi is idle, on a reservation that is used once; a model's own bash call never takes that path (issue #253). `--unattended` turns prompts off, says so loudly, and is never the default.
-- **A committed config cannot choose launch commands, credential files, data endpoints, permission modes or a wider sandbox.** The machine-local fields (`kimi_cmd`, `permission_modes`, `codex_bin`, `pi.cmd`, `checks`, `mlx.bin`, `mlx.runtimeDir`, `mlx.modelPath`, `omniroute.urls`, `omniroute.access_hosts`, the `omniroute` key files, `memory.worker_url`, `local.read_allow`, `local.bash_network`, `local.network_allow`, `terminal.open`) apply only from a config file git confirms nobody committed: `.agenthub/config.json` or `.agenthub/config.local.json`, matched by file identity so no other spelling the file system accepts slips past, and `.agenthub` itself not a committed symlink or submodule. Without a repository, or when git fails, they keep their defaults; an empty value always means the default. "Untracked" is answered by the repository that contains the project: a checkout copied or extracted into an unrelated repository, or into an ignored directory of one, is trusted like your own files. So a cloned repository cannot choose a launch command, a completion check, a gateway to send a key file to, a memory endpoint, a permission mode, the command that opens a terminal, or a wider sandbox. A command in `checks` runs as you, outside the local worker's sandbox, like a git hook. So do the `setup` and `verify` commands of a benchmark suite (issue #251): `ahub bench run <suite.json>` is a person's command, refused from an agent session, and it resets the work tree for each attempt, so it runs only with `bench.enabled`, at the root of a clean repository that tracks nothing under `.agenthub/`. Nothing in `routing.toml` or in task text is ever run. `routing.toml` and the other shared fields still come from the checkout, and they matter: `routing.toml` picks the models the local worker and the hub's inference use at your gateway and can turn the PII constraint off, and roles and budget shape who does what. Review them in a repository you do not trust. The hub's own git calls outside the sandbox (snapshots, facts, config trust, project discovery, memory recall, the bench runner) all go through the one helper in `src/hub/git.ts`, which disables the programs a repository's configuration can name — the file-system monitor, hooks, external diff, the pager, and the credential and askpass helpers, with prompts failing closed — so a config that ever does get written cannot run code with the hub's rights. Of those, the monitor, hooks and external diff are reachable by commands the hub issues (the planted-program test exercises all three; a `diff --no-index` reads the repo's config, so that call also passes `--no-ext-diff` and `--no-textconv`); the pager and the credential and askpass helpers are not (every call pipes stdout, and no hub command authenticates), and their settings are belt and suspenders. The cost: `core.fsmonitor=false` also turns off a person's enabled built-in monitor for the hub's own calls, so the per-turn snapshot's `add -A` scans the whole tree (the snapshot has a 10 s cap). git has no global switch for filter drivers, and of the hub's commands only the snapshot's `add`/`restore` would run one (its driver command lives in the protected `.git/config`).
+- **A committed config cannot choose launch commands, credential files, data endpoints, permission modes or a wider sandbox.** The machine-local fields (`kimi_cmd`, `permission_modes`, `codex_bin`, `pi.cmd`, `checks`, `mlx.bin`, `mlx.runtimeDir`, `mlx.modelPath`, `omniroute.urls`, `omniroute.access_hosts`, the `omniroute` key files, `memory.worker_url`, `local.read_allow`, `local.bash_network`, `local.network_allow`, `terminal.open`) apply only from a config file git confirms nobody committed: `.agenthub/config.json` or `.agenthub/config.local.json`, matched by file identity so no other spelling the file system accepts slips past, and `.agenthub` itself not a committed symlink or submodule. Without a repository, or when git fails, they keep their defaults; an empty value always means the default. "Untracked" is answered by the repository that contains the project: a checkout copied or extracted into an unrelated repository, or into an ignored directory of one, is trusted like your own files. So a cloned repository cannot choose a launch command, a completion check, a gateway to send a key file to, a memory endpoint, a permission mode, the command that opens a terminal, or a wider sandbox. A command in `checks` runs as you, outside the local worker's sandbox, like a git hook. So do the `setup` and `verify` commands of a benchmark suite (issue #251): `ahub bench run <suite.json>` is a person's command, refused from an agent session, and it resets the work tree for each attempt, so it runs only with `bench.enabled`, at the root of a clean repository that tracks nothing under `.agenthub/`. Nothing in `routing.toml` or in task text is ever run. `routing.toml` and the other shared fields still come from the checkout, and they matter: `routing.toml` picks the models the local worker and the hub's inference use at your gateway and can turn the PII constraint off, and roles and budget shape who does what. Review them in a repository you do not trust. The hub's own git calls outside the sandbox (snapshots, facts, config trust, project discovery, memory recall, the bench runner) all use the single hardened implementation in the exact-pinned first-party `@staix/agent-mem/platform` package, re-exported by `src/hub/git.ts`, which disables the programs a repository's configuration can name — the file-system monitor, hooks, external diff, the pager, and the credential and askpass helpers, with prompts failing closed — so a config that ever does get written cannot run code with the hub's rights. Of those, the monitor, hooks and external diff are reachable by commands the hub issues (the planted-program test exercises all three; a `diff --no-index` reads the repo's config, so that call also passes `--no-ext-diff` and `--no-textconv`); the pager is not (every call pipes stdout). Credential and askpass helpers are disabled for project repositories; memory sync alone may use credentials for its own memory repository, without prompts. The cost: `core.fsmonitor=false` also turns off a person's enabled built-in monitor for the hub's own calls, so the per-turn snapshot's `add -A` scans the whole tree (the snapshot has a 10 s cap). git has no global switch for filter drivers, and of the hub's commands only the snapshot's `add`/`restore` would run one (its driver command lives in the protected `.git/config`).
 - **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.
@@ -21,6 +21,18 @@ agent-hub connects agents that can each run commands. This page says what the hu
 - **Secrets stay where they are read.** The gateway key and Cloudflare Access values are read inside the gateway client and go only into request headers: never into logs, errors, envelopes, tool output, memory, or the generated Switchyard config (the key travels by environment variable name). Subscription logins of Claude, Codex and Kimi are never proxied or pooled.
 - **The hub's own model calls are fenced.** Digest condensation, task triage and the PII screen read agent-written text as data; their output is capped text framed as untrusted, or a value checked against a closed list. It is never used as a route, a peer id, a tool call or an instruction.
 
+## 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.
+
+`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.
+
+`hub_memory_correct` requires `memory_correct` and proposes a machine-local candidate after the same project/privacy checks, including revalidation after asynchronous screening. It cannot accept or alter a note. Public review failures with unmet items may also propose candidates through Tasks. Candidates and usage counters stay at `M/candidates.db`, are not synced/imported, and never enter recall, briefs, ask or graph evidence. A person accepts shared-v1 candidates through the package CLI's TTY/policy checks; the accepted result is an ordinary v1 note, while the sidecar remains local. Generation `amem review` remains unsupported and refuses. Citation counters are observation proxies, not evidence that an agent understood or used a note.
+
+The hub binds the selected root/profile at open. Invalid/missing generation metadata refuses native memory without a shared-v1 fallback; the bus and board continue. Explicit checks at hub operation entry and before sidecar writes stop later stale calls, but are not atomic against a selector change during an in-flight core operation. Migration therefore requires quiescing consumers and closing handles before changing selection, then reopening through the supported lifecycle. A public core pre-write hook is the upgrade path for atomic in-flight cutover.
+
+Before migrating any real home, every hub sharing it must first be on 0.12.30 with positive authenticated binding or unbound/quiesced proof from `ahub memory profile-check` in each relevant registry. An unknown or unreadable runtime is not proof of absence, and a matching ready binding still holds a handle that must be closed. Profile-check reports only its named registry inventory. Root paths, selector receipts and malformed-legacy counts are person-local diagnostics, excluded from ordinary peer status and allowed agent CLI reads. Source/fixture checks do not establish native capture, real migration or account/device-sync success.
+
 ## What is not defended
 
 - **A malicious local process running as you.** It can read the control token, `hub.db`, the project and your home directory without the hub's help. The token keeps web pages and other users out, not your own processes.
@@ -71,10 +83,35 @@ or the native Claude/Codex shell marker when the hub marker is absent. It connec
 as that peer in tools mode. Messages and task changes retain that actor;
 `say` defaults to status priority and important messages still require the peer's
 capability. Conflicting or malformed markers fail closed. There is no `--as-user`.
-Human-only operations are refused before connecting, including permission answers
+By default, console operations are refused before connecting, including permission answers
 and permission modes, queue resolution, budget overrides, benchmark runs, research
 backfill and task labels, stopping a peer (`ahub stop`), lifecycle and recovery
 operations, and `ask`.
+For live verification explicitly authorized by the user, an agent may invoke
+`ahub --live-test [--project <path|id>] <command> [args...]`. The flag delegates
+the existing console authority for console-class operations and conductor-class peer starts/holds, including approvals,
+settings, roster and lifecycle operations. It does not restrict effects to a
+scratch project: the agent must stay within the authorized commands and targets.
+Malformed or conflicting caller markers still refuse. The original peer and
+closed command label are recorded with outcome `delegated` before execution;
+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.
+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.
+The flag is not stored in settings or exported to native agent children. Ahub's
+own daemon launch, console subprocesses, recovery runner, interactive follow-up commands and upgrade coordinator
+handover carry it explicitly in argv. Each new top-level invocation needs its
+own flag. An older CLI does not support it; use a candidate with this feature
+for the continuation too. Staging rejects a target without the pinned
+`LIVE_TEST_SUPPORTED` declaration before preparation or commit, including a
+previously cached stage. Delegated headless-native restoration uses the ordinary target CLI with its
+operationId through that operational console authority. Native and TUI
+restoration keep their existing identity and ownership checks. External computer-use restrictions remain unchanged.
 The operator uses a plain terminal or `ahub console`. A Claude `!` command that
 inherits the agent markers follows the same rule. The console strips control
 sequences from agent and daemon text before it quotes forged headers, and its