@staix/agent-hub 0.12.29 → 0.12.31

package/docs/plans/2026-10-16-amem-failure-registry.md

@@ -0,0 +1,101 @@
+# Agent-mem P0 failure registry
+
+Issue #412 P0 annex. Inventory: `docs/plans/amem-cases.json` (60 cases, 8 modes). Source references were relocated against HEAD `5af9eb9bff85f4705a351441ea7d3ff1553cf121`; case status is the inventory status, not a new verification claim. This document records retained source assertions and declared ceilings; tests and live legs were not executed for the mapping.
+
+Evidence scope is repo-only: all mechanism and regression references below come from this checkout; external historical outcomes are retained as inventory status, not newly verified.
+
+## Table A
+
+Owner names describe the mechanism after the split. P4 ports core regressions; P5 retains hub integration regressions. Mixed rows can cite both. A `ceiling` citation records the first words of a current `ponytail:` comment and does not claim the limitation is fixed. S04 has no planned phase because a consensus broker is out of scope. I06 preserves the exact template source, including substitutions, for its 12 parameterized tests.
+
+| id | mode | status | owner module | phase | retained regression or declared ceiling |
+| --- | --- | --- | --- | --- | --- |
+| T01 | Truth/lifecycle | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review fixes: deadlines are fixed when written, ids resolve within the project's view, and a cut-short settlement finishes at the next start` |
+| T02 | Truth/lifecycle | regression-covered | agent-hub: tasks.ts | P5 | `test/memory-native.test.ts` :: `a late note on an already approved task starts its clock at once (review of #352)`; `test/memory-store.test.ts` :: `review of #352: a late short-term note on a settled task gets its own clock, and a forgotten replacement shows the old entry again` |
+| T03 | Truth/lifecycle | regression-covered | agent-hub: tasks.ts | P5 | `test/memory-native.test.ts` :: `an explicit short horizon on an open task is never promoted, and a bad short_ttl_days fails the config (review of #352)`; `test/memory-store.test.ts` :: `review of #352: an explicit short note on an open task keeps its own deadline through approval` |
+| T04 | Truth/lifecycle | regression-covered | agent-hub: tasks.ts | P5 | `test/memory-native.test.ts` :: `an approval a stop cut off before its settle entry is settled when the hub starts again (review of #352)`; `test/memory-store.test.ts` :: `review fixes: deadlines are fixed when written, ids resolve within the project's view, and a cut-short settlement finishes at the next start` |
+| T05 | Truth/lifecycle | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a demoted copy takes its hidden original with it, and malformed synced lines are skipped`; `test/memory-store.test.ts` :: `review of #352: twice-promoted chains, non-string metadata and provenance nodes` |
+| T06 | Truth/lifecycle | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a superseded source of a settled task is kept for when its replacement goes, and a corrupt machine id fails the store`; `test/memory-store.test.ts` :: `review of #352: a held source moves to long-term as soon as its replacement is forgotten`; `test/memory-store.test.ts` :: `review of #352: a held source is promoted when its replacement expires while the store is idle, and an unreadable expiry is skipped` |
+| T07 | Truth/lifecycle | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a promoted replacement keeps its supersession, and a promotion is dated as its source`; `test/memory-store.test.ts` :: `review of #352: promoting a replaced entry keeps it replaced, and a non-UTC at is skipped` |
+| T08 | Truth/lifecycle | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a supersession that would close a cycle is refused, and an undated settle is skipped`; `test/memory-store.test.ts` :: `review of #352: a cycle made by supersessions written apart drops its earliest relation` |
+| T09 | Truth/lifecycle | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a later supersede op wins over an earlier note's own supersedes` |
+| T10 | Truth/lifecycle | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a note on a task never approved leaves after the fixed backstop, and the CLI screens what it prints` |
+| T11 | Truth/lifecycle | guard/design | agent-mem: import.ts | P4 | `test/memory-phase3.test.ts` :: `claude-mem import copies the hub's notes of this project once, never model answers, PII or secrets, and never writes claude-mem`; `test/memory-phase3.test.ts` :: `model-suggested edges are drawn but are not evidence until a person confirms them; a rejected one disappears` |
+| D01 | Duplicate/identity | fixed-source | agent-mem: import.ts | P4 | `test/memory-sync.test.ts` :: `CLI claude-mem imports use text-only nodes across checkouts and local deny policies, then converge in either sync order` |
+| D02 | Duplicate/identity | fixed-source | agent-mem: store.ts | P4 | `test/memory-dedupe.test.ts` :: `legacy dedupe lists without writes, applies append-only, repeats without writes, and forget removes the whole tuple`; `test/memory-dedupe.test.ts` :: `dedupe sends a single remaining head to the newest valid outside terminal, preserving both personal replacements`; `test/memory-sync.test.ts` :: `legacy duplicate dedupe syncs append-only and divergent prior relations converge after a re-run` |
+| D03 | Duplicate/identity | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: two machines promoting the same demoted entry write one copy` |
+| D04 | Duplicate/identity | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a short-term id kept past its task's approval reaches the promoted copy`; `test/memory-store.test.ts` :: `review of #352: another machine with only the synced copy resolves the original short-term id` |
+| R01 | Retrieval/capture | guard/design | agent-mem: recall.ts | P4 | `test/recall.test.ts` :: `kimi gets every platform in one call; codex gets the other platforms only, without the repeated legend` |
+| R02 | Retrieval/capture | regression-covered | agent-mem: recall.ts | P4 | `test/recall.test.ts` :: `the token budget is split per platform so the first one cannot crowd out the rest` |
+| R03 | Retrieval/capture | guard/design | agent-mem: client.ts | P4 | `test/memory.test.ts` :: `fail-open: a stopped worker, an unknown endpoint and a hang all yield undefined with one log line` |
+| R04 | Retrieval/capture | historical-fixed | agent-hub: capture.ts | P5 | `test/local-worker.test.ts` :: `claude-mem capture: init, one observation per tool call, summarize, session-end; skip list and denylisted paths stay out; a down worker blocks nothing` |
+| R05 | Retrieval/capture | historical-fixed | agent-hub: capture.ts | P5 | gap |
+| R06 | Retrieval/capture | historical-fixed | agent-hub: bus.ts | P5 | `test/bus.test.ts` :: `shared notes ride in the preface after recall, never as a delivery of their own; the newest ten are kept` |
+| R07 | Retrieval/capture | historical-fixed | agent-hub: bus.ts | P5 | `test/bus.test.ts` :: `a preface made while a delivery is in flight survives that delivery's failure, and both go out once` |
+| R08 | Retrieval/capture | historical-fixed | agent-hub: templates/AGENTS.block.md | P5 | gap |
+| R09 | Retrieval/capture | historical-partial | external: claude-mem | external | gap |
+| R10 | Retrieval/capture | historical-partial | external: claude-mem | external | gap |
+| R11 | Retrieval/capture | historical-partial | external: claude-mem | external | gap |
+| R12 | Retrieval/capture | historical-fixed | external: claude-mem | external | gap |
+| R13 | Retrieval/capture | fixed-source | agent-mem: import.ts | P4 | `test/memory-phase3.test.ts` :: `claude-mem project filtering prevents starvation and the local cursor advances bounded windows, including skipped rows`; `test/memory-phase3.test.ts` :: `claude-mem cursor survives reopen and resets a recreated project source even when unrelated rows have higher ids`; `test/memory-phase3.test.ts` :: `claude-mem cursor records completed rows after a callback error and restart reconsiders earlier privacy skips` |
+| X01 | Project isolation | open-ceiling | external: claude-mem | external | ceiling `src/memory/import.ts` :: `ponytail: claude-mem keys projects by` |
+| X02 | Project isolation | regression-covered | agent-mem: import.ts | P4 | `test/memory-phase3.test.ts` :: `claude-mem import copies the hub's notes of this project once, never model answers, PII or secrets, and never writes claude-mem` |
+| X03 | Project isolation | regression-covered | agent-mem: recall.ts | P4 | `test/memory-store.test.ts` :: `review fixes: deadlines are fixed when written, ids resolve within the project's view, and a cut-short settlement finishes at the next start`; `test/memory-store.test.ts` :: `review of #352: projects are keyed by their origin remote, or by name and directory without one`; `test/recall.test.ts` :: `worktrees use the native parent and parent/worktree aliases` |
+| X04 | Project isolation | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a replacement never narrows who sees an entry` |
+| P01 | Privacy | fixed-source | agent-hub: tasks.ts | P5 | `test/tasks.test.ts` :: `a done summary, review note or unmet item matching a PII pattern reaches neither claude-mem nor a cloud peer`; `test/tasks.test.ts` :: `the completed-change notice leaves out a summary line and file names that match a PII pattern` |
+| P02 | Privacy | fixed-source | agent-hub: adapters/local-worker.ts | P5 | `test/local-worker.test.ts` :: `hub tool capture cannot leak refused notes, withheld summaries or PII proposals`; `test/local-worker.test.ts` :: `refused hub_send text is not captured while ordinary file tools still are` |
+| P03 | Privacy | fixed-source | agent-hub: daemon.ts | P5 | `test/local-worker.test.ts` :: `daemon local board lists expose PII rows only in a PII turn, never ordinary history or answers` |
+| P04 | Privacy | regression-covered | agent-hub: tasks.ts | P5 | `test/memory-native.test.ts` :: `a note about a private path is refused before either memory sees it (review of #352)`; `test/memory-store.test.ts` :: `review of #352: notes leaving for a model are screened under the current PII policy, and a replaced promoted copy stays replaced elsewhere` |
+| P05 | Privacy | regression-covered | agent-mem: recall.ts | P4 | `test/memory-store.test.ts` :: `review of #352: notes leaving for a model are screened under the current PII policy, and a replaced promoted copy stays replaced elsewhere` |
+| P06 | Privacy | regression-covered | agent-hub: cli/memory.ts | P5 | `test/memory-store.test.ts` :: `review of #352: a note on a task never approved leaves after the fixed backstop, and the CLI screens what it prints` |
+| P07 | Privacy | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: every promotion goes through the screen: a note it keeps stays short-term, another project's waits`; `test/memory-store.test.ts` :: `review of #352: the promotion screen ignores a task key's numbers, sees the task's current paths, and a refused promote says why` |
+| P08 | Privacy | guard/design | agent-mem: sync.ts | P4 | `test/memory-sync.test.ts` :: `a public remote is refused, an unknown one warns, and a store with no remote creates nothing` |
+| P09 | Privacy | fixed-source | agent-hub: config-trust.ts | P5 | `test/config-trust.test.ts` :: `a committed config keeps the defaults for every machine-local field, logs them, and still applies the rest` |
+| I01 | Index integrity/freshness | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `an incremental index equals a rebuild from the logs, in any order, and bad lines are skipped`; `test/memory-store.test.ts` :: `review of #352: a demoted copy takes its hidden original with it, and malformed synced lines are skipped`; `test/memory-store.test.ts` :: `review of #352: promoting a replaced entry keeps it replaced, and a non-UTC at is skipped`; `test/memory-sync.test.ts` :: `review of #354: a lock a killed git left behind never hides this machine's entries, a poisoned goal line is skipped, and goals pass the PII screen` |
+| I02 | Index integrity/freshness | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a segment that shrinks rebuilds the index, and two hops pass through provenance`; `test/memory-store.test.ts` :: `review of #352: a segment rewritten in place without shrinking rebuilds the index`; `test/memory-store.test.ts` :: `review of #352: a rewrite past the first 4 KiB is caught, and mem: ids resolve` |
+| I03 | Index integrity/freshness | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a note written while the index is locked shows on the next read` |
+| I04 | Index integrity/freshness | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a note written while the index is locked shows on the next read` |
+| I05 | Index integrity/freshness | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a long-lived store reads what another process wrote, with no write of its own` |
+| I06 | Index integrity/freshness | fixed-source | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #378: deferred ${change} is indexed by the next ${anotherReader ? "other store's" : "writer's"} relevant read` |
+| I07 | Index integrity/freshness | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a read prunes what expired while the store sat idle, so the index equals a rebuild` |
+| S01 | Sync/concurrency | regression-covered | agent-mem: store.ts | P4 | `test/memory-store.test.ts` :: `review of #352: a newer entry's graph shows what it supersedes, and a fresh home gets one machine id`; `test/memory-store.test.ts` :: `review of #352: a superseded source of a settled task is kept for when its replacement goes, and a corrupt machine id fails the store` |
+| S02 | Sync/concurrency | regression-covered | agent-mem: sync.ts | P4 | `test/memory-sync.test.ts` :: `review of #354: a lock a killed git left behind never hides this machine's entries, a poisoned goal line is skipped, and goals pass the PII screen` |
+| S03 | Sync/concurrency | guard/design | agent-mem: sync.ts | P4 | `test/memory-sync.test.ts` :: `two machines sync through a private remote: each sees the other's long-term entries, short-term ones stay home, writes never conflict and a forget propagates`; `test/memory-sync.test.ts` :: `a public remote is refused, an unknown one warns, and a store with no remote creates nothing` |
+| S04 | Sync/concurrency | open-ceiling | agent-mem: store.ts | none (declared ceiling) | ceiling `src/memory/store.ts` :: `ponytail: advisory, eventually consistent through` |
+| C01 | Scale/cost/measurement | open-ceiling | agent-mem: store.ts | P6 | ceiling `src/memory/store.ts` :: `ponytail: the check and the append are not one step across processes` |
+| C02 | Scale/cost/measurement | open-ceiling | agent-mem: store.ts | P6 | ceiling `src/memory/store.ts` :: `ponytail: hashes the whole indexed prefix on every read` |
+| C03 | Scale/cost/measurement | open-ceiling | agent-mem: store.ts | P6 | ceiling `src/memory/store.ts` :: `ponytail: a few retries; a store with more writers racing on one segment` |
+| C04 | Scale/cost/measurement | open-ceiling | agent-mem: store.ts | P6 | ceiling `src/memory/store.ts` :: `ponytail: computed in memory over all rows` |
+| C05 | Scale/cost/measurement | open-ceiling | agent-mem: store.ts | P9 | ceiling `src/memory/store.ts` :: `ponytail: pruning trusts the wall clock` |
+| C06 | Scale/cost/measurement | open-ceiling | agent-mem: recall.ts | P1 | ceiling `src/memory/recall.ts` :: `ponytail: 3 characters per token` |
+| C07 | Scale/cost/measurement | open-ceiling | agent-hub: daemon.ts | P6 | ceiling `src/hub/daemon.ts` :: `ponytail: recomputed on every poll from the whole index` |
+| C08 | Scale/cost/measurement | open-measurement | agent-hub: research.ts | P10 | gap |
+
+## Gaps
+
+A gap is an absent regression for the specific failure, not an assertion that its mechanism is absent. External gaps require upstream or provider evidence; no agent-mem phase can establish them alone.
+
+- R05 (P5): The capture integration checks receipt after stop, but does not assert shutdown awaits the bounded end request before process exit. Add the regression in P5.
+- R08 (P5): Rendering tests check workflow kinds, but do not assert generated instructions interpret only presence as reference. Add the regression in P5.
+- R09 (external): No repository test reproduces observer prose instead of XML or establishes dropped-data recovery. Obtain an upstream/provider retained regression; ownership remains external.
+- R10 (external): No repository test establishes real observer allowance/provider recovery. Obtain an upstream/provider retained regression; ownership remains external.
+- R11 (external): No repository test establishes installed plugin/cache/home readiness for the external worker. Obtain an upstream/provider retained regression; ownership remains external.
+- R12 (external): No repository test reproduces the launcher compilation versus SessionStart race. Obtain an upstream/provider retained regression; ownership remains external.
+- C08 (P10): Counts/report plumbing does not encode causal adoption effectiveness, manual retry labels, or the field window. Add the regression in P10.
+
+## Table B
+
+All live legs are **unrun**. Fixture assertions and this validator cannot close the claims below. Line citations point to the unchecked live requirements in `docs/smoke.md` at the HEAD above.
+
+| id | live leg | owner | phase | status | claim blocked |
+| --- | --- | --- | --- | --- | --- |
+| L01 | Two physical Macs, private GitHub SSH remote; entries, forget, lease and conflict read back on both | person, claude records | before #258 closes | unrun | Physical cross-machine sync and conflict behavior, `docs/smoke.md:63` |
+| L02 | gh reports an actual public test remote and sync refuses it | person | before #258 closes | unrun | Actual public-remote refusal, `docs/smoke.md:64` |
+| L03 | Import the real local claude-mem with counts/skips; source DB unchanged | claude | P5 | unrun | Real import and source immutability, `docs/smoke.md:65` |
+| L04 | A reachable real model emits dashed suggestions; briefs exclude them until confirmation | claude, person looks at the dashboard | P5 | unrun | Live suggestions and evidence exclusion, `docs/smoke.md:66` |
+| L05 | Memory and Long-term tasks tabs, light/dark, phone width, browser | person | P5 | unrun | Human browser inspection, `docs/smoke.md:67` |
+| L06 | off / claude-mem / native memory arms, five repeats, plus two weeks of field records (#258 AC11) | claude runs the arms by hand | P10 | unrun | Controlled memory-arm and field effectiveness, `docs/smoke.md:68` |
+| L07 | Native Claude/Codex attach with tooling event and installed add-ons (#248) | claude | P10 | unrun | Actual installed runtime fingerprint, `docs/smoke.md:97` |
+| L08 | Interleaved randomized add-on arms for claude-mem, ponytail, ripwire, five repeats (#248 AC2/3) | claude | P10 | unrun | Controlled add-on comparisons, `docs/smoke.md:98` |
+| L09 | Two weeks of research.enabled, then the add-ons report (#248) | person enables, claude reports | P10 | unrun | Field observation window and report, `docs/smoke.md:99` |
+| L10 | Revise the add-on decisions from measured results | person | after P10 | unrun | Evidence-backed adoption decisions, `docs/smoke.md:100` |

package/docs/plans/2026-10-16-amem-p0-baseline.md

@@ -0,0 +1,110 @@
+# Agent-mem P0 baseline
+
+Issue #412, Evidence E1-E12 and P0. This snapshot records what the sources reproduce, including disagreements with the plan. The [failure registry](2026-10-16-amem-failure-registry.md) is the companion P0 annex; its retained source assertions do not certify live legs.
+
+# Capture contract
+
+- Capture date: 2026-10-16. Source HEAD: `8f59603e3637419465b548b6e6a073b5b525b164` (before the receipt-second correction). The source references below were checked at this HEAD.
+- SQLite observation and work-state cutoff: `created_at_epoch < 2026-10-16T00:00:00.000Z`, in epoch milliseconds. Each collector invocation uses one read transaction on a `{ readonly: true }` connection.
+- Native log cutoff: `at <= 2026-10-15T21:53:00.000Z`, over `log/*.jsonl` and `local/*.jsonl`. Counts are raw dated log rows, not current visibility or an index projection. A promoted copy counts as another row. `by_tier` uses the row's declared tier; ops without a tier are `other`. `segments` counts physical placement.
+- Event and recall cutoff: `at < 2026-10-15T22:35:36.000Z` (the entire receipt second). Only `events*.jsonl` and the current `hub.log` are read; missing rotated log archives are not inferred.
+- Auto-memory/Codex file counts and research-directory presence have no trustworthy historical cutoff and are current directory counts. Symlink directories are not followed. Claude `project_dirs` counts every immediate directory, while `projects_with_memory` counts directories with at least one eligible note. Codex counts regular files recursively, including non-Markdown files.
+- Fail distinctness is SHA-256 of exact UTF-8 `text`, not title or entry id. Hashes and note text are never printed. Different tier copies with identical text count once.
+- No native index, machine identity file, or vault file is opened. No model, sync, write API or subprocess is called by the collector. Errors are numeric and do not expose source paths or messages. `readable: 0` is unavailable, never zero data; `null` marks evidence outside this script's scope.
+- All paths have CLI overrides: `--claude-mem-db`, `--memory-dir`, `--project-dir`, `--claude-projects`, `--codex-memories`, `--research-dir`, `--cases`. Defaults use the home directory and the script's checkout. For this capture, `--project-dir` targeted the main agent-hub checkout, since this worktree has no runtime state. Pass `--project-dir` pointing to the runtime checkout when collecting from a worktree. In the runtime checkout, the default command reads its own state.
+- Bare `bun scripts/amem/baseline.ts` in this worktree exits 0; E4 and E5.briefs report unreadable because this worktree has no `.agenthub/state`. The explicit-project capture below reads those sources successfully. No source was unreadable from codex sandbox with that override.
+
+# Evidence table
+
+| Id | Number and unit | Cutoff | Script key or source query | Status |
+| --- | --- | --- | --- | --- |
+| E1 | 200,717 observations; 4,882,886,254 discovery tokens; 14 days: min 849, max 11,749, median 5,411, total 82,067 | SQLite cutoff above; daily interval [2026-10-02, 2026-10-16) UTC | `E1`; `count(*)`, `sum(discovery_tokens)`, and 14 daily half-open epoch ranges over observations | drifting: historical rows can later be inserted, merged or deleted; daily counts reproduced |
+| E1 | Prior receipt: 11 GB store, 7.1 GB vectors | Earlier measurement, no size cutoff retained | #412 E1; no recursive disk scan performed here | drifting; not remeasured |
+| E2 | 0 rows with relevance_count > 0; 0 with occurrence_count > 1 | SQLite cutoff | `E2`; conditional sums over observations | drifting; zero is a missing use signal, not evidence of no use |
+| E3 | 128 rows: 41 log, 87 local; 102 notes, 26 settle ops; 52 decision, 44 finding, 3 contract, 3 fail; decisions 26 approved / 24 changes requested / 2 other; long decisions 38, auto outcomes 36 | Native cutoff | `E3`; anchored first-line text regexes and declared tier | rebuildable from dated logs; all frozen native receipts reproduced |
+| E4 | One witnessed channel delivery duplicated the presence block; 15 displayed lines reportedly all auto outcomes cut mid-sentence | Original witnessed delivery, no retained machine-readable delivery receipt | #412 E4, no source in script for the duplicated block or its cause | witnessed-only; not independently reproduced |
+| E4 | 17 recall log lines, 49,135 chars total, mean 2,890.294117647059 chars | Event/recall cutoff | `E4`; timestamped `recall <peer>: N chars` lines | rebuildable from retained current log; 7-start receipt not counted by this script |
+| E5 | 3 fail note rows, 2 distinct text hashes; 11 briefs, 61 native items, 24 external capture items, 5 fails, 5 briefs with fails > 0 | Native cutoff for notes; event cutoff for briefs | `E5.notes`, `E5.briefs`; memory_brief event sums | rebuildable; frozen brief receipt reproduced |
+| E6 | 144 project keys; 132 without slash; exact agent-hub key 10,673 rows, scoped agent-hub key 28,369 rows | SQLite cutoff | `E6`; count distinct project, instr(project,'/'), exact-key conditional sums | drifting; key counts reproduce, exact-key row counts differ |
+| E7 | Prior Pi denial receipts #69 and #73 | Earlier sandbox runs | #412 E7; `E7.sandbox_receipt` is null | witnessed-only; no new Pi sandbox or graph/rebuild refusal run |
+| E8 | 165 Claude note files (excluding MEMORY.md), 217 immediate project directories, 8 with notes; 257 recursive Codex files; 3,916 work-state entries; 102 native notes | File counts at capture; SQLite cutoff for work-state; native cutoff for notes | `E8`, `E3.by_op.note` | drifting for files/SQLite; rebuildable native notes |
+| E8 | 813 vault notes, previously obtained through Obsidian MCP | Earlier #412 snapshot | #412 E8; `E8.vault` is null; vault remains MCP-only | witnessed-only for this capture; not rebuildable by this script |
+| E9 | Fresh-store single runs at N=2,000 / 20,000 / 200,000; full stdout below | New run per N, 2026-10-16 | `bun scripts/amem/scale-bench.ts N` | rebuildable workload; timings vary, no latency-distribution claim |
+| E10 | Unknown ops ignored; unknown note kinds/scopes skipped; unknown optional fields hashed but omitted on projection/promotion | Source HEAD above | `src/memory/store.ts:466` note validation, `:468` explicit projection, `:479` recognized-op branch to `:484`, `:338` promotion field list; `entryId` at `:73` | static; line references rechecked |
+| E11 | 0 research directories at configured default location | Capture time | `E11.research_directory_exists`; no study records inferred from directory absence | drifting; #412 reports the AC11/add-on arms as unrun, not independently audited here |
+| E12 | 60 cases, 8 modes; 28 regression-covered, 9 open-ceiling, 8 fixed-source, 6 historical-fixed, 5 guard/design, 3 historical-partial, 1 open-measurement | Frozen cases file hash below | `E12`; fixed public mode/status taxonomy; full mode counts below | rebuildable inventory, not proof that all cases are fixed |
+
+# Differences from #412 and frozen receipts
+
+No value was tuned to match a receipt. During the reviewer-requested stdout re-freeze, the current recursive Codex file count moved from 124 to 257; this uncut file count remains drifting. These are all mismatches or non-comparable aggregates observed in this capture; unmatched historical claims remain qualified above.
+
+| Measurement | #412 or receipt | This capture | Interpretation |
+| --- | --- | --- | --- |
+| Observations | 200,467 | 200,717 | SQLite cutoff is frozen, source rows remain mutable; cause of 250-row difference not established |
+| Discovery tokens | 4.87 B (rounded) | 4,882,886,254 (4.882886254 B) | Does not round to 4.87 B; no exact old sum retained here |
+| Recall chars mean | about 2,990 | 2,890.294117647059 | 17 line count matches; prior average not reproduced |
+| Exact agent-hub project observations | 10,661 | 10,673 | Same exact-key query with frozen cutoff; mutable source difference |
+| Scoped agent-hub project observations | 28,148 | 28,369 | Same exact-key query with frozen cutoff; mutable source difference |
+| Claude auto-memory files | 172 | 165 | Current immediate memory/*.md files excluding MEMORY.md |
+| Claude project count | 37 projects | 217 immediate directories; 8 with eligible notes | Old inclusion rule not retained, so neither count is claimed comparable |
+| Codex memory files | 7 | 257 recursive regular files | Old inclusion rule not retained; current definition includes nested and non-Markdown files |
+| Work-state entries | 3,888 | 3,916 | Frozen created_at cutoff, mutable source |
+| 20K open / search / 2-hop ms | 347 / 74 / 50 | 875 / 244 / 149 | Different environment and single samples; no regression conclusion |
+| 200K open / search / 2-hop ms | 3,906 / 835 / 506 | 12,877 / 2,609 / 1,495 | Different environment and single samples; no regression conclusion |
+| 200K index MB | 405 (rounded) | 404.9 | Rounds to the same whole-MB value |
+
+The daily 849 / 11,749 / 5,411 / 82,067 receipt, native 128 and 52 = 26 + 24 + 2 receipt, long 38 / 36 receipt, fail 3 / 2 receipt, brief 11 / 61 / 24 / 5 / 5 receipt, E2 zeros, E6 144 / 132, E8 102 native notes, and E12 60 / 8 reproduce.
+
+# Frozen collector stdout
+
+The following is the exact single stdout line, with its final LF included in the hash. Numeric errors and null placeholders are part of its schema; no note content, titles, identifiers or private project labels are exported.
+
+```json
+{"E1":{"observations":200717,"discovery_tokens":4882886254,"daily_utc":{"2026-10-02":849,"2026-10-03":6488,"2026-10-04":3406,"2026-10-05":8510,"2026-10-06":2385,"2026-10-07":4564,"2026-10-08":4837,"2026-10-09":9446,"2026-10-10":10661,"2026-10-11":11749,"2026-10-12":6707,"2026-10-13":5985,"2026-10-14":4220,"2026-10-15":2260},"days":14,"min":849,"max":11749,"median":5411,"total":82067},"E2":{"relevance_positive":0,"occurrence_repeated":0},"E3":{"rows":128,"malformed":0,"segments":{"log":41,"local":87},"by_op":{"note":102,"goal":0,"forget":0,"supersede":0,"demote":0,"settle":26,"goal_state":0,"goal_link":0,"lease":0,"lease_force":0,"suggest":0,"confirm":0,"reject":0,"unknown":0},"by_kind":{"decision":52,"finding":44,"contract":3,"fail":3},"by_tier":{"short":61,"long":41,"other":26},"decisions":{"approved":26,"changes_requested":24,"other":2},"long_decisions":38,"long_auto_outcomes":36},"E4":{"readable":1,"recalls":17,"chars_total":49135,"mean_chars":2890.294117647059},"E5":{"notes":{"fail_rows":3,"distinct_fail_text_hashes":2},"briefs":{"readable":1,"briefs":11,"native_items":61,"claude_mem_items":24,"fails":5,"with_fails":5,"malformed":0}},"E6":{"project_keys":144,"keys_without_slash":132,"agent_hub":10673,"work_dev_agent_hub":28369},"E7":{"sandbox_receipt":null},"E8":{"claude":{"readable":1,"files":165,"project_dirs":217,"projects_with_memory":8},"codex":{"readable":1,"files":257},"claude_mem":{"work_state_entries":3916},"vault":null},"E9":{"benchmark":null},"E10":{"static_code_review":null},"E11":{"readable":1,"research_directory_exists":0},"E12":{"readable":1,"cases":60,"modes":8,"by_mode":{"Truth/lifecycle":11,"Duplicate/identity":4,"Retrieval/capture":13,"Project isolation":4,"Privacy":9,"Index integrity/freshness":7,"Sync/concurrency":4,"Scale/cost/measurement":8,"other":0},"by_status":{"regression-covered":28,"open-ceiling":9,"fixed-source":8,"historical-fixed":6,"guard/design":5,"historical-partial":3,"open-measurement":1,"other":0}}}
+```
+
+# Scale runs
+
+Each N ran once in a fresh Bun process and a new temporary home/index, sequentially in the remote development container without a parallel benchmark worker pool. The original workload is unchanged, including its open → search → graph → rebuild order. "Cold" means no pre-existing derived database for the open measurement; OS page caches were not flushed. Search/graph run after opening and are not separately cold. There are no repeated samples or p95 values. `logMB` and `indexMB` use decimal MB. Only synthetic temporary data was written.
+
+Environment: Linux remote development container, Bun 1.4.2. The configured container allowance is 16 CPUs / 32 GB; the script is single-process with no worker pool. No benchmark worker concurrency was added. These runs cannot be compared as a speed regression against the original host's one-shot receipts.
+
+```json
+{"N":2000,"logMB":2.6,"indexMB":4.1,"openMs":91,"searchMs":23,"hits":50,"graph2Ms":15,"graphNodes":22,"rebuildMs":67}
+{"N":20000,"logMB":26.3,"indexMB":40.4,"openMs":875,"searchMs":244,"hits":50,"graph2Ms":149,"graphNodes":97,"rebuildMs":981}
+{"N":200000,"logMB":263.6,"indexMB":404.9,"openMs":12877,"searchMs":2609,"hits":50,"graph2Ms":1495,"graphNodes":200,"rebuildMs":16027}
+```
+
+# Digests
+
+| Artifact | SHA-256 |
+| --- | --- |
+| Collector stdout (including LF) | `2af1390b5d900726c0909b6ab817f1d605bacb855a84dcf51acf518a2a3319e6` |
+| `scripts/amem/baseline.ts` | `cdd0d263386dd9cc8960a4a95823122fbe3c1a77eec0121ce45960065d15f626` |
+| `docs/plans/amem-cases.json` | `1f20f6885f0e9437e88bda427499f43eb97f8e0691f615cfba28b97b11aa92a4` |
+| `scripts/amem/scale-bench.ts` | `6d8a151e649097898394c59d6939abe1408c15785d8eaa875ea74e82588d8f55` |
+| Three benchmark stdout lines (including LFs) | `d3f0432d1e78abf8701b21d7f3fbf95732b257aca36e83b3daa6a33f0299e045` |
+
+To verify the stdout digest, extract the JSON block exactly with its final LF and hash its bytes. Rerunning the collector can drift even with the same cutoff, so a later differing stdout hash is not automatically script drift.
+
+# Verification
+
+- Count-only fixture: 24 assertions plus missing-store and invalid-argument checks passed. It covered inclusive native and exclusive end-of-second event boundaries, strict SQLite cutoff, duplicate fail text across tiers, MEMORY.md exclusion, recursive file counting, no sensitive fixture strings in output, and byte/file-set equality of fixture inputs before and after collection. The ad hoc fixture lived outside the repo and is not a retained regression.
+- Explicit-project collector and bare-default collector both exited 0. The bare-default worktree-state limitation is documented above.
+- `bun x tsc --noEmit`: passed in the remote container after frozen-lockfile install.
+- Registry validator passed for all 60 rows; a separate ad hoc negative fixture confirmed rejection of duplicate/missing case ids, an unlisted gap, a missing ponytail marker, a missing literal test declaration, and invalid owner/phase fields.
+- Initial local `scripts/check.sh` invocation (before the receipt-second correction): 2,791 pass / 4 fail, exit 1. The invocation PATH omitted `/usr/sbin`, making `lsof` unavailable to benchmark cwd/restoration checks. No source or assertions were changed to resolve those failures. Corrected-PATH focused verification passed: 63 pass / 0 fail across the three affected benchmark files. Subsequent full-gate attempts were deferred by admission before execution and are not test runs.
+- Final P0 gate, reviewer decision 2026-10-16: the PR CI runs `scripts/check.sh` at the exact PR head on both `ubuntu-latest` and `macos-latest`, as verified in `.github/workflows/check.yml`. Both platform gates must finish with `check: OK`, and required CI (including seeded guards) must be green before reviewer approval. CI has not run at this handoff; no green CI or successful local full gate is claimed.
+- No further local full-gate retries: the person's live remote desktop session holds admission while connected. The reviewer owns pushing the branch, opening the PR and approving only after green CI. This handoff submits the implementation for review, not a completed P0 acceptance claim.
+
+Focused check receipts:
+
+```text
+baseline fixture: OK (24 assertions; missing-store and invalid-argument checks; source bytes and file set unchanged)
+check-registry: OK (60 cases, 8 modes; gaps: R05, R08, R09, R10, R11, R12, C08)
+63 pass
+0 fail
+281 expect() calls
+Ran 63 tests across 3 files. [13.59s]
+```
+- Live accounts, two physical Macs, browser inspection, model suggestions and research arms were not run. The annex keeps all ten live legs unrun.

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.