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.mdindex 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.mdindex 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 afake 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 sentover HTTP and claimed through the native CLI. Every run keeps logs and a JSONreport in the printed artifact directory, and failed browser cases also keep ascreenshot.@@ -58,8 +58,8 @@ states, source navigation, on-page recall and mobile overflow. Rust regressionsin `contextual.rs`, `live_token_usage.rs`, `session_usage.rs` and the hooksrouter 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 isreorganized, and a fault that was not injected fails the campaign. Assertionsstay 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.