Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs: polish PR 23 prose with humanizer

Aldo Junior0ba37d67c719
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index c505d83f..a28aff9e 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -91,7 +91,7 @@ the legitimate restricted-project control and the failed-query cases.
| 8d | Messaging: an inferred scope never changes a queue; a read names it (#854) | `scope.rs` `ScopeSource::is_inferred`; `ai-memory-mcp/src/server.rs` `refuse_inferred_message_scope`, called by `memory_message_pop` and `memory_message_cancel` (mailbox scope) and `memory_message_send` (sender scope) before admission or any writer call, so a `shared_slot`/`startup_seed`/`default`/`default_after_mismatch` scope is refused with nothing claimed, cancelled, or delivered; `inferred_scope_hint` on every inferred `memory_message_list` (inbox and outbox, empty or not); the SessionStart notice (`ai-memory-hooks/src/router.rs` `render_inbox_notice`) and `memory_briefing` `scope` name the inbox from server-side names only | `agent_messages_scope.rs` `unscoped_pop_from_the_shared_slot_is_refused_and_claims_nothing`, `unscoped_cancel_from_the_shared_slot_is_refused_and_the_outbox_survives`, `unscoped_send_from_the_shared_slot_is_refused_and_explicit_sender_is_stamped` (each with the shared slot on another project; session-bound and explicit callers as controls; each fails with the guard removed), `unscoped_list_names_the_mailbox_it_read_even_when_not_empty`; `agent_messages_briefing.rs` `no_scope_pop_is_refused_and_the_briefing_names_the_inbox_to_pop`, `no_scope_inbox_list_that_misses_the_mail_names_the_inferred_scope`; router `session_start_notice_surfaces_pending_mail_without_consuming_it` (names the inbox, carries no message text) | STRONG |
| 8e | Messaging: admission is the same for MCP and admin sends (#756) | `ai-memory-mcp/src/admin.rs` `handle_send_message` runs `Wiki::authorize_operation(.., AdmissionOp::MessageSend, ..)` at the recipient scope before `insert_message` (a refusal is 403 and stores nothing) and calls `notify_operation_observers` only after a successful commit; skipping webhooks needs `Capability::SkipAdmissionChain` (`skip_webhooks_for_admin_request`); the MCP path is `server.rs` `memory_message_send` | `admin.rs` `admin_message_send_reject_leaves_inbox_empty` (a rejecting webhook gets 403 and an empty inbox; fails with the admission call removed), controls `admin_message_send_observer_sees_commit_without_blocking_response` and `admin_message_send_full_inbox_does_not_notify_observer` | STRONG |
| 8f | Messaging: the web mailbox shows a restricted sender's name and a card's count only to a reader of that repository; it never consumes mail | `ai-memory-store/src/reader.rs` `list_inbox_with_senders` (`readable_repository_predicate("sp.id", viewer)` on the sender join, so the name is `NULL` for an unreadable sender) and `pending_inbox_counts` (`readable_repository_predicate("p.id", viewer)`); `ai-memory-web/src/routes/project.rs` `mailbox` is `list`-only, no pop/cancel route exists, and `mailbox_scope` matches the URL's exact project name (as `list_pages` does), so an alias never shows another project's mail | `routes.rs` `web_mailbox_hides_restricted_sender_names_and_cards` (a granted reader of the recipient is shown "a project you cannot read", the restricted sender's name and card never reach the grid, alice as the control; fails with either predicate removed), `web_mailbox_lists_only_this_projects_inbox_and_never_consumes_it` (sender and bystander pages show nothing of the recipient's mail, a POST is 405 and the message is still pending, the body is HTML-escaped), `web_mailbox_does_not_follow_a_project_alias` (a legacy key that resolves to `acme-api` shows none of its mail on `/w/default/api`; `acme-api` itself is the control) | STRONG |
-| 8h | Per-response usage stays scoped to project/session/owner and cannot be inflated by replay or reduced by partial reports | `ai-memory-store/src/reader.rs` `token_usage_report_page` applies the resolved project/session, `OwnerFilter`, search and signals before ordering/pagination; summary totals retain the full authorized scope; `ops.rs` `upsert_token_calls` keys native ids by session and merges monotonic counters in the writer transaction | Hooks `live_token_calls_update_open_sessions_without_an_end_event` attempts a foreign workspace/project and owner with an authorized control; web `operations_agent_aggregates_and_drilldowns_apply_ownership_before_totals`; hooks `live_token_calls_scrub_private_labels_before_truncating` refuses private/malformed ids and tests a secret crossing the model-label size bound with a public control; store `live_token_usage.rs` checks replayed/partial row and aggregate consistency and reused native ids across sessions, harnesses and projects; the Rust mutation campaign requires lowered response counters and wrong Codex cache accounting to fail `token_call_queries_search_and_order_before_pagination_with_scope_and_owner_guards` checks a tiny newest response beyond fifty larger ones, search, pages, foreign session and owner isolation with root controls; mutation probes remove the owner/search predicates and require assertion failures. CLI cursor tests cover 300 responses, byte windows, incomplete records and enqueue failure; the native hook and cursor mutation probes require failures if progress resets or advances before enqueue. Browser `capture-backlog`, `call-history` and `session-live-usage` exercise native capture through delivery, full-history queries and live session updates. | STRONG |
+| 8h | Per-response usage stays scoped to project/session/owner and cannot be inflated by replay or reduced by partial reports | `ai-memory-store/src/reader.rs` `token_usage_report_page` applies the resolved project/session, `OwnerFilter`, search and signals before ordering/pagination; summary totals retain the full authorized scope; `ops.rs` `upsert_token_calls` keys native ids by session and merges monotonic counters in the writer transaction | Hooks `live_token_calls_update_open_sessions_without_an_end_event` attempts a foreign workspace/project and owner with an authorized control; web `operations_agent_aggregates_and_drilldowns_apply_ownership_before_totals`; hooks `live_token_calls_scrub_private_labels_before_truncating` refuses private/malformed ids and tests a secret crossing the model-label size bound with a public control; store `live_token_usage.rs` checks replayed/partial row and aggregate consistency and reused native ids across sessions, harnesses and projects; the Rust mutation campaign requires lowered response counters and wrong Codex cache accounting to fail their regression tests. `token_call_queries_search_and_order_before_pagination_with_scope_and_owner_guards` checks a tiny newest response beyond fifty larger ones, search, pages, foreign session and owner isolation with root controls; mutation probes remove the owner/search predicates and require assertion failures. CLI cursor tests cover 300 responses, byte windows, incomplete records and enqueue failure; the native hook and cursor mutation probes require failures if progress resets or advances before enqueue. Browser `capture-backlog`, `call-history` and `session-live-usage` exercise native capture through delivery, full-history queries and live session updates. | STRONG |
| 8i | Live sidebar notifications and browser mailbox context hide restricted project names/counts; message sends preserve write authorization on both coordinates, sanitization and admission; directed mail can only be claimed by its harness | `ai-memory-web/src/routes/inbox.rs` derives queue context from viewer-filtered projects and grouped pending counts, honors explicit scope and refuses partial/foreign scope; it uses `Capability::NormalWrite` and guarded source/target scope lookups; `Wiki::send_agent_message` sanitizes and admits before the writer; `ops.rs` checks `to_agent` in selection and the atomic claim | `notifications.rs` uses viewer-filtered grouped counts, returns at most five project names without message content and disables caching; state-filtered history retains both coordinate guards before pagination, and received mail defaults to pending. `operations_notifications_are_read_only_and_hide_restricted_projects` attempts disclosure with root/read controls and tests non-consumption; the mutation gate removes its viewer filter and requires failure. Browser `notifications` checks anonymous refusal, live appearance/collection, correct project links and clearing stale data on a 403. `operations.rs` `operations_inbox_queue_context_hides_foreign_projects_and_preserves_mail` attempts restricted-project disclosure and explicit/partial-scope access with legitimate read/root controls; the core mutation gate removes the project visibility filter and requires failure. Browser `mailbox-context` exercises same-name projects in different workspaces, navigation, responsive links and non-consuming reads. `operations.rs` tests anonymous/read-only refusal with write/root controls, write grants on both coordinates, sanitizer/admission refusals and explicit cross-workspace delivery; `agent_messages.rs` `addressed_messages_are_claimed_once_only_by_the_selected_harness`; real HTTP/Chromium `web_dashboard_browser.mjs` `delivery` verifies legacy GET-only auth, cleared one-request credentials, escaped text, wrong-harness refusal and claim-once; `check-dashboard-core-mutations.py` removes harness checks and requires the claim test to fail | STRONG |
| 9 | Scope resolution fail-closed | `ai-memory-store/src/scope.rs` no-create `lookup_existing_*`; identity-aware lookup accepts exact/canonical/v2-basename keys only when they deduplicate to one UUID; `ops.rs` `resolve_project_name_for_write` performs write authorization, optional name-only promotion, and audit in one writer transaction; create only via `create_explicit_scope`; `ops.rs` `get_or_create_project_as` — the capture and managed-run creator path — consults the same coordinate lookup before inserting, so a name a promoted project still answers to (its `legacy_name` or `canonical_name`) reuses that row, an ambiguous name is refused, and no twin is minted under a key the read path already resolves (the lookup is skipped only while the schema predates V76, via `project_coordinates::supports_coordinates`). The admin destructive project routes (`admin.rs` `resolve_target_for_admin`, used by `purge-project` / `rename-project` / `move-project`) accept a bare `project_id` as an alternative to the name: it is parsed to a UUID (400 on a malformed one), looked up **within the workspace the request named** via `ReaderPool::project_name_by_id` (404 when it names no row there, so a real id from another workspace is refused rather than resolved), and the two spellings are mutually exclusive (both or neither is a 400). `list-projects` carries the id in each row, and inherits the same row-level visibility filter as the name, so a restricted project leaks neither. `ProjectNameAmbiguous` refuses cross-forge/multi-candidate keys before mutation; its message names each holder and the key it matched by, but a restricted holder only as "a restricted project", because the lookup runs before any caller is authorized and the project list hides restricted names from callers without a grant; an audit failure after the name UPDATE rolls the transaction back. V76's derived-key indexes bound hot lookup to exact/canonical/legacy equality probes with at most four rows. Promoting public APIs return `ResolvedWriteScope` metadata (no untraced promotion API); MCP, admin, and managed-workstream write entry points make Wiki refresh/checkpoint the committed scope manifest after promotion and surface `manifest_warning` on success or any later operation failure; pure managed-run input validation precedes promotion. A managed run whose `project` is the name its checkout's git remote derives (`PrepareManagedRunRequest.repository_identity`, accepted only through `accept_wire_identity` and only when `path_style_name` equals the requested name) resolves through `resolve_project_by_identity_for_capture` — the identity holder, else the cwd-prefix project with `$HOME` excluded, claimed or renamed only for a writer — and then `authorize_scope_for(Write)` on the writer connection, so an identity can neither redirect a differently named run nor open, claim, or create a project the caller may not write; Project manifests persist the typed full identity/source and derived keys so clean reindex restores the same UUID and lookup behavior. Also `ai-memory-hooks/src/router.rs` `workspace_override_is_rescope` — the hook router's session-sticky gate resolves a marker's `workspace` override via this same no-create `lookup_existing_workspace` (never a hand-rolled lookup) and fails closed (treats it as a rescope, disqualifying sticky) on a different or unresolvable workspace; only an override that resolves to the session's OWN workspace is not a rescope (#976) | `scope.rs` `read_resolution_table_driven`, `multi_scope_resolution_deduplicates_and_validates`, `identity_resolution.rs` `a_capture_naming_a_promoted_projects_legacy_key_reuses_it` (a capture naming the promoted project's legacy key lands in it, creates nothing and leaves the name resolvable), `a_capture_of_an_existing_exact_name_still_lands_there`, `a_capture_of_a_new_name_still_creates_its_project` (controls: the fallback runs only after the exact-name miss and still records the creator), hooks `two_api_checkouts_with_different_remotes_get_two_projects` (an identity-less capture under a key two projects claim refuses and creates nothing; a fresh folder-named capture still creates its project as the control), `a_slashed_label_reaches_only_a_project_the_caller_may_use` (a `workspace/project` label passed as the project is authorized as the pair it names and creates nothing when refused; granted control), `a_slashed_write_resolves_its_own_pair_and_never_creates`, `an_existing_slashed_project_wins_over_the_split`, no-auto-create + `unscoped_write_with_unresolvable_coordinate_errors`; `dual_key_scope.rs` `page_write_failure_after_promotion_preserves_manifest_warning`, `handoff_failure_after_promotion_preserves_manifest_warning`; `workstream.rs` `managed_run_rejects_mutually_exclusive_selection_before_promotion`, `managed_run_downstream_failure_after_promotion_preserves_manifest_warning`; `identity_resolution.rs` `canonical_and_legacy_reads_resolve_one_legacy_row_without_renaming`, `authorized_write_promotes_in_place_and_preserves_dependents_and_legacy_lookup`, `read_only_user_cannot_promote_a_legacy_name`, `canonical_target_conflict_rolls_back_the_promotion`, `audit_failure_rolls_back_promotion_and_keeps_the_writer_alive`, `exact_name_that_is_another_forges_canonical_key_fails_closed`, `an_ambiguous_name_names_its_holders_but_not_a_restricted_one` (restricted holder unnamed; open holder named as the control), `concurrent_legacy_and_canonical_resolve_or_create_converge_on_one_uuid`; admin `admin_purge.rs` `purge_project_refuses_a_real_id_from_another_workspace` (a row that really exists in another workspace answers 404 from `default` and is left intact), admin_rename/admin_move `rename_project_refuses_a_real_id_from_another_workspace` / `move_project_refuses_a_real_id_from_another_workspace` (the same for rename and move, the foreign project keeps its name and workspace, with the same id accepted from its own workspace as the control), `purge_project_still_refuses_an_ambiguous_name_by_default` (a name held by two rows -- one via its `legacy_name` -- stays a 400 and purges nothing), `purge_project_by_id_reaches_the_twin_and_leaves_the_name_holder_intact` (legitimate control: the id reaches the row the name could not, and the name-holder survives with its name), and store `list_projects_with_stats_hides_a_restricted_projects_id_from_an_ungranted_viewer` (the id is absent exactly where the name is, for an ungranted viewer, and present for the operator -- bite-checked with the visibility filter removed); `project_coordinates.rs` `shared_candidate_query_deduplicates_before_bound_and_uses_only_indexes`; wiki `promoted_identity_round_trips_through_manifest_and_clean_reindex`, `old_project_manifest_without_identity_still_reindexes`, `reindex_rejects_project_coordinate_fields_that_do_not_match_identity`; admin `write_page_surfaces_manifest_failure_after_promotion`, `bootstrap_surfaces_manifest_failure_after_promotion`, `move_project_merge_surfaces_destination_promotion_manifest_warning`, `move_session_create_surfaces_destination_promotion_manifest_warning`; `multi_session.rs` `two_operators_promote_two_clone_keys_to_one_uuid_without_moving_active_pointers`; MCP `dual_key_scope.rs`; hooks `workstream.rs` `managed_run_by_remote_identity_claims_the_folder_named_project`, `managed_run_by_remote_identity_routes_past_an_identityless_twin` (name-only control is ambiguous), `managed_run_identity_never_redirects_another_project_name`, `managed_run_by_remote_identity_refuses_a_viewer_without_write` (outsider refused with no project created; granted member admitted as the control), `managed_run_identity_never_claims_a_restricted_legacy_project` (an outsider whose cwd sits in a restricted identity-less project is refused, the identity stays unrecorded and no twin appears; fails with either the writer's claim check or the route's write check removed; a granted member claims it as the control), `managed_run_identity_routing_stays_inside_the_requested_workspace`, `concurrent_identity_runs_on_a_legacy_project_converge_on_it` (invariant #16), `managed_run_promotion_refreshes_the_scope_manifest`, `managed_run_discloses_manifest_failure_after_committed_promotion` static read/write/authz/cross-workspace/cross-forge cases; `router.rs` `workspace_override_is_rescope_only_on_a_genuine_workspace_change` (same/different/unresolvable workspace cases), `sticky_routing_keeps_the_session_project_across_a_sibling_checkout` (regression: same workspace forwarded on every event + `project_src=repo-root` from a nested checkout stays sticky), `sticky_routing_still_rescopes_when_marker_names_a_different_workspace_mid_session` (opposite direction: a genuinely different workspace still rescopes even under `sticky`) | STRONG |
| 10 | Destructive-op live-process refusal + confirm flags (invariant #9); `purge-project`'s `dry_run` always wins over `confirm` so a preview request can never become destructive; an explicitly empty or whitespace-only CLI scope flag cannot silently select the checkout | `ai-memory-cli/src/commands/process_guard.rs` `sibling_processes` + confirm flags in `reset`/`restore`/`reindex`/`uninstall --purge-data`/`purge_project`; `admin.rs` `handle_purge_project` checks `req.dry_run` unconditionally, before `req.confirm`, mirroring `reclaim-ledger-versions`; `ai-memory-cli/src/commands/mod.rs` `resolve_scope_noting_marker_project`, `resolve_scope_with_marker`, and `resolve_workspace` call `commands::refuse_empty_explicit` at the shared choke point before resolution or HTTP | `admin_purge.rs` confirm→400; `removal.rs` — injected live-sibling makes each destructive command bail before touching the data dir; `uninstall.rs` `purge_guard_refuses_a_live_sibling_before_stopping_the_service` — `uninstall --purge-data` checks for siblings (the `setup` service's own pid excepted) before it stops that service, and `purge_guard_rechecks_after_stopping_the_service` refuses when the stopped service is still alive; `admin_purge.rs` `purge_project_confirm_true_and_dry_run_true_still_only_previews` — `{"confirm": true, "dry_run": true}` deletes nothing (the regression this row now also covers); `ops.rs` `purge_project_dry_run_changes_nothing` — every project-scoped row count, the `purged_scopes` tombstone, and the `audit_log` row are identical before/after a `PurgeMode::Preview` run; `ops.rs` `purge_project_counts_collateral_damage_in_another_project` and `admin_purge.rs` `purge_project_dry_run_and_confirmed_purge_both_report_collateral_damage_in_another_project` — a purge of project P collaterally deletes an observation, and orphans a handoff's session reference, in a *different* project Q (via `sessions` cascading out of P), and both the preview and the confirmed report count it; CLI `commands::tests::resolve_scope_and_workspace_refuse_empty_and_whitespace_flags` and `tests/suite/marker_scope.rs` `restore_page_refuses_empty_scope_flags_without_sending_a_mutation` refuse empty and whitespace-only `--workspace`/`--project` with no POST; omitted, partially explicit and fully explicit scopes reach only the expected target as controls. Without the guard, the shipped binary sends the restore to the marker scope and the test fails | STRONG |
diff --git a/docs/testing-dashboard.md b/docs/testing-dashboard.md
index 2027f489..a872e7be 100644
--- a/docs/testing-dashboard.md
+++ b/docs/testing-dashboard.md
@@ -30,7 +30,7 @@ describes the test browser's system dependencies and headless shell.
The browser runner starts its own Rust server, uses synthetic projects and a
fake root token, and drives Chromium through its native debugging protocol. It
-replaces no DOM and contacts no running production server. Messages are sent
+does not modify the DOM or contact a running production server. Messages are sent
over HTTP and claimed through the native CLI. Every run keeps logs and a JSON
report in the printed artifact directory, and failed browser cases also keep a
screenshot.
@@ -58,8 +58,8 @@ states, source navigation, on-page recall and mobile overflow. Rust regressions
in `contextual.rs`, `live_token_usage.rs`, `session_usage.rs` and the hooks
router also cover foreign source IDs, private contradictions, source ownership,
root controls, redacted admin settings, transaction rollback, native cursor
-continuity, malformed gaps and sanitization before truncation. Historical
-unknown data is a required outcome and is never replaced by guessed coordinates.
+continuity, malformed gaps and sanitization before truncation. Tests require historical data with missing context to remain unknown, without
+guessed coordinates.
| Behavior | Automated regression guard |
| --- | --- |
@@ -129,8 +129,8 @@ source anchors used to inject a fault need updating when the implementation is
reorganized, and a fault that was not injected fails the campaign. Assertions
stay on the behavior above, not on a particular function body.
-These are bounded probes, not proof against every possible defect. Rust tests
-also run the existing authorization, isolation, concurrency and recovery suites.
-The browser gate covers Chromium on Linux only. It does not establish Firefox or
-Safari rendering or pixel-perfect appearance. A behavior-preserving refactor
-should pass the regression tests.
+The probes cover the deliberate faults listed above. Rust tests also run the
+existing authorization, isolation, concurrency and recovery suites. Browser
+coverage is limited to Chromium on Linux. This gate does not check Firefox,
+Safari or pixel-perfect appearance. Behavior-preserving refactors should pass
+the tests.