Skip to content

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

Rust

Merge main into release/3.2

AkitaOnRails60163a681aaa
diff --cc CHANGELOG.md
index 1cfad4f0,5f56e23a..37f39164
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -11,201 -11,91 +11,285 @@@ version in [`docs/changelog/`](docs/cha
## [Unreleased]
+### Added
+
+- Added first-party Qwen Code lifecycle and MCP support. `install-mcp --client
+ qwen-code` (aliases `qwen`, `qwencode`) writes a Streamable HTTP `httpUrl`
+ entry into `~/.qwen/settings.json`; a token-file install gets a stdio
+ `mcp-bridge` instead of embedding the bearer. `install-hooks --agent
+ qwen-code` merges ten Claude-shaped events (including `PostToolUseFailure`
+ and subagent start/stop) as native `ai-memory hook` commands with no script
+ bundle. `SessionStart` injects the prior handoff as
+ `hookSpecificOutput.additionalContext`; Qwen's own `SessionEnd` closes the
+ session. User-prompt capture uses Qwen's provenance-bearing
+ `submitted_prompt`, never an automated continuation in `prompt`. Capture
+ exclusions cover Qwen's Gemini-like tools. Qwen-only agent backups include
+ its settings, both documented global skill roots, `QWEN.md`, and `AGENTS.md`.
+ `setup` detects `~/.qwen`. There is no `ai-memory run qwen` adapter.
+- Added zero-LLM substring retrieval for unspaced Han, Kana, and Hangul text.
+ Pages and observations gain transactionally maintained derived unigram/bigram
+ FTS indexes; existing unicode61 search and ranking remain unchanged for
+ Latin-only queries, while CJK matches participate in project, scoped,
+ global, temporal, raw-observation, and observation-evidence retrieval.
+ Upgraded stores backfill missing derived rows before accepting traffic, and
+ compaction rebuilds the auxiliary indexes with the existing FTS set.
+ ([#1433](https://github.com/akitaonrails/ai-memory/issues/1433))
+- Added a first-party Hermes Agent lifecycle and an `install-mcp --client
+ hermes` client. The `hooks:` block `install-hooks --agent hermes` prints now
+ also wires `on_session_start`, `pre_llm_call` (the prompt, never the
+ conversation history), `on_session_end` as a turn boundary and
+ `on_session_finalize` as the session end, and each primary-session
+ `pre_llm_call` checks for a pending handoff and brings it into that turn as
+ `{"context": ...}`. This includes a resumed native Hermes session. Hermes
+ events route by `TERMINAL_CWD` when it names an existing directory (in a
+ gateway, for the default profile only), and a delegated child's lifecycle
+ events are dropped. When the
+ community memory-provider plugin is installed, only the tool events are
+ printed. `install-mcp --client hermes` prints an `mcp_servers:` entry for the
+ session-less stdio bridge with no token in it, and refuses `--apply` ([#1454](https://github.com/akitaonrails/ai-memory/pull/1454)).
+- Added bounded local document extraction to the optional
+ `ai-memory-importer` companion. Its dry-run-first `document` command accepts
+ UTF-8 text/Markdown, text-layer PDF, DOCX, PPTX, XLSX, VTT, and
+ SRT; emits attributed, client-sanitized markdown; caps source, archive,
+ extracted text, PDF streams, sheets, and actual XLSX cells; and uses deterministic digest paths plus
+ conditional MCP writes for idempotent reruns without overwriting an existing
+ foreign page. OCR, images, and raw audio/video remain explicitly out of
+ scope.
+- Added passive per-workload LLM telemetry to `ai-memory status --json` and
+ `GET /admin/status`. The closed workload set covers consolidation, reranking,
+ auto-improvement, bootstrap, query answers, lint, profile maintenance, dream
+ merges, and experience abstraction, with process-lifetime calls, outcomes,
+ latency buckets, coarse token estimates, and provider-reported usage where available.
+ It records no prompt or output text and does not change provider/model
+ routing; public per-workload profiles remain deferred until measurements
+ justify their configuration and authentication surface.
+- Added structured pre-rank filters to `memory_query`: case-insensitive
+ `kind` and exact-array `tag`, typed `tier`, and literal `path_prefix`.
+ Filters apply consistently to project/scopes hybrid streams, cross-project
+ global FTS, `as_of` history, supplemental profile hits, and `pin_first`.
+ Filtered misses omit raw observations because those rows carry no page
+ metadata.
+- Added a read-only managed-workstream operations page at
+ `/web/workstreams`. On multi-user servers it is root-only; single-operator
+ installs retain their existing admin access. The bounded overview orders
+ live and interrupted work first and derives `active`, `interrupted`,
+ `completed`, and `empty` only from trusted run lifecycle fields and imported
+ event counts. It exposes no checkout paths, repository fingerprints, lease
+ owners, native session ids, source metadata, or transcript content, and it
+ does not broaden checkout-local `resume` discovery.
+- Added `ai-memory recent` and `GET /admin/recent` to list the most recently
+ updated wiki pages, newest first. The listing is scoped to the current
+ project by default (cwd / marker, or `--workspace`/`--project`); `--global`
+ covers every project and labels each hit with its workspace and project.
+ Each hit carries an RFC 3339 `updated_at` instead of an FTS rank. The admin
+ route is root-only on a multi-user server, the same as `/admin/search`.
+ ([#1379](https://github.com/akitaonrails/ai-memory/pull/1379))
+- Added an explicit `serve --allow-insecure-human-auth` (or
+ `AI_MEMORY_ALLOW_INSECURE_HUMAN_AUTH=true`) escape hatch for operators who
+ knowingly run password login over plain HTTP on a private LAN.
+ It is off by default, does not bypass the separate unauthenticated-exposure
+ guard, and prints an unconditional warning that passwords, API credentials,
+ session cookies, and memory data cross the network unencrypted. (#1383)
+- Added first-party Cline CLI lifecycle and MCP support. `install-hooks
+ --agent cline --apply` writes Cline's nine supported event files globally or
+ per project, refuses user-owned and symlinked targets, and keeps embedded
+ bearer credentials owner-only. `install-mcp --client cline --apply` writes
+ Cline's top-level transport fields and explicitly selects Streamable HTTP.
+ Detached start hooks recover handoffs through MCP; yolo mode disables hooks.
+ Also added `install-mcp --client freebuff --apply`, which registers the
+ sessionless stdio bridge in `~/.agents/mcp.json` without starting another
+ ai-memory server. (#1335)
+- Added `[ingest] drop_events` (env `AI_MEMORY_INGEST__DROP_EVENTS`), an
+ opt-in list of hook event kinds the server drops before storing them, next
+ to the existing `drop_tool_use_id_prefixes` and `drop_tool_names`. A dropped
+ event gets the same 202, `dropped_by_policy` metric and log as the other
+ policy drops, before the rate limiter, the ingest semaphore and the
+ sanitizer. Subagent classification precedes every id, name, and kind matcher,
+ so a matching marked event still seeds tracking for its unmarked tail. The
+ default drops nothing. `Config::load` checks each value
+ against the typed event kind and rejects unknown kinds and `session-start`
+ and `session-end`, which open and close sessions. The motivating case is
+ `pre-tool-use`: in one production store about 87% of those observations had
+ an empty body, and each pairs with a `post-tool-use` that carries the
+ content. With `pre-tool-use` dropped, a session whose only work was a tool
+ call that never finished now ends as lifecycle-only. (#1339)
+- Added opt-in `[sessions] idle_end_after_hours` (env
+ `AI_MEMORY_SESSIONS__IDLE_END_AFTER_HOURS`; default `0`, off; range
+ `1..=8760`). When it is set, the `serve` maintenance tick ends open sessions
+ with no activity for that many hours, such as a harness that crashed or a
+ terminal closed before `SessionEnd` fired. A substantive session gets its
+ `sessions/<id>.md` summary page, attributed to the session's owner, and its
+ consolidation job. A boundary-only session ends lifecycle-only and releases
+ the handoff it had accepted. The tick creates no handoff of its own and skips
+ sessions bound to an active managed run. A real `SessionEnd` or checkpoint
+ that lands while the tick runs wins, and the tick leaves that session alone.
+ `ended_at` is the time of the tick; the session's last activity goes in the
+ audit row. (#1338)
+- Added first-party DeepSeek Harness (DSH) lifecycle capture. `install-hooks
+ --agent dsh` (aliases `deepseek-harness`, `deepseek_harness`) stages the
+ new `hooks/dsh` bundle, writes a generated Claude Code `hooks.json`, and
+ prints a Cordis patch fragment that mounts DSH's official
+ `@deepseek-ai/dsh-hooks-claude-code` bridge on
+ `$DSH_HOME/profiles/<profile>/cordis.patch.yml` (the patch file itself is
+ never auto-written). DSH sessions are stored as `agent=dsh`, and its bridge
+ forwards Claude Code-shaped tool payloads, so `[capture] ignore_paths`
+ exclusions apply to its file, search and shell calls (Windows `pwsh`, POSIX
+ `bash`) like any other Claude-shaped adapter; the reserved Code Mode
+ `run_code` transport that its `headless` profile calls is treated as inline
+ program source. The bridge
+ delivers exactly seven events (no `PreCompact` or `SessionEnd`) and runs
+ `SessionStart` detached, so finished sessions close with
+ `finalize-session --agent dsh` and pending handoffs are recovered via
+ `memory_handoff_list` / `memory_handoff_accept`. (#1337)
+- Added an Antigravity skill root family. `install-skills --agent antigravity`
+ (aliases `antigravity-cli`, `agy`; also `install-instructions
+ --skills-agent antigravity`) writes the managed Agent Skills to both global
+ roots Antigravity reads, `~/.gemini/config/skills` (App and IDE) and
+ `~/.gemini/antigravity-cli/skills` (CLI), or to the workspace
+ `.agents/skills` with `--scope project`. `ai-memory setup` now uses it for
+ Antigravity, which until now got its skills only in `~/.agents/skills`, a
+ directory Antigravity does not read globally, and `uninstall --only skills`
+ sweeps both roots. MCP-driven routing refresh and `backup-agents` expose and
+ preserve the same roots, including the shared project `.agents/skills`.
+ (#1357)
+
+- Added a read-only wiki link graph in `/web`. The header **Graph** link opens
+ `/web/graph`, a server-rendered map of resolved wikilinks whose endpoints sit
+ in different projects, plus a table of those edges. Each project page links
+ to `/web/w/<workspace>/<project>/graph`, which shows that project's latest
+ unexpired pages and the resolved same-project links between them as an SVG
+ and a table. Both pages are HTML with no JavaScript.
+ `GET /api/v1/graph` now accepts `workspace` and `project` together to return
+ only edges that touch that project (passing only one of them is `400`), and
+ `GET /api/v1/workspaces/{workspace}/projects/{project}/graph` returns the
+ in-project node and edge lists. A project graph keeps at most 120 pages,
+ preferring those with the most same-project neighbours and then the most
+ recently updated; the store applies that cap before loading nodes or their
+ selected edges into the process. Expired pages stay hidden. An edge still
+ requires both ends to be readable.
+- Added Antigravity hook parity with Claude Code and Codex for the `agy` CLI,
+ the desktop App and the IDE. `install-hooks --agent antigravity-cli` now
+ wires the native `SessionStart`, which injects the handoff as an
+ `injectSteps` system message that stays in the conversation, where the
+ ephemeral message it replaces was dropped after the first turn.
+ `PreInvocation` gets its own `pre-invocation` handler: on builds without
+ `SessionStart`, the first turn's call stands in for it, once per
+ conversation. The native hook now reads each turn's prompts from the
+ conversation's own transcript (`transcriptPath`, only under
+ `~/.gemini/<app>/brain/<conversationId>/`, no symlinks out of it, 8 MiB per
+ hook and a 100 ms filesystem deadline) and records them as user prompts,
+ so summaries and handoffs carry them. A timed-out read leaves its cursor
+ untouched and retries on the next hook. A `Stop` that finished the turn
+ (`NO_TOOL_CALL` or `model_stop`) with
+ `fullyIdle: true` writes a turn checkpoint, the path OpenCode 2 uses: the
+ summary page and one handoff are refreshed and the conversation stays open,
+ so `finalize-session` is no longer needed for normal use. It remains the
+ explicit close, hands the baton over without the 10-minute quiet period,
+ queues opt-in consolidation, and skips its `history.jsonl` prompt replay
+ for a conversation whose prompts were already captured. Rerun
+ `install-hooks --agent antigravity-cli --apply` to add `SessionStart`;
+ existing native-hook installs get the prompts and checkpoints without it.
+ A turn checkpoint never ends a conversation, even a turn with no captured
+ prompt or tool call, so a handoff it claimed at start is never offered
+ again; the conversation start is claimed atomically, so a concurrent
+ `SessionStart` and first `PreInvocation` cannot both claim a handoff;
+ prompt ingest keys include the prompt's time and text, so a rewind that
+ reuses step numbers keeps its new prompts; and the transcript is opened
+ with `O_NOFOLLOW | O_NONBLOCK` and, on Linux, checked against the opened
+ descriptor's real path. (#1416)
+
+ ### Security
+ - Updated `rustls-webpki` 0.103.15 → 0.103.16 for
+ [RUSTSEC-2026-0382](https://rustsec.org/advisories/RUSTSEC-2026-0382), in
+ which certificate verification may accept distrusted intermediates, and
+ `webpki-root-certs` 1.0.9 → 1.0.10 for
+ [RUSTSEC-2026-0383](https://rustsec.org/advisories/RUSTSEC-2026-0383), whose
+ bundled roots still trusted distrusted emSign intermediates. The importer,
+ relay and wiki sync companions take the same `rustls-webpki` bump.
+
+ ### Fixed
+ - Bound native API-key hashes to their configured pepper with a persisted
+ Argon2id verifier. A restored database with existing keys now refuses to
+ serve under a different `[auth].token_pepper` instead of silently making
+ every key return 401; pepper rotation remains allowed while no keys exist.
+ A pre-verifier backup containing keys fails restore until the operator
+ supplies the original pepper and explicitly confirms it with
+ `--accept-legacy-api-key-pepper`.
+ ([#1495](https://github.com/akitaonrails/ai-memory/issues/1495))
+
+ - Defined `ai-memory backup` as an online data snapshot rather than a complete
+ host image, documented the separately protected config, root credentials and
+ raw ledgers a host move may require, and corrected the missing-token startup
+ remedy so it no longer implies the snapshot contains `auth-tokens/`.
+ ([#1494](https://github.com/akitaonrails/ai-memory/issues/1494))
+
+ - Accepted the exact CRLF migration checksums written by Windows-native
+ releases before v3.1.2 and replaced them transactionally with the current
+ LF checksums before strict migration validation. Unknown migration changes
+ still fail closed. Bare hook reinstallation also preserves the Windows
+ exec-form `--capture-assistant` opt-in instead of looking only inside the
+ command string. ([#1499](https://github.com/akitaonrails/ai-memory/issues/1499))
+
+ - Held `ai-memory run` heartbeat notices while the harness owns the terminal
+ and printed them after it exits, so a server outage no longer writes into the
+ harness TUI. Only the first and latest notices are replayed, with a count of
+ the rest. A transport outage that changes into a server-side lease rejection
+ is reported as a new state instead of being hidden as the same failure.
+ ([#1500](https://github.com/akitaonrails/ai-memory/issues/1500))
+
+ - Dropped stopwords from the quoted bag of words a search falls back to when
+ its text looks like FTS5 syntax but does not parse, such as a question
+ ending in `(prod)`. The fallback OR-joined `what`, `is`, `the` and `of`
+ with the content words; it now filters through the configured
+ `[search.fts] stopwords` list like a bare query, keeps the words the user
+ quoted, and keeps every word when all of them are stopwords.
+
+ - Corrected `docs/lifecycle-ops.md` on two points. The `move-project` merge
+ drops everything the source project owns, the same set `purge-project`
+ deletes. This includes managed workstreams, cross-project messages,
+ auto-improvement and profile-harvest state, consolidation jobs, ingest keys,
+ entities, page feedback, per-session purge tombstones and project grants as well as
+ sessions, observations and handoffs. The `400` for sending both a project
+ name and an id, or neither, applies to the admin endpoints; the CLI resolves
+ a missing project from the marker, the git remote, then the directory name.
+ ([#1493](https://github.com/akitaonrails/ai-memory/issues/1493))
+
+ - Named the install's data dir in the `mcp-bridge` entries `install-mcp`
+ writes for Claude Code and the session-less stdio bridge when the install
+ was given one (`--data-dir`, `AI_MEMORY_DATA_DIR` or `data_dir` in the
+ config), as Muse's entry and the install's hooks already did. The bridge
+ read the default data dir's config and token instead, so on a host whose
+ server uses the default data dir it authenticated with the server's root
+ bearer.
+ ([#1489](https://github.com/akitaonrails/ai-memory/issues/1489))
+
+ - Let `ai-memory mcp-bridge` send the key `install-hooks --apply --auth-token`
+ stored in `<data_dir>/auth-token` when no bearer is configured, ahead of the
+ loopback root token discovery, so a remote
+ client whose hooks hold a native API key wires the MCP bridge without
+ copying the key. `install-mcp --apply --auth-token` now stores the key there
+ for the Claude Code (`--session-aware`) and Muse bridge entries and leaves
+ it out of the harness config, where it outlived a key rotation; existing
+ entries keep working. `uninstall --only hooks` keeps the stored key while
+ such a bridge entry remains. ([#1490](https://github.com/akitaonrails/ai-memory/issues/1490))
+
+ - Kept the bridge from sending a discovered root key to a non-loopback
+ server, rejected a malformed stored user key instead of falling through to
+ root, made failed installs roll back newly stored credentials, and included
+ the absolute data dir in Claude Code's printed session-aware command as well
+ as its JSON entry.
+ ([#1490](https://github.com/akitaonrails/ai-memory/issues/1490))
+
+ ## [3.1.2] - 2026-10-20
+
### Fixed
+- Reserved local-embedding capacity for interactive search queries instead of
+ allowing concurrent page writes and backfill work to occupy every inference
+ slot. Excess queries fall back immediately to non-vector retrieval, and a
+ cancelled request retains its slot until its non-cancellable CPU inference
+ actually ends. An opt-in real-model contention probe records idle,
+ unbounded-load, and bounded-load p50/p95 query latency; hosted embedding
+ providers are unchanged.
- Reported appended and removed lines in wiki sync conflict summaries, with
an explicit end-of-file marker instead of line 0 and matching previews.
([#1477](https://github.com/akitaonrails/ai-memory/issues/1477))
diff --cc crates/ai-memory-cli/src/commands/install_mcp.rs
index 3a7f2849,dab4a105..0ef155fc
--- a/crates/ai-memory-cli/src/commands/install_mcp.rs
+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs
@@@ -143,8 -130,65 +130,71 @@@ pub(crate) fn run_with_opencode_dialect
{
route_file_token(&mut args, token_file)?;
}
+ // The bridge loads its config and token from a data dir the way any CLI
+ // call does. Muse starts stdio servers with a cleared environment (`HOME`,
+ // `PATH` and its own `MUSE_SESSION_ID`), so its bridge finds this install
- // only through an explicit `--data-dir`, as the Muse hooks do. Any other
++ // only through an explicit `--data-dir`, as the Muse hooks do. Hermes
++ // keeps only a short allowlist (`PATH`, `HOME`, `XDG_*`, ...;
++ // `_build_safe_env` in `tools/mcp_tool_config.py`), which drops
++ // `AI_MEMORY_DATA_DIR` the same way. Any other
+ // bridge needs it when this install was given a data dir: the hooks name
+ // that dir, and a bridge without it would read the default one, with its
+ // own config and bearer. Not from inside the Docker helper, whose data dir
+ // is a container path the host-side bridge cannot open.
+ let runs_bridge =
+ (args.client == McpClient::ClaudeCode && args.session_aware) || args.stdio_bridge;
+ if config.runtime_env.host_cwd().is_none()
- && (args.client == McpClient::Muse || (runs_bridge && config.data_dir_explicit))
++ && (matches!(
++ args.client,
++ McpClient::Muse | McpClient::Freebuff | McpClient::Hermes
++ ) || (runs_bridge && config.data_dir_explicit))
+ {
+ args.bridge_data_dir = Some(config.data_dir.clone());
+ }
+ // An explicit `--auth-token` for an entry that runs `mcp-bridge` goes where
+ // the hooks keep theirs, `<data_dir>/auth-token`, and the bridge reads it
+ // from there when nothing else is configured. Inline in the harness config
+ // it would sit outside the data dir's protection and outlive a rotation,
+ // the reasons #552 moved the hooks' copy. The entry then names that data
+ // dir, so the bridge reads the file the key went into. Only `--apply`
+ // stores, as with `install-hooks`: a printed snippet is the operator's to
+ // place. The key stays inline, as before, whenever the bridge would not
+ // reach it: a bearer this config is configured with would win over it, a
+ // different key already stored belongs to the hooks, the store failed, or
+ // this is the Docker helper, whose data dir the host-side bridge cannot
+ // open.
+ let bridge_carries_token = matches!(args.client, McpClient::Muse)
+ || (args.client == McpClient::ClaudeCode && args.session_aware);
+ let may_store_bridge_key = args.apply
+ && token_given
+ && bridge_carries_token
+ && config.auth.configured_bearer_token().is_none()
+ && config.runtime_env.host_cwd().is_none()
+ && same_mcp_endpoint(
+ &config.server_url,
+ args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
+ );
validate_args(&args)?;
if args.apply {
+ if may_store_bridge_key
+ && let Some(token) = args.auth_token.clone()
+ && let Some(stored) = store_bridge_key(&config.data_dir, &token)
+ {
+ args.auth_token = None;
+ args.bridge_data_dir = Some(config.data_dir.clone());
+ if let Err(error) = apply_to_config_file(&args) {
+ if stored == HookCredential::Seeded
+ && crate::config::read_hook_auth_token(&config.data_dir).as_deref()
+ == Some(token.as_str())
+ {
+ crate::config::clear_hook_auth_token(&config.data_dir).with_context(
+ || "rolling back the bridge credential after MCP config update failed",
+ )?;
+ }
+ return Err(error);
+ }
+ return Ok(());
+ }
return apply_to_config_file(&args);
}
let snippet = match args.client {
diff --cc crates/ai-memory-store/migrations/V85__sessions_dsh_agent_kind.sql
index 3afbbe80,00000000..3afbbe80
mode 100644,000000..100644
--- a/crates/ai-memory-store/migrations/V85__sessions_dsh_agent_kind.sql
+++ b/crates/ai-memory-store/migrations/V85__sessions_dsh_agent_kind.sql
diff --cc crates/ai-memory-store/migrations/V86__sessions_cline_agent_kind.sql
index 4ce9f3ee,00000000..06e641a2
mode 100644,000000..100644
--- a/crates/ai-memory-store/migrations/V86__sessions_cline_agent_kind.sql
+++ b/crates/ai-memory-store/migrations/V86__sessions_cline_agent_kind.sql
@@@ -1,72 -1,0 +1,72 @@@
- -- Expand sessions.agent_kind CHECK for Cline CLI while preserving V84's
++-- Expand sessions.agent_kind CHECK for Cline CLI while preserving V85's
+-- schema, indexes, and scope-pairing triggers.
+--
+-- `Store::open` turns foreign keys off around the migration runner (a PRAGMA
+-- inside refinery's transaction is ignored). With them on, `DROP TABLE
+-- sessions` would delete every observation, ingest key, and other row that
+-- references a session through ON DELETE CASCADE.
+
+DROP TRIGGER IF EXISTS auto_improve_scheduler_claims_session_pairing_ai;
+DROP TRIGGER IF EXISTS session_consolidation_jobs_session_pairing_ai;
+
+CREATE TABLE sessions_new (
+ id BLOB PRIMARY KEY NOT NULL,
+ workspace_id BLOB NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+ project_id BLOB NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+ agent_kind TEXT NOT NULL CHECK (agent_kind IN ('claude-code','codex','open-code','cursor','gemini-cli','claude-desktop','openclaw','antigravity-cli','omp','pi','crush','grok','zero','devin','kimi-code','kiro-cli','command-code','hermes','pool','zcode','grizzybot','copilot-cli','droid','muse','codebuddy','ibm-bob','dsh','cline','other')),
+ cwd TEXT,
+ started_at INTEGER NOT NULL,
+ ended_at INTEGER,
+ summary_page_id BLOB REFERENCES pages(id) ON DELETE SET NULL,
+ ended_observation_count INTEGER NOT NULL DEFAULT 0 CHECK (ended_observation_count >= 0),
+ actor_user TEXT
+);
+
+INSERT INTO sessions_new (
+ id, workspace_id, project_id, agent_kind, cwd, started_at, ended_at,
+ summary_page_id, ended_observation_count, actor_user
+)
+SELECT
+ id, workspace_id, project_id, agent_kind, cwd, started_at, ended_at,
+ summary_page_id, ended_observation_count, actor_user
+FROM sessions;
+
+DROP TABLE sessions;
+
+ALTER TABLE sessions_new RENAME TO sessions;
+
+CREATE INDEX idx_sessions_recent ON sessions(workspace_id, project_id, started_at DESC);
+CREATE INDEX idx_sessions_project ON sessions(project_id);
+CREATE INDEX idx_sessions_started_at ON sessions(started_at DESC);
+CREATE INDEX idx_sessions_scope_ended
+ ON sessions(workspace_id, project_id, ended_at ASC)
+ WHERE ended_at IS NOT NULL;
+CREATE INDEX idx_sessions_open_owner
+ ON sessions(workspace_id, project_id, agent_kind, actor_user)
+ WHERE ended_at IS NULL;
+
+CREATE TRIGGER sessions_ws_proj_pairing_ai
+BEFORE INSERT ON sessions
+FOR EACH ROW
+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM projects WHERE id = NEW.project_id)
+BEGIN
+ SELECT RAISE(ABORT, 'sessions.workspace_id does not match the project''s workspace');
+END;
+
+CREATE TRIGGER auto_improve_scheduler_claims_session_pairing_ai
+BEFORE INSERT ON auto_improve_scheduler_claims
+FOR EACH ROW
+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM sessions WHERE id = NEW.session_id)
+ OR NEW.project_id IS NOT (SELECT project_id FROM sessions WHERE id = NEW.session_id)
+BEGIN
+ SELECT RAISE(ABORT, 'auto_improve_scheduler_claims scope does not match the session scope');
+END;
+
+CREATE TRIGGER session_consolidation_jobs_session_pairing_ai
+BEFORE INSERT ON session_consolidation_jobs
+FOR EACH ROW
+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM sessions WHERE id = NEW.session_id)
+ OR NEW.project_id IS NOT (SELECT project_id FROM sessions WHERE id = NEW.session_id)
+BEGIN
+ SELECT RAISE(ABORT, 'session_consolidation_jobs scope does not match the session scope');
+END;
diff --cc crates/ai-memory-store/migrations/V87__cjk_search_indexes.sql
index 285d303b,00000000..285d303b
mode 100644,000000..100644
--- a/crates/ai-memory-store/migrations/V87__cjk_search_indexes.sql
+++ b/crates/ai-memory-store/migrations/V87__cjk_search_indexes.sql
diff --cc crates/ai-memory-store/migrations/V88__sessions_qwen_code_agent_kind.sql
index f6614974,00000000..7dbcf347
mode 100644,000000..100644
--- a/crates/ai-memory-store/migrations/V88__sessions_qwen_code_agent_kind.sql
+++ b/crates/ai-memory-store/migrations/V88__sessions_qwen_code_agent_kind.sql
@@@ -1,73 -1,0 +1,73 @@@
- -- Expand sessions.agent_kind CHECK for Qwen Code while preserving V85's
- -- schema, indexes, and scope-pairing triggers (V86 only added CJK search
++-- Expand sessions.agent_kind CHECK for Qwen Code while preserving V86's
++-- schema, indexes, and scope-pairing triggers (V87 only added CJK search
+-- indexes and does not rebuild sessions).
+--
+-- `Store::open` turns foreign keys off around the migration runner (a PRAGMA
+-- inside refinery's transaction is ignored). With them on, `DROP TABLE
+-- sessions` would delete every observation, ingest key, and other row that
+-- references a session through ON DELETE CASCADE.
+
+DROP TRIGGER IF EXISTS auto_improve_scheduler_claims_session_pairing_ai;
+DROP TRIGGER IF EXISTS session_consolidation_jobs_session_pairing_ai;
+
+CREATE TABLE sessions_new (
+ id BLOB PRIMARY KEY NOT NULL,
+ workspace_id BLOB NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+ project_id BLOB NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+ agent_kind TEXT NOT NULL CHECK (agent_kind IN ('claude-code','codex','open-code','cursor','gemini-cli','claude-desktop','openclaw','antigravity-cli','omp','pi','crush','grok','zero','devin','kimi-code','kiro-cli','command-code','hermes','pool','zcode','grizzybot','copilot-cli','droid','muse','codebuddy','ibm-bob','dsh','cline','qwen-code','other')),
+ cwd TEXT,
+ started_at INTEGER NOT NULL,
+ ended_at INTEGER,
+ summary_page_id BLOB REFERENCES pages(id) ON DELETE SET NULL,
+ ended_observation_count INTEGER NOT NULL DEFAULT 0 CHECK (ended_observation_count >= 0),
+ actor_user TEXT
+);
+
+INSERT INTO sessions_new (
+ id, workspace_id, project_id, agent_kind, cwd, started_at, ended_at,
+ summary_page_id, ended_observation_count, actor_user
+)
+SELECT
+ id, workspace_id, project_id, agent_kind, cwd, started_at, ended_at,
+ summary_page_id, ended_observation_count, actor_user
+FROM sessions;
+
+DROP TABLE sessions;
+
+ALTER TABLE sessions_new RENAME TO sessions;
+
+CREATE INDEX idx_sessions_recent ON sessions(workspace_id, project_id, started_at DESC);
+CREATE INDEX idx_sessions_project ON sessions(project_id);
+CREATE INDEX idx_sessions_started_at ON sessions(started_at DESC);
+CREATE INDEX idx_sessions_scope_ended
+ ON sessions(workspace_id, project_id, ended_at ASC)
+ WHERE ended_at IS NOT NULL;
+CREATE INDEX idx_sessions_open_owner
+ ON sessions(workspace_id, project_id, agent_kind, actor_user)
+ WHERE ended_at IS NULL;
+
+CREATE TRIGGER sessions_ws_proj_pairing_ai
+BEFORE INSERT ON sessions
+FOR EACH ROW
+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM projects WHERE id = NEW.project_id)
+BEGIN
+ SELECT RAISE(ABORT, 'sessions.workspace_id does not match the project''s workspace');
+END;
+
+CREATE TRIGGER auto_improve_scheduler_claims_session_pairing_ai
+BEFORE INSERT ON auto_improve_scheduler_claims
+FOR EACH ROW
+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM sessions WHERE id = NEW.session_id)
+ OR NEW.project_id IS NOT (SELECT project_id FROM sessions WHERE id = NEW.session_id)
+BEGIN
+ SELECT RAISE(ABORT, 'auto_improve_scheduler_claims scope does not match the session scope');
+END;
+
+CREATE TRIGGER session_consolidation_jobs_session_pairing_ai
+BEFORE INSERT ON session_consolidation_jobs
+FOR EACH ROW
+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM sessions WHERE id = NEW.session_id)
+ OR NEW.project_id IS NOT (SELECT project_id FROM sessions WHERE id = NEW.session_id)
+BEGIN
+ SELECT RAISE(ABORT, 'session_consolidation_jobs scope does not match the session scope');
+END;
diff --cc crates/ai-memory-store/src/api_credentials.rs
index 6b080e9c,8d16c175..cdbb48c6
--- a/crates/ai-memory-store/src/api_credentials.rs
+++ b/crates/ai-memory-store/src/api_credentials.rs
@@@ -433,7 -470,7 +470,7 @@@ mod tests
|row| row.get(0),
)
.unwrap();
- assert_eq!(version, 87, "update the pin when adding a migration");
- assert_eq!(version, 84, "update the pin when adding a migration");
++ assert_eq!(version, 88, "update the pin when adding a migration");
let cols: i64 = conn
.query_row(
"SELECT COUNT(*) FROM pragma_table_info('users') \
diff --cc crates/ai-memory-store/src/migrations.rs
index 403acba3,1dafa07a..fb0da788
--- a/crates/ai-memory-store/src/migrations.rs
+++ b/crates/ai-memory-store/src/migrations.rs
@@@ -1539,115 -1584,6 +1584,115 @@@ mod tests
0
);
for name in [
+ "idx_sessions_open_owner",
+ "sessions_ws_proj_pairing_ai",
+ "auto_improve_scheduler_claims_session_pairing_ai",
+ "session_consolidation_jobs_session_pairing_ai",
+ ] {
+ let kind = if name.starts_with("idx_") {
+ "index"
+ } else {
+ "trigger"
+ };
+ assert_eq!(schema_object_count(&conn, kind, name), 1, "missing {name}");
+ }
+ }
+
- /// V87 expands the sessions enum for Qwen Code. Existing sessions and
- /// dependent observations survive the table rebuild, while the old V86
++ /// V88 expands the sessions enum for Qwen Code. Existing sessions and
++ /// dependent observations survive the table rebuild, while the old V87
+ /// constraint rejects the new value and the migrated schema accepts it.
+ #[test]
- fn v86_to_v87_preserves_sessions_and_observations_and_accepts_qwen_code() {
++ fn v87_to_v88_preserves_sessions_and_observations_and_accepts_qwen_code() {
+ let mut conn = Connection::open_in_memory().unwrap();
- run_to(&mut conn, 86).unwrap();
++ run_to(&mut conn, 87).unwrap();
+ conn.pragma_update(None, "foreign_keys", "ON").unwrap();
+ let workspace_id = crate::ops::get_or_create_workspace(&mut conn, "default").unwrap();
+ let project_id =
+ crate::ops::get_or_create_project(&mut conn, &workspace_id, "project", None).unwrap();
+ let existing = SessionId::new();
+ conn.execute(
+ "INSERT INTO sessions \
+ (id, workspace_id, project_id, agent_kind, cwd, started_at, actor_user) \
+ VALUES (?1, ?2, ?3, 'ibm-bob', '/repo', 1, 'user:alice')",
+ params![
+ existing.as_bytes(),
+ workspace_id.as_bytes(),
+ project_id.as_bytes(),
+ ],
+ )
+ .unwrap();
+ assert!(
+ conn.execute(
+ "INSERT INTO sessions \
+ (id, workspace_id, project_id, agent_kind, started_at) \
+ VALUES (?1, ?2, ?3, 'qwen-code', 1)",
+ params![
+ SessionId::new().as_bytes(),
+ workspace_id.as_bytes(),
+ project_id.as_bytes(),
+ ],
+ )
+ .is_err(),
- "the V86 CHECK must reject qwen-code"
++ "the V87 CHECK must reject qwen-code"
+ );
+ conn.execute(
+ "INSERT INTO observations \
+ (id, session_id, workspace_id, project_id, kind, title, body, created_at) \
+ VALUES (?1, ?2, ?3, ?4, 'prompt', 'kept', 'kept body', 1)",
+ params![
+ uuid::Uuid::new_v4().as_bytes(),
+ existing.as_bytes(),
+ workspace_id.as_bytes(),
+ project_id.as_bytes(),
+ ],
+ )
+ .unwrap();
+
+ conn.pragma_update(None, "foreign_keys", "OFF").unwrap();
+ run(&mut conn).unwrap();
+ conn.pragma_update(None, "foreign_keys", "ON").unwrap();
+
+ let preserved: (String, String, Option<String>) = conn
+ .query_row(
+ "SELECT agent_kind, cwd, actor_user FROM sessions WHERE id = ?1",
+ params![existing.as_bytes()],
+ |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)),
+ )
+ .unwrap();
+ assert_eq!(
+ preserved,
+ ("ibm-bob".into(), "/repo".into(), Some("user:alice".into()))
+ );
+ let observations: i64 = conn
+ .query_row(
+ "SELECT COUNT(*) FROM observations WHERE session_id = ?1",
+ params![existing.as_bytes()],
+ |row| row.get(0),
+ )
+ .unwrap();
+ assert_eq!(observations, 1, "the session's observations survive");
+
+ crate::ops::begin_session(
+ &mut conn,
+ &NewSession {
+ occurred_at: None,
+ id: SessionId::new(),
+ workspace_id,
+ project_id,
+ agent_kind: AgentKind::QwenCode,
+ cwd: Some("/repo".into()),
+ actor_user: Some("user:alice".into()),
+ },
+ )
+ .unwrap();
+ assert_eq!(
+ conn.query_row("SELECT COUNT(*) FROM pragma_foreign_key_check", [], |row| {
+ row.get::<_, i64>(0)
+ })
+ .unwrap(),
+ 0
+ );
+ for name in [
"idx_sessions_open_owner",
"sessions_ws_proj_pairing_ai",
"auto_improve_scheduler_claims_session_pairing_ai",
diff --cc crates/ai-memory-store/src/ops.rs
index 1fed43a6,31bae2cc..5e9f222e
--- a/crates/ai-memory-store/src/ops.rs
+++ b/crates/ai-memory-store/src/ops.rs
@@@ -1582,129 -1581,6 +1582,129 @@@ fn stamped_frontmatter(mut conformed: s
Ok(serde_json::to_string(&conformed)?)
}
+/// Rows added by [`backfill_cjk_indexes`] while opening an upgraded store.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct CjkBackfillSummary {
+ pub(crate) pages: u64,
+ pub(crate) observations: u64,
+}
+
+/// Repair missing rows in the derived CJK indexes before readers start.
+///
+/// Every source row receives an auxiliary row, including Latin-only content
+/// (whose terms are empty). That makes this an idempotent anti-join instead of
+/// rescanning every Latin row at each startup. Deletes and direct content
- /// updates remove the derived row through V86 triggers, so a crash or an
++/// updates remove the derived row through V87 triggers, so a crash or an
+/// offline maintenance edit converges here on the next open.
+pub(crate) fn backfill_cjk_indexes(conn: &mut Connection) -> StoreResult<CjkBackfillSummary> {
+ type PageRow = (i64, String, String, String);
+ type ObservationRow = (i64, String, String);
+ const BATCH: i64 = 256;
+ let mut summary = CjkBackfillSummary::default();
+
+ loop {
+ let tx = conn.transaction()?;
+ let rows: Vec<PageRow> = {
+ let mut stmt = tx.prepare(
+ "SELECT p.rowid, p.title, p.body, p.path_search FROM pages p \
+ WHERE NOT EXISTS (SELECT 1 FROM pages_cjk_fts f WHERE f.rowid = p.rowid) \
+ ORDER BY p.rowid LIMIT ?1",
+ )?;
+ stmt.query_map([BATCH], |row| {
+ Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?))
+ })?
+ .collect::<Result<_, _>>()?
+ };
+ if rows.is_empty() {
+ tx.commit()?;
+ break;
+ }
+ for (rowid, title, body, path_search) in &rows {
+ index_page_cjk(&tx, *rowid, title, body, path_search)?;
+ }
+ summary.pages += rows.len() as u64;
+ tx.commit()?;
+ conn.execute_batch("PRAGMA wal_checkpoint(TRUNCATE);").ok();
+ }
+
+ loop {
+ let tx = conn.transaction()?;
+ let rows: Vec<ObservationRow> = {
+ let mut stmt = tx.prepare(
+ "SELECT o.rowid, o.title, o.body FROM observations o \
+ WHERE NOT EXISTS ( \
+ SELECT 1 FROM observations_cjk_fts f WHERE f.rowid = o.rowid \
+ ) ORDER BY o.rowid LIMIT ?1",
+ )?;
+ stmt.query_map([BATCH], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))?
+ .collect::<Result<_, _>>()?
+ };
+ if rows.is_empty() {
+ tx.commit()?;
+ break;
+ }
+ for (rowid, title, body) in &rows {
+ index_observation_cjk(&tx, *rowid, title, body)?;
+ }
+ summary.observations += rows.len() as u64;
+ tx.commit()?;
+ conn.execute_batch("PRAGMA wal_checkpoint(TRUNCATE);").ok();
+ }
+ Ok(summary)
+}
+
+fn index_page_cjk(
+ conn: &Connection,
+ rowid: i64,
+ title: &str,
+ body: &str,
+ path_search: &str,
+) -> StoreResult<()> {
+ let result = conn.execute(
+ "INSERT INTO pages_cjk_fts(rowid, title, body, path_search) VALUES (?1, ?2, ?3, ?4)",
+ params![
+ rowid,
+ cjk_index_terms(title),
+ cjk_index_terms(body),
+ cjk_index_terms(path_search)
+ ],
+ );
+ finish_cjk_index_write(result)
+}
+
+fn index_observation_cjk(
+ conn: &Connection,
+ rowid: i64,
+ title: &str,
+ body: &str,
+) -> StoreResult<()> {
+ let result = conn.execute(
+ "INSERT INTO observations_cjk_fts(rowid, title, body) VALUES (?1, ?2, ?3)",
+ params![rowid, cjk_index_terms(title), cjk_index_terms(body)],
+ );
+ finish_cjk_index_write(result)
+}
+
+fn finish_cjk_index_write(result: rusqlite::Result<usize>) -> StoreResult<()> {
+ match result {
+ Ok(_) => Ok(()),
+ Err(error) => {
+ // Historical migration tests deliberately stop at V18/V19/V33
+ // and then exercise current operation helpers against that frozen
- // schema. A real Store migrates through V86 before the writer is
++ // schema. A real Store migrates through V87 before the writer is
+ // spawned, so a missing table remains a fatal integrity error in
+ // every production build.
+ #[cfg(test)]
+ if error.to_string().contains("no such table:")
+ && error.to_string().contains("_cjk_fts")
+ {
+ return Ok(());
+ }
+ Err(error.into())
+ }
+ }
+}
+
/// What a [`backfill_entity_index`] pass did.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
pub struct EntityBackfillSummary {
diff --cc docs/mcp-install.md
index 4492f74e,f92ef74f..91912ce5
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@@ -25,10 -25,24 +25,25 @@@ Warp, Kilo Code, Goose and OpenHuman ha
> the token file at launch and forwards no session id, so the client passes
> `workspace` and `project` like any static client. Stdio entries name the
> `ai-memory` binary by its absolute path, so the client does not need it on
- > its `PATH`; the Docker wrapper keeps the bare `ai-memory`. ZCode keeps
+ > its `PATH`; the Docker wrapper keeps the bare `ai-memory`. When the install
+ > was given a data dir (`--data-dir`, `AI_MEMORY_DATA_DIR` or `data_dir` in
+ > the config), every bridge entry names it with `--data-dir`, as that
+ > install's hooks do, so the bridge reads that install's config and token
+ > rather than the default data dir's. ZCode keeps
-> HTTP entries only and is refused. Passing `--auth-token` explicitly (or
+> HTTP entries only and is refused. Hermes Agent gets the bridge entry
+> whatever the token source, so its config never holds a token. Passing `--auth-token` explicitly (or
> `AI_MEMORY_AUTH_TOKEN`) keeps the HTTP snippets below, header included.
+ > The two entries that run the bridge with an explicit key are the
+ > exception: `install-mcp --apply --auth-token <key>` for Claude Code with
+ > `--session-aware`, and for Muse, stores the key in `<data_dir>/auth-token`,
+ > the file `install-hooks --apply --auth-token` writes, and writes the entry
+ > with `--data-dir` and no key. The bridge reads that file whenever no
+ > bearer is configured, ahead of the root token it discovers on a loopback
+ > install, so a client whose hooks already hold a key needs no
+ > `--auth-token` here at all, and rotating the key with `install-hooks` also
+ > rotates the bridge's. The key stays in the entry, as before, when the
+ > config already resolves a bearer, a different key is stored, the hooks
+ > sign in with OIDC, or the snippet is only printed.
> **Transport is stateless by default.** Since v0.1.2 the HTTP transport
> answers each request independently (plain JSON, no `Mcp-Session-Id`
diff --cc docs/security-boundaries.md
index c559c3f0,d7cd6370..21f02b9b
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@@ -98,10 -93,10 +98,10 @@@ means the boundary is not built yet
| 11h | Docker-wrapper capture-policy capability (#1002) | `bin/ai-memory` routes ordinary Linux/macOS `install-hooks`, upgrade refreshes, and every `hook`/`hook-drain` invocation through the stable checksum-verified native host client, so the hook process executes the capture-policy boundary in 11b before spool/network; a hook config that calls the wrapper never runs in the helper container, and an unavailable client drops the event with exit 0 instead of falling back to it. Only an explicit `AI_MEMORY_HOOK_PLATFORM=posix|windows` retains the documented script compatibility path and its warning; `AI_MEMORY_NATIVE_BIN` may not point back to the wrapper. For a server initialized on the named volume, `bin/ai-memory` `refresh_volume_token` (run only by `install-hooks`) copies `/data/auth-tokens/default` (only when `/data/config.toml` names it) to an owner-only `native-runner/server-token` through the helper's stdout, and `use_volume_token` points the native client at that copy (the managed host commands and `mcp-bridge` only read it and never enter the container engine) with `AI_MEMORY_AUTH__BEARER_TOKEN_FILE`, so it is a file-sourced token (never rendered into a harness config) and never an argv; a refresh that reads no token from a reachable volume deletes the copy, and a successful full `uninstall --apply` deletes it after the container returns; a bind-mounted `AI_MEMORY_DATA_DIR` is read directly and an explicit `AI_MEMORY_AUTH_TOKEN` wins | `scripts/check-native-packaging.sh` `Checking host-launch wrapper routing`: a default allowlist install reaches the fake native client while a Docker executable that always fails proves no container fallback occurred; the explicit `posix` control reaches fake Docker and adds no native invocation; the self-referential native override is refused. `tests/wrapper_upgrade.sh` `lifecycle hook native host routing`: `hook --event session-start` and `hook-drain` reach the fake native client with the stdin payload while `docker`/`podman` stubs on PATH and in `AI_MEMORY_DOCKER` stay unused, and a non-executable `AI_MEMORY_NATIVE_BIN` exits 0 without reaching the engine; `Checking the wrapper hands host commands the volume's root bearer`: for `mcp-bridge`, `install-hooks` and `run` the fake native client receives the token file (mode 600, right content) and the token is absent from its argv; controls: a bind-mounted data dir and an explicit `AI_MEMORY_AUTH_TOKEN` make no copy and ask no container (bite: dropping the export fails the check); `Checking the host token copy goes with the volume's token and with uninstall`: a volume answering with no token removes the copy and hands none over, while an unreachable engine keeps it; a dry-run, `--only hooks` or failing `uninstall` keeps it and a successful `uninstall --apply` removes it (bite: without either removal the check fails); `auth_default_e2e.rs` `a_host_client_given_the_token_file_by_env_authenticates` (the native side of the handoff, with a no-variable control) | STRONG on the shipped Linux/macOS wrapper. Windows and remote/manual script installers remain explicitly outside capture-policy v1 |
| 11j | Offline recovery journal and transcript replay | `ai-memory-cli/src/commands/recovery.rs` keeps bounded locators, ordered semantic transcript digests, pre-launch cursors and persistent correlated-delivery/loss evidence in an atomic journal, refuses a symlinked data dir and any symlinked component inside it (ancestors above the data dir are trusted, so macOS `/var` → `/private/var` works), sanitizes/caps failure reasons, and bounds each replay plus the whole pass; `hook_spool` coordinates enqueue and quarantine with short filesystem locks, canonically resolves partial scope from the recorded cwd, bounds per-file reads and current global occupancy across the main spool and recovery directories, sweeps completed tombstones, and holds correlated events outside drain until replay succeeds or restores them on failure; degraded resumes use `ai-memory-workstream`'s adapter-validated delta export, whose blocking parse and baseline scans are capped by record, event-count, source-byte and serialized-byte totals; `backfill::import_exact_session` chunks by item and byte limits and requires per-item durable acknowledgements; `run.rs` journals every session launch, including explicit spool-only evidence for unsupported exporters, and journals a resumed export only after capturing its exact pre-launch cursor; `workstream.rs` `/recover/finish` retains owner/project authorization, rejects superseded runs, and validates a finished retry by durable transcript/native/cursor/exit identity without regenerating its checkpoint; validated recovery ingest keys bind session, agent, event kind and sanitized event identity until session purge | `transcript.rs` `persisted_baseline_exports_only_offline_append_and_rejects_rewrite`, parser/baseline cap and ordered-semantic digest tests; CLI `run_offline.rs` real degraded spool-only and overlap/idempotency tests; `recovery.rs` `spool_only_without_correlated_evidence_never_auto_clears`, `a_dropped_spool_event_stays_lost_on_the_next_empty_pass`, loss/time-budget tests, `symlinked_journal_and_ancestor_are_refused`, `a_symlinked_ancestor_of_the_data_dir_is_trusted`, `a_symlink_inside_a_data_dir_under_a_symlinked_ancestor_is_refused`; `hook_spool.rs` partial-scope late enqueue, completion-race, occupancy churn/active-cap, bounded-read and tombstone-sweep tests, plus interval isolation (`completed_tombstone_keeps_a_later_resume_of_the_same_session` proves a post-interval resume hook is delivered, `completing_one_recovery_interval_leaves_the_other_intervals_entries_intact` proves one interval's completion never consumes another's evidence and ambiguous entries fail closed into the main spool); `backfill.rs` `two_sequential_recovery_intervals_on_one_resumed_session_replay_exactly_once` proves the second interval's content and session-end are stored with end-of-session effects while reruns stay pure replays; `transcript.rs` `an_oversized_first_record_is_skipped_by_session_listing_caps` proves the first-record byte caps bite before allocation; store `insert_observation_ingest_dedups_on_key` rejects cross-session and changed-event preclaims; hooks `expired_run_recovery_is_owner_only_and_refuses_superseded_runs` proves changed transcript refusal and changed-checkpoint no-op | STRONG on Unix integration coverage; Unix lock opens use no-follow and atomic replacement rechecks the destination. Windows owner-only ACL/reparse and lock semantics require the PR `windows` lane |
| 11i | OpenCode executable probing and generated-config cleanup (#1097) | `ai-memory-cli/src/config.rs` captures the full process environment once in typed `RuntimeEnv`; `run.rs` overlays explicit `run --env` values with platform key semantics and uses that same effective environment for executable resolution, probing, and launch without rereading process environment; `opencode_dialect.rs` invokes only direct argv `--version`, caps output and time, and rejects malformed/future majors. Automatic launch skips only OpenCode on probe failure; explicit OpenCode fails. `install_hooks.rs` quarantines the incompatible sibling before reading its exact ownership markers, restores unowned content with an atomic no-replace link, and never deletes or overwrites a concurrent replacement; `install_mcp.rs` owns the shared dual-schema endpoint/token inference used by both installers, rejects conflicting generated V1/V2 entries before mutation, and migrates an alternate-major entry only when endpoint, generated shape, and absent-or-Authorization-only headers match, preserving custom headers and ambiguous entries; auto-wire migrates MCP before hooks infer from that exact config path and skips hook mutation when transition preflight fails | `run.rs` `automatic_opencode_probe_failure_keeps_another_harness_available`, `opencode_executable_probe_selects_v2_for_launch_and_autowire`, effective-child-environment PATH casing controls, fake V1/V2/env-derived-major/malformed/future/timeout executable tests, `setup-agent` V1/V2 no-probe integration controls; `install_hooks.rs` `opencode_plugin_cleanup_removes_only_exact_owned_incompatible_sibling`, `opencode_plugin_cleanup_preserves_a_concurrent_user_replacement`, `opencode_plugin_restore_moves_quarantine_when_destination_is_free`, `opencode_plugin_restore_preserves_an_existing_replacement`, `opencode_plugin_restore_does_not_replace_a_file_created_at_restore_window`, `opencode_plugin_cleanup_does_not_escape_custom_target_directory`; `install_mcp.rs` `opencode_install_reuses_owned_endpoint_and_token_across_major_transitions`, `opencode_install_refuses_conflicting_owned_transition_entries`, `opencode_install_does_not_infer_from_a_user_owned_transition_entry`, `opencode_mcp_migration_moves_only_owned_alternate_shape`, `opencode_mcp_migration_preserves_ambiguous_user_entry`, `opencode_mcp_migration_preserves_custom_headers`, `opencode_mcp_migration_accepts_only_historical_generated_headers` | STRONG for Unix process probes and platform-neutral ownership gates; exact Windows executable resolution remains covered by `run.rs` resolver tests and requires the PR `windows` label |
-| 11k | Server-side tool drop list (#1241) | `ai-memory-hooks/src/drop_list.rs` `IngestDropList::matches`, checked in `router.rs` `admit_hook` and the `handle_hook_batch` loop right after the client capture protocol and before the rate limiter, the ingest semaphore, the sanitizer and storage; lists from `[ingest] drop_tool_use_id_prefixes` / `drop_tool_names`, validated once in `Config::load` (at most 64 entries of 128 printable characters each). Only tool events match: a tool-call id by prefix, a tool name exactly, both read through the per-agent mapping `capture_policy::tool_payload_fields` that tool metadata uses (generic Claude-style fields for an agent without one; Factory Droid sends no tool-call id, so only its tool name can match; Meta Muse Code sends its provider call id in `tool_use_id`, and CodeBuddy Code Claude Code's `tool_use_id`, so both can). A drop answers 202 and counts as `dropped_by_policy`; the matched value is never logged | `router.rs` `the_ingest_drop_list_drops_before_any_capacity_is_spent` (with the semaphore exhausted a listed event still answers 202; control: an unlisted one gets 429) and `the_ingest_drop_list_applies_to_hook_batches` (listed items acknowledged as policy drops, the unlisted item ingested); `drop_list.rs` unit tests (prefix only at the start, names only exact, non-tool events never match, bounds refused; `each_agent_is_matched_on_its_own_tool_fields` matches OpenCode `callID`, Hermes `extra.tool_call_id`, Antigravity `toolCall.name`, Muse and CodeBuddy `tool_use_id` and CodeBuddy `tool_name`, with same-agent controls kept, and fails when only the generic fields are read). Both router tests fail with `matches` forced to `false` | STRONG. The list applies to every project on the server; it narrows what is stored and never widens access |
+| 11k | Server-side ingest drop list: tool id/name lists (#1241) and whole event kinds (`[ingest] drop_events`) | `ai-memory-hooks/src/drop_list.rs` `IngestDropList`: `matches` for the tool lists (a tool-call id by prefix, a tool name exactly) and `matches_event_kind` for the whole kinds (every `[ingest] drop_events` value parsed with the typed `HookEvent::parse`; `session-start`/`session-end` and the `other` bucket rejected), both validated once in `Config::load` (tool lists: at most 64 entries of 128 printable characters each). Checked in `router.rs` `admit_hook` and the `handle_hook_batch` loop after the subagent exclusion (`should_drop_subagent`) and before the rate limiter, ingest semaphore, sanitizer, and storage, so a marked subagent event seeds the tracking set its unmarked tail is dropped against even when its tool id, tool name, or event kind is listed. The tool lists match only tool events and are read through the per-agent mapping `capture_policy::tool_payload_fields` that tool metadata uses. A drop answers 202 and counts as `dropped_by_policy`; the matched value is never logged | tool lists: `router.rs` `the_ingest_drop_list_drops_before_any_capacity_is_spent`, `the_ingest_drop_list_applies_to_hook_batches`, `marked_tool_policy_drops_seed_subagent_tracking_before_single_ingress_matching`, and `marked_tool_policy_drops_seed_subagent_tracking_before_batch_matching` cover capacity, batch acknowledgements, id-prefix and exact-name seeding order, unmarked tails, and stored controls; `drop_list.rs` unit tests cover bounds, exact matching, and each agent's native fields. Whole kinds: `router.rs` `the_ingest_drop_events_drops_the_named_kind_and_keeps_the_rest`, `the_ingest_drop_events_drops_before_any_capacity_is_spent`, `the_ingest_drop_events_consumes_no_rate_budget`, `the_ingest_drop_events_batch_reports_per_index_outcomes_and_only_stores_the_kept`, `the_ingest_drop_events_keeps_dropping_the_unmarked_subagent_tail`, `the_ingest_drop_events_keeps_dropping_the_unmarked_subagent_tail_in_batches`, and `a_marked_event_of_a_dropped_kind_still_seeds_subagent_tracking`; `drop_list.rs` `drop_events_*` tests cover typed matching and rejected state/unknown kinds. Moving any matcher before subagent exclusion fails its single/batch tail tests; removing either batch matcher fails its batch contract | STRONG. The list applies to every project on the server; it narrows what is stored and never widens access |
| 11l | Marketplace plugin front door: a plugin-launched event gets exactly the native hook's capture policy, scope and server routing, is captured once beside settings-file hooks, and sends nothing without the binary (#1166) | `plugins/*/scripts/ai-memory-hook` (rendered from `crates/ai-memory-cli/templates/plugin/ai-memory-hook.sh` by `render_plugins.rs`) has no capture logic: it only finds the binary (an `ai_memory_bin` option is honoured only as an absolute path, so a checkout cannot plant a relative one) and runs `ai-memory hook` with `AI_MEMORY_HOOK_ORIGIN=<agent>-plugin`, `hook` first so the Docker wrapper routes it, omitting `--server-url` when the option is empty (a pre-3.0 binary's usage error, exit 2 before it reads stdin, is retried once against the default local server with a stderr hint), and without a binary drains stdin, prints `{}` (guidance on `session-start` only) and exits 0; `hook.rs` `is_dropped_plugin_copy` + `plugin_origin.rs` `drops_plugin_event` drop a plugin copy when the user `settings.json` (honouring `CLAUDE_CONFIG_DIR`) or the checkout's `.claude/settings.local.json` carries an ai-memory hook for the same event (`install_hooks::hooks_file_delivers_ai_memory_event`); a Droid-launched copy (`droid-plugin`) is checked against the one file Droid reads hooks from (`~/.factory/hooks.json`, else the `hooks` key of `~/.factory/settings.json`); a Muse-launched copy (`muse-plugin`, recognized by `MUSE_PLUGIN_ID` with `MUSE_SESSION_ID`) is checked against the `hooks` key of `${XDG_CONFIG_HOME:-~/.config}/muse/settings.json`, and its subagent events are dropped; both drop a folderless session (no `cwd`, or a Claude desktop `scratch-workspaces` cwd); Codex plugin events are never de-duplicated (an untrusted settings hook is skipped silently, so dropping could lose the event); the drift test keeps every plugin hook on the native path (no `hooks/<agent>/*.sh`, no credential in any plugin file) | CLI `tests/suite/plugins.rs` through the committed launcher and the real binary: `ignore_paths_hold_through_the_plugin` (ignored path never spooled; public-file control kept), `allowlist_mode_holds_through_the_plugin` (unmarked checkout emits nothing, prompts included; marked control captured), `marker_scope_routes_plugin_events`, `server_profiles_route_plugin_events` (profile URL and token, never the plugin's URL), `a_settings_hook_for_the_same_event_drops_the_plugin_copy` (user and project settings; unwired-event and no-settings controls), `a_droid_hook_for_the_same_event_drops_the_droid_plugin_copy` (Droid `hooks.json`; no-Droid-hook, Claude-settings-only, unwired-event and folderless controls), `a_muse_hook_for_the_same_event_drops_the_muse_plugin_copy` (Muse `settings.json`; no-Muse-hook, Claude-settings-only and unwired-event controls; subagent and folderless events dropped), `plugin_origin.rs` `muse_plugin_copy_is_dropped_when_muse_settings_hooks_deliver_the_event` (a matcher-narrowed hook does not count) and `test_plugin_launcher.sh` (an inherited `MUSE_SESSION_ID` without `MUSE_PLUGIN_ID` stays `claude-code`), `folderless_sessions_are_not_captured_through_the_plugin`, `without_a_binary_nothing_is_sent_and_the_agent_is_not_blocked`, `foreign_hosts_are_attributed_or_ignored`, `committed_plugins_match_the_renderer`, `plugin_tree_carries_no_credentials`; `plugin_origin.rs` unit tests (`codex_plugin_events_are_never_deduplicated_against_settings`, `droid_settings_hooks_count_only_while_hooks_json_is_absent`, `only_a_catch_all_matcher_suppresses_the_plugin_copy`: a settings hook narrowed by a matcher never drops the plugin copy); `hook.rs` `plugin_copy_is_dropped_only_with_the_plugin_origin`; `tests/hooks/test_plugin_launcher.sh` (a relative `ai_memory_bin` planted in the checkout is never run; PATH control); `tests/e2e/claude_plugin_smoke.py` (real `claude -p`: settings hook plus plugin give one `user-prompt`) | STRONG. Verified 2026-10-13: removing the `is_dropped_plugin_copy` guard fails the de-duplication and folderless tests (and the smoke reports `user-prompt x2`); disabling the native `Drop` disposition or the allowlist gate fails the `ignore_paths` and allowlist tests through the launcher. Not covered: tool events from a live model turn (no credential in CI), Windows Git Bash, Cowork and the desktop Code tab (see `docs/design-marketplace-plugins.md`) |
| 11m | The server never opens a filesystem path named in a hook payload | `ai-memory-hooks/src/payload.rs` `HookEnvelope::from_query_and_body` (run by `/hook` and every `/hook/batch` item) only reads the posted JSON; Antigravity step-log enrichment (`antigravity.rs` `enrich_antigravity_step_output`, which opens `<artifactDirectoryPath or transcriptPath dir>/.system_generated/steps/<stepIdx>/output.txt`) runs only client-side in `ai-memory-cli/src/commands/hook.rs` against the client's own home, and the server stores whatever `tool_response` the client sent | `router.rs` `a_hook_payload_cannot_make_the_server_read_its_own_disk` (an Antigravity `PostToolUse` batch naming a server-only directory through `artifactDirectoryPath` and through `transcriptPath`; no stored observation or file contains the server-side sentinel); `payload.rs` `envelope_parsing_never_reads_a_payload_named_antigravity_artifact` and `antigravity_post_tool_use_renders_client_enriched_output` (control: client-supplied output still rendered) | STRONG. Both adversarial tests fail with the server-side enrichment call reinstated (the sentinel file content is stored and readable through search) |
- | 12 | Network/auth posture, including auth on by default for new installs (an existing install keeps loopback no-auth until `ai-memory auth enable`) | `config.rs` loopback `DEFAULT_BIND`; `serve.rs` `validate_http_exposure`, `require_allowed_host`; `auth.rs` `require_bearer`; `serve.rs` mounts `/identity` inside the host and machine-auth gates even with web disabled; `nix/nixos-module.nix` treats only literal `127.0.0.1`/`::1` as loopback, requires exactly one secret environment source for other binds, keeps secret auth and `llm_headers` values out of the Nix store, and brackets IPv6 in `ExecStart`; new-install default: `commands/init.rs` `root_bearer_for_new_config` mints a root bearer only on a fresh data dir (no config file and no database) and only when no bearer is supplied otherwise, via `local_auth.rs` `provision_root_token` (`auth-tokens/` `0700`, file `0600`, atomic, reused when present) and records the relative `[auth].bearer_token_file`; `config.rs` `apply_bearer_token_file` reads it once (`AI_MEMORY_AUTH_TOKEN` wins, inline + file together refused, a missing or blank file leaves no bearer) and `discover_root_token` lets a packaged install's client commands use `<data_dir>/auth-tokens/default` only with no config file at the probed path, a loopback server URL and no registered `default` profile; `serve.rs` `refuse_a_missing_token_file` stops a server whose configured file holds no token; `AuthSettings::renderable_bearer_token` keeps a file-sourced token out of every renderer: `install_mcp.rs` `route_file_token` (Claude Code gets the session-aware `ai-memory mcp-bridge` entry, Codex and Prime Agent name `AI_MEMORY_AUTH_TOKEN`, every other client a `stdio_bridge_entry` that runs `mcp-bridge --no-session-id` in its documented stdio shape, Pi keeps its extension, ZCode (HTTP-only) is refused) and `mcp_bridge.rs`, which authenticates with the config-resolved bearer and connects upstream before serving stdio, so a refused token ends it with `401 Unauthorized` instead of hanging; `uninstall.rs` `mcp_entry_is_ours` / `toml_mcp_entry_targets` recognise bridge entries by `install_mcp::bridge_entry_url`; `auth_enable.rs` `rewire_clients` re-registers every client whose entry targets this server, `install_hooks.rs` (persisted to the hook credential files, never inlined, not even on the F5 persist-failure fallback), `setup_agent.rs`, `run_autowire.rs`, `setup.rs` (runs `init`, adopts the minted token in memory through `adopt_token_file`, and calls the installers with no explicit token; the rendered user unit carries none; `user_service.rs` `is_rendered_by_setup` lets `uninstall` stop and delete only a unit carrying `setup`'s identity line whose SHA-256 still matches, never a hand-written or edited one); `local_auth.rs` `seed_hook_credential` gives hooks the token through `auth-token`/`auth-header` and keeps a different stored credential; `uninstall.rs` keeps the root bearer (`server_profiles::clear_tokens` `keep`); `commands/auth_enable.rs` is the idempotent opt-in | `serve.rs` host-guard (missing→400 / forged→403), non-loopback-requires-token; `auth.rs` wrong-token 401; `serve.rs` `machine_identity_remains_authenticated_with_web_disabled_and_expired_keys` (wrong and expired keys refused, valid machine key accepted, web remains disabled); `flake.nix` `nixos-module-eval` refuses `localhost` and `0.0.0.0` without a secret source, refuses two secret sources, `settings.auth` secrets, and `settings.llm_headers`, with literal IPv4/IPv6 loopback and one-source controls; `cli/tests/suite/auth_default_e2e.rs` against the shipped binary: `a_fresh_install_requires_the_token_and_its_own_clients_still_work` (after `init`, unauthenticated `/mcp`, `/hook`, `/api/v1/projects`, `/admin/status` → 401 and `/healthz` → 200; the same requests with the token succeed; the native hook delivers with no token in its environment, `status` authenticates through config, `mcp-bridge` lists tools; the token is in neither process's `/proc/<pid>/cmdline`; after `install-hooks`, `install-mcp --apply` for every client it writes (21, by default config path under the test home), a refused ZCode install and `auth enable` twice, a scan of the whole home finds the token nowhere and a scan of the data dir finds it only in the token file and the two hook credential files), `an_existing_install_is_unchanged_until_auth_enable` (control: a pre-default install serves every route open and `status` names the fix; `auth enable` twice is idempotent, rewires Claude Code to the bridge, and after a restart the routes refuse and the hook still delivers), `a_packaged_install_with_an_external_config_wires_its_clients`, `uninstall_keeps_the_root_bearer_and_a_missing_one_stops_the_server`, `a_host_client_given_the_token_file_by_env_authenticates`; `init.rs` `a_fresh_init_mints_a_root_bearer_the_loader_reads`, `init_on_an_existing_install_does_not_turn_auth_on`, `init_with_a_supplied_bearer_mints_nothing`, `re_running_init_keeps_the_same_root_bearer`; `config.rs` `a_relative_bearer_token_file_resolves_against_the_data_dir`, `a_missing_or_blank_bearer_token_file_is_reported_not_guessed`, `the_env_token_wins_over_the_bearer_token_file`, `an_inline_bearer_and_a_bearer_token_file_together_are_refused`, `a_client_without_a_config_file_discovers_the_root_bearer`, `root_bearer_discovery_is_refused_outside_its_narrow_case` (existing config, remote URL, `default` profile, env token); `auth_default_e2e.rs` `a_session_less_bridge_serves_any_client_without_holding_the_token` (`tools/list` and a scoped `memory_query` through `mcp-bridge --no-session-id` against a fresh auth-on server, the token in neither the bridge's `/proc/<pid>/cmdline` nor its `/proc/<pid>/environ`; control: the session-aware mode still refuses to start without `CLAUDE_CODE_SESSION_ID`) and `a_bridge_without_the_token_is_refused_cleanly_not_hung` (exits promptly naming `401 Unauthorized`); `mcp_bridge.rs` `only_the_session_aware_mode_forwards_and_requires_a_session_id`, `a_session_less_upstream_config_carries_no_session_header`, `stdio_bridge_forwards_tools_and_session_header_in_both_http_modes` (control); `install_mcp.rs` `a_file_sourced_token_wires_every_client_without_entering_its_config` (every written client: no token, no header, an entry that reaches the server; ZCode refused and unwritten), `stdio_bridge_entries_follow_each_clients_documented_shape`, `inline_and_explicit_tokens_still_embed_as_before` (control); `uninstall.rs` `bridge_entries_are_recognised_by_their_upstream_url` (JSON, OpenCode array and TOML shapes; a bridge to another server and a foreign command are kept); `install_hooks.rs` `a_file_sourced_token_is_persisted_but_never_embedded`; `auth_enable.rs` `enable_twice_is_idempotent_and_leaks_the_token_into_no_harness_config` (every client pre-wired over HTTP is re-registered, ZCode reported as manual, the second run byte-identical), `enable_leaves_an_entry_for_another_server_alone`, `enable_refuses_while_a_default_profile_would_share_the_token`; `local_auth.rs` `the_root_bearer_is_owner_only`, `seeding_never_replaces_a_different_hook_credential`; `setup_e2e.rs` `setup_installs_wires_is_idempotent_and_uninstall_removes_its_unit` (one `setup --yes` in a fresh temp home: the token is in no file under the home but the token file and the two hook credential files, not in the user unit and not in `setup`'s output; the self-check's `memory_status` and a hook event authenticate through the file; `uninstall` then disables and deletes the unit once and a second `uninstall` calls nothing), `uninstall_leaves_a_unit_it_did_not_write` (adversarial: the packaged unit copied by hand is kept, no `systemctl` call); `user_service.rs` `a_foreign_or_edited_unit_is_left_alone`, `rendered_units_carry_an_identity_that_survives_only_unedited` | STRONG. Bite checks for the new-install default: with fresh-install minting disabled the fresh e2e routes answer without a token and the `init` tests fail; with `renderable_bearer_token` returning the file token, `install-mcp`, `install-hooks`, `auth enable` and the e2e scans find it in harness configs; without the `serve` refusal a server whose token file was deleted keeps running (the e2e times out on it); without the hook seeding the fresh e2e hook is refused; without `clear_tokens` `keep` uninstall deletes the root bearer; with `route_file_token` no longer choosing the stdio bridge the every-client and `auth enable` tests fail; with `auth enable` skipping the re-registration its test fails; with the session-less mode forwarding an inherited id the bridge unit test fails; without the 401 naming the refusal e2e fails; without bridge-entry recognition the uninstall test fails; with `setup` handing the token to `install-mcp` its scan finds it in `.claude.json`; with `is_rendered_by_setup` accepting any unit, the foreign-unit tests fail; with discovery removed the packaged e2e gets 401, and with each discovery guard removed the matching case of `root_bearer_discovery_is_refused_outside_its_narrow_case` fails. Residual: a hand-edited `servers.toml` that adds a `default` profile after the root bearer exists would read the root bearer as that profile's token (`server add` refuses it, `auth enable` refuses while it exists); ZCode takes only HTTP entries and is refused, so it needs a manual entry; the stdio entries for Zero, Muse Code and DeepSeek Harness follow their documented or source-level format but were not run against those clients |
+ | 12 | Network/auth posture, including auth on by default for new installs (an existing install keeps loopback no-auth until `ai-memory auth enable`) | `config.rs` loopback `DEFAULT_BIND`; `serve.rs` `validate_http_exposure`, `require_allowed_host`; `auth.rs` `require_bearer`; `serve.rs` mounts `/identity` inside the host and machine-auth gates even with web disabled; `nix/nixos-module.nix` treats only literal `127.0.0.1`/`::1` as loopback, requires exactly one secret environment source for other binds, keeps secret auth and `llm_headers` values out of the Nix store, and brackets IPv6 in `ExecStart`; new-install default: `commands/init.rs` `root_bearer_for_new_config` mints a root bearer only on a fresh data dir (no config file and no database) and only when no bearer is supplied otherwise, via `local_auth.rs` `provision_root_token` (`auth-tokens/` `0700`, file `0600`, atomic, reused when present) and records the relative `[auth].bearer_token_file`; `config.rs` `apply_bearer_token_file` reads it once (`AI_MEMORY_AUTH_TOKEN` wins, inline + file together refused, a missing or blank file leaves no bearer) and `discover_root_token` lets a packaged install's client commands use `<data_dir>/auth-tokens/default` only with no config file at the probed path, a loopback server URL and no registered `default` profile; `serve.rs` `refuse_a_missing_token_file` stops a server whose configured file holds no token; `AuthSettings::renderable_bearer_token` keeps a file-sourced token out of every renderer: `install_mcp.rs` `route_file_token` (Claude Code gets the session-aware `ai-memory mcp-bridge` entry, Codex and Prime Agent name `AI_MEMORY_AUTH_TOKEN`, every other client a `stdio_bridge_entry` that runs `mcp-bridge --no-session-id` in its documented stdio shape, Pi keeps its extension, ZCode (HTTP-only) is refused) and `mcp_bridge.rs`, which authenticates with the config-resolved bearer and connects upstream before serving stdio, so a refused token ends it with `401 Unauthorized` instead of hanging; `mcp_bridge.rs` `bridge_bearer` sends a configured bearer, else the hook key stored in `<data_dir>/auth-token`, else the discovered loopback root token (`AuthSettings::configured_bearer_token` leaves discovery out, so a server+client host never sends root over a stored user key), and the fallback is in the bridge only (`Config::load` never reads that file, so `serve` neither requires nor accepts it); `install_mcp.rs` `store_bridge_key` stores an explicit `--auth-token` there for the Claude Code and Muse bridge entries on `--apply` and writes the entry with `--data-dir` and no key, keeping the key inline when a configured bearer would win, a different key is stored, the hooks use OIDC, the store fails or the Docker helper runs; `uninstall.rs` keeps the stored key on `--only hooks` while `install_mcp::bridge_entry_remains`; `uninstall.rs` `mcp_entry_is_ours` / `toml_mcp_entry_targets` recognise bridge entries by `install_mcp::bridge_entry_url`; `auth_enable.rs` `rewire_clients` re-registers every client whose entry targets this server, `install_hooks.rs` (persisted to the hook credential files, never inlined, not even on the F5 persist-failure fallback), `setup_agent.rs`, `run_autowire.rs`, `setup.rs` (runs `init`, adopts the minted token in memory through `adopt_token_file`, and calls the installers with no explicit token; the rendered user unit carries none; `user_service.rs` `is_rendered_by_setup` lets `uninstall` stop and delete only a unit carrying `setup`'s identity line whose SHA-256 still matches, never a hand-written or edited one); `local_auth.rs` `seed_hook_credential` gives hooks the token through `auth-token`/`auth-header` and keeps a different stored credential; `uninstall.rs` keeps the root bearer (`server_profiles::clear_tokens` `keep`); `commands/auth_enable.rs` is the idempotent opt-in | `serve.rs` host-guard (missing→400 / forged→403), non-loopback-requires-token; `auth.rs` wrong-token 401; `serve.rs` `machine_identity_remains_authenticated_with_web_disabled_and_expired_keys` (wrong and expired keys refused, valid machine key accepted, web remains disabled); `flake.nix` `nixos-module-eval` refuses `localhost` and `0.0.0.0` without a secret source, refuses two secret sources, `settings.auth` secrets, and `settings.llm_headers`, with literal IPv4/IPv6 loopback and one-source controls; `cli/tests/suite/auth_default_e2e.rs` against the shipped binary: `a_fresh_install_requires_the_token_and_its_own_clients_still_work` (after `init`, unauthenticated `/mcp`, `/hook`, `/api/v1/projects`, `/admin/status` → 401 and `/healthz` → 200; the same requests with the token succeed; the native hook delivers with no token in its environment, `status` authenticates through config, `mcp-bridge` lists tools; the token is in neither process's `/proc/<pid>/cmdline`; after `install-hooks`, `install-mcp --apply` for every client it writes (21, by default config path under the test home), a refused ZCode install and `auth enable` twice, a scan of the whole home finds the token nowhere and a scan of the data dir finds it only in the token file and the two hook credential files), `an_existing_install_is_unchanged_until_auth_enable` (control: a pre-default install serves every route open and `status` names the fix; `auth enable` twice is idempotent, rewires Claude Code to the bridge, and after a restart the routes refuse and the hook still delivers), `a_packaged_install_with_an_external_config_wires_its_clients`, `uninstall_keeps_the_root_bearer_and_a_missing_one_stops_the_server`, `a_host_client_given_the_token_file_by_env_authenticates`; `init.rs` `a_fresh_init_mints_a_root_bearer_the_loader_reads`, `init_on_an_existing_install_does_not_turn_auth_on`, `init_with_a_supplied_bearer_mints_nothing`, `re_running_init_keeps_the_same_root_bearer`; `config.rs` `a_relative_bearer_token_file_resolves_against_the_data_dir`, `a_missing_or_blank_bearer_token_file_is_reported_not_guessed`, `the_env_token_wins_over_the_bearer_token_file`, `an_inline_bearer_and_a_bearer_token_file_together_are_refused`, `a_client_without_a_config_file_discovers_the_root_bearer`, `root_bearer_discovery_is_refused_outside_its_narrow_case` (existing config, remote URL, `default` profile, env token); `auth_default_e2e.rs` `a_session_less_bridge_serves_any_client_without_holding_the_token` (`tools/list` and a scoped `memory_query` through `mcp-bridge --no-session-id` against a fresh auth-on server, the token in neither the bridge's `/proc/<pid>/cmdline` nor its `/proc/<pid>/environ`; control: the session-aware mode still refuses to start without `CLAUDE_CODE_SESSION_ID`) and `a_bridge_without_the_token_is_refused_cleanly_not_hung` (exits promptly naming `401 Unauthorized`); `mcp_bridge.rs` `only_the_session_aware_mode_forwards_and_requires_a_session_id`, `a_session_less_upstream_config_carries_no_session_header`, `stdio_bridge_forwards_tools_and_session_header_in_both_http_modes` (control); `config.rs` `config_load_never_adopts_the_stored_hook_key` (adversarial: a stored hook key leaves the loaded bearer empty, so `serve` on that data dir neither requires nor accepts it; control: a `bearer_token_file` naming the same file is adopted); `mcp_bridge.rs` `bridge_bearer_puts_the_stored_hook_key_below_a_configured_bearer` (a configured bearer wins, a blank one does not), `a_stored_user_key_outranks_the_discovered_root_token` (adversarial: discoverable loopback root plus a stored key sends the stored key; control: discovery alone still sends root); `install_mcp.rs` `an_explicit_key_for_a_bridge_is_stored_instead_of_written_inline` (Claude Code and Muse entries carry no key and name the data dir, the stored pair is the hooks' format; controls keeping the key inline and storing nothing: print path, configured bearer, a different stored key, OIDC hooks, Docker helper, HTTP entry); `removal.rs` `an_explicit_bridge_key_is_stored_and_outlives_only_hooks_removal`; `install_mcp.rs` `a_file_sourced_token_wires_every_client_without_entering_its_config` (every written client: no token, no header, an entry that reaches the server; ZCode refused and unwritten), `stdio_bridge_entries_follow_each_clients_documented_shape`, `inline_and_explicit_tokens_still_embed_as_before` (control); `uninstall.rs` `bridge_entries_are_recognised_by_their_upstream_url` (JSON, OpenCode array and TOML shapes; a bridge to another server and a foreign command are kept); `install_hooks.rs` `a_file_sourced_token_is_persisted_but_never_embedded`; `auth_enable.rs` `enable_twice_is_idempotent_and_leaks_the_token_into_no_harness_config` (every client pre-wired over HTTP is re-registered, ZCode reported as manual, the second run byte-identical), `enable_leaves_an_entry_for_another_server_alone`, `enable_refuses_while_a_default_profile_would_share_the_token`; `local_auth.rs` `the_root_bearer_is_owner_only`, `seeding_never_replaces_a_different_hook_credential`; `setup_e2e.rs` `setup_installs_wires_is_idempotent_and_uninstall_removes_its_unit` (one `setup --yes` in a fresh temp home: the token is in no file under the home but the token file and the two hook credential files, not in the user unit and not in `setup`'s output; the self-check's `memory_status` and a hook event authenticate through the file; `uninstall` then disables and deletes the unit once and a second `uninstall` calls nothing), `uninstall_leaves_a_unit_it_did_not_write` (adversarial: the packaged unit copied by hand is kept, no `systemctl` call); `user_service.rs` `a_foreign_or_edited_unit_is_left_alone`, `rendered_units_carry_an_identity_that_survives_only_unedited` | STRONG. Bite checks for the new-install default: with fresh-install minting disabled the fresh e2e routes answer without a token and the `init` tests fail; with `renderable_bearer_token` returning the file token, `install-mcp`, `install-hooks`, `auth enable` and the e2e scans find it in harness configs; without the `serve` refusal a server whose token file was deleted keeps running (the e2e times out on it); without the hook seeding the fresh e2e hook is refused; without `clear_tokens` `keep` uninstall deletes the root bearer; with `route_file_token` no longer choosing the stdio bridge the every-client and `auth enable` tests fail; with `auth enable` skipping the re-registration its test fails; with the session-less mode forwarding an inherited id the bridge unit test fails; without the 401 naming the refusal e2e fails; without bridge-entry recognition the uninstall test fails; with `Config::load` adopting the stored hook key, without the bridge fallback, with discovery counted as a configured bearer, or with `install-mcp` never storing the key, the matching new test fails; with `setup` handing the token to `install-mcp` its scan finds it in `.claude.json`; with `is_rendered_by_setup` accepting any unit, the foreign-unit tests fail; with discovery removed the packaged e2e gets 401, and with each discovery guard removed the matching case of `root_bearer_discovery_is_refused_outside_its_narrow_case` fails. Residual: a hand-edited `servers.toml` that adds a `default` profile after the root bearer exists would read the root bearer as that profile's token (`server add` refuses it, `auth enable` refuses while it exists); ZCode takes only HTTP entries and is refused, so it needs a manual entry; the stdio entries for Zero, Muse Code and DeepSeek Harness follow their documented or source-level format but were not run against those clients |
| 12b | Managed-workstream provenance privacy, stable replay identity and server event namespace | `ai-memory-core/src/workstream.rs` `scrub_workstream_provenance`; `ai-memory-hooks/src/workstream.rs` `finish_run` reserved client-id check and `sanitize_events` before immutable segments, with `sanitize_events` and `append_boundary_events` scrubbing event/checkpoint/losses content *before* the 64 KiB cap so a cap-straddling secret is never cut into an unmatchable prefix (#1113); `ai-memory-store/src/workstream.rs` `finish_run` stable identity check and `stored_event`, scrubbing content with the explicitly supplied configured sanitizer before its 16 KiB store-boundary bound; no changes to the typed observation boundary | `store/tests/suite/workstream_provenance.rs` `workstream_provenance_is_bounded_scrubbed_and_idempotent_before_storage` (hostile and oversized source ids, unknown metadata, legitimate correlation, retry and distinct event ids), `workstream_provenance_legacy_reads_strip_secrets_and_unknown_metadata` (search and tail, malformed/oversized legacy JSON), `workstream_provenance_reused_event_id_retains_data_and_refuses_identity_change` (first indexed version retained, identity refusal and batch rollback), `workstream_provenance_replay_survives_sanitizer_changes` (new extra patterns and removal of a built-in-pattern allowlist exemption, with identity-refusal control), `workstream_provenance_replay_preserves_legacy_rows_above_bounds`, `workstream_provenance_finished_run_ignores_late_events`, `workstream_provenance_retry_with_marker_matching_pattern_is_idempotent`, `workstream_content_is_scrubbed_before_the_store_cap` (a credential straddling the 16 KiB store cap is redacted, not persisted as an unmatchable prefix; benign control verbatim; #1113); `hooks` `workstream_provenance_finish_scrubs_before_raw_segment_and_search` (custom sanitizer, immutable segment, SQL recovery and finished-run no-op), `workstream_provenance_client_cannot_use_server_event_ids` (reserved ids refused before raw writes, normal client event and server-generated checkpoint/loss controls), `finish_run_scrubs_event_content_before_the_byte_cap` and `finish_run_scrubs_boundary_events_before_the_byte_cap` (a credential straddling the 64 KiB event cap is redacted in the raw segment and never reaches the index; checkpoint/losses and benign controls; #1113); `cli/tests/suite/workstream_provenance.rs` (text/JSON and old server DTOs) | STRONG: privacy, stable-identity and reserved-namespace regressions fail with their guards bypassed; an isolated allowlist bypass fails on the unknown key, and bypassing the raw-id search authorization returns 200 where its test requires 403. No provenance is emitted in startup packets, and old raw segments are not rewritten |
| 12c | Browser cross-origin writes refused on an unauthenticated server (a foreign page in the operator's browser, DNS rebinding, and a LAN host where browsers send no fetch metadata) | `serve.rs` `refuse_cross_origin_browser_requests` / `is_cross_origin_browser_request`, layered on the machine (`/mcp`, `/hook*`, `/handoff`, `/workstream/*`, `/identity`) and admin (`/admin/*`) routes when auth is off: `Sec-Fetch-Site` other than `same-origin`/`none` → 403, or, without fetch metadata, an `Origin` whose authority is not the `Host` → 403; and `is_non_script_browser_request`: any `Sec-Fetch-Dest` other than `empty` (case-insensitive; non-UTF-8 refused) → 403 whatever `Sec-Fetch-Site` says, so links, images, navigations, iframes and form posts are refused even as `same-origin` or `none`. Browsers send fetch metadata over plain HTTP only to a potentially trustworthy host, so on any other `Host` (a LAN address or name in the allowlist, `0.0.0.0`, `host.docker.internal`; `is_loopback_host` admits only `localhost`, `*.localhost`, `127.0.0.0/8` and `[::1]`) `handoff_fetch_lacks_client_marker` also refuses `GET`/`HEAD /handoff` without a non-empty `X-AI-Memory-Client` header (`ai_memory_hooks::CLIENT_MARKER_HEADER`) → 403 whose body names both remedies (re-stage hooks, or set a bearer token). A page cannot add that header without a preflight these routes never answer. `/handoff` is the one state-changing `GET` on these routes; the other `GET`s are reads a foreign page cannot see the answer to, and every cross-origin `POST` carries `Origin`. Every first-party client sends the marker: the native hook (`hook_capture.rs` `post_hook`/`post_batch`/`get_handoff`), CLI subcommands (`http_client.rs` `ServerEndpoint::authenticate`), every curl in `hooks/_lib.sh`, both header tables in `hooks/lib/ai-memory-hook.ps1`, and the generated TypeScript integrations (`render_shared.rs` `ts_auth_headers_fn` plus the spool drain). Loopback hosts keep accepting a fetch without it, so hooks staged before the header existed still work on a default install, except that a request carrying any proxy forwarding header (`Forwarded`, `X-Forwarded-For`/`-Host`/`-Proto`/`-Server`/`-Port`, `X-Original-Forwarded-For`, `X-Real-IP`, `X-Client-IP`, `CF-Connecting-IP`, `True-Client-IP`, `Via`; `PROXY_HEADERS`) counts as non-loopback, since a plain-HTTP proxy can rewrite `Host` to loopback while the browser behind it sent no fetch metadata. No first-party client sends those headers. Hooks, the CLI and MCP clients send none of these headers; the web UI's same-origin `/admin/pending-writes` calls are `fetch()` (`Sec-Fetch-Dest: empty`) and pass. Behind it, axum `Json` and rmcp's `Content-Type: application/json` check refuse the preflight-free content types (`text/plain`, form-urlencoded, multipart) with 415; `require_allowed_host` (and rmcp `allowed_hosts` on `/mcp`) refuses a rebinding `Host`; machine/admin routes carry no CORS layer, so a preflight never comes back permissive. A stored wiki page viewed in the built-in web UI could otherwise turn the guard's same-origin allowance into a claim: `ai-memory-web/src/markdown.rs` `safe_image_url` / `is_safe_image_target` render as `#` any image target that is root-relative, a network path, carries a `..` segment (also percent-encoded), or, for a UI mounted at the base-path root, starts with a server route segment Every `/web` surface (built-in pages including `/web/pending`, the login page, a custom SPA and `/api/v1`) answers `X-Frame-Options: DENY` and `Content-Security-Policy: frame-ancestors 'none'` (`ai-memory-web/src/mount.rs` `deny_framing`), because a framed page's own Approve/Reject `fetch()` is same-origin and the guard rightly lets it through | `cli/tests/suite/cross_origin_e2e.rs` `browser_cross_origin_requests_cannot_write_to_an_unauthenticated_loopback_server`, against the shipped `serve`: every write route (`/hook`, `/hook/batch`, MCP `memory_write_page`/`memory_delete_page`/`memory_message_send`/`memory_handoff_accept`, `/admin/write-page`/`delete-page`/`purge-project`/`messages/send`, `/workstream/runs`) × each simple content type × modern, Origin-only and fetch-metadata-only browser shapes → 4xx; body-less `GET /handoff` (which claims the single-use baton), `POST /admin/profile/rebuild` and `POST /admin/backup` → 403; a rebinding `Host` → 403; preflights answer no `Access-Control-Allow-*`; `GET /handoff` as a same-origin `document` or `image` and as a `Sec-Fetch-Site: none` `document` → 403 with the baton still open. Then a canary scan of the whole data dir, page/project/handoff survival, and legitimate controls (JSON MCP calls, a JSON hook → 202, the web UI's same-origin `/admin/pending-writes` list and approve reach their handlers, the anonymous active-project pointer is unmoved after the refused `/handoff` fetches while the closing hook-style fetch claims the baton and moves it). `serve.rs` `cross_origin_browser_request_detection` and `non_script_browser_request_detection` (header tables) and `cross_origin_browser_guard_applies_only_without_auth` (same-origin `image` and `none` `document` refused, same-origin `empty` passes, both pass with auth on); `ai-memory-web` `markdown.rs` `neutralises_images_that_reach_server_routes` (`/handoff?…`, `/admin/backup`, `//host/…`, `../` and `%2e%2e/` traversal, root-mounted route names refused) with `preserves_relative_images` as the legitimate control. `cross_origin_e2e.rs` `handoff_fetch_on_a_lan_host_requires_the_client_marker`, against a `serve` that allowlists a LAN name and address: `GET` and `HEAD /handoff` through either without the marker, and with an empty one → 403 carrying the remedy text, with the baton still open and the active-project pointer unmoved; controls: a marked fetch through the LAN name claims the baton, and a marker-less fetch through `127.0.0.1` (a hook staged before the marker) claims the next one; then a `127.0.0.1` fetch carrying each proxy forwarding header and no marker → 403 with the baton still open, and the same fetch with the marker claims it. `serve.rs` `loopback_host_detection`, `handoff_fetch_client_marker_decision` (incl. a loopback `Host` with each proxy header, refused without the marker and admitted with it, and a named row per header so none can drop out of the list) and `handoff_client_marker_guard_on_lan_hosts_and_under_a_base_path` (also under a `--base-path` nest; inactive with auth on). Front-door parity: `hook_capture.rs` `every_native_hook_request_carries_the_client_marker` (handoff GET, hook POST, batch POST), `http_client.rs` `authenticate_no_token_sets_only_the_client_marker`, the client-marker block of `tests/hooks/test_lib.sh` (every curl branch of the GET, the POST and the drain, plus a static check that every PowerShell header table carries it and every `Invoke-WebRequest` passes one), `render_shared.rs` `assert_every_ts_request_carries_client_marker` run for OpenCode, OpenCode 2, OMP, Pi and OpenClaw, `external_capture_ts.rs` (the rendered OpenCode plugin under Node sends no unmarked request) and `external_capture_powershell.rs` `every_request_carries_the_client_marker` (Windows leg); `ai-memory-web/src/mount.rs` `web_surfaces_refuse_to_be_framed` (`/web`, `/web/pending`, `/web/login`, `/api/v1/projects` all carry both headers; bites with `deny_framing` neutralized) | STRONG with listed residuals. Bite checks: with the marker check disabled, the LAN e2e marker-less `GET /handoff` returns 200 and the unit layer test fails; with the proxy-header rule disabled, the proxied loopback e2e fetch claims the baton and the unit decision test fails; dropping the marker from the native handoff GET, the shell token-drain curl, a PowerShell header table or the TypeScript spool drain fails the matching front-door test. With the guard removed, the cross-origin `GET /handoff` returns 200, consumes the baton and moves the active-project pointer (the pre-fix behaviour); with the guard treating `same-origin` as foreign, the web UI control gets 403; with the `Sec-Fetch-Dest` check removed, the same-origin `document` `GET /handoff` returns 200 and the unit guard test lets a same-origin image through; with the host layer removed, a rebound `/hook` returns 202; a permissive `CorsLayer` fails the preflight assertion; reverting `is_safe_image_target` to the pre-fix rule fails the markdown test on `/handoff?…`, dropping the percent-decoding fails it on `%2e%2e/`, and emptying the route list fails it on a root-mounted `handoff`. To reproduce the bite on the 415 layer, remove the guard and make `/hook` read a raw body instead of `Json`: a `text/plain` hook then returns 202 and the test fails. Residual, closed by setting a bearer token: a browser that sends no fetch metadata even to a loopback host (Safari before 16.4) sends no `Sec-Fetch-*` header and no `Origin` on an image `GET` or a link click, so such a request to a loopback host still reaches `/handoff` (loopback keeps accepting marker-less legacy hooks) and the other, read-only `GET` routes. On a non-loopback host the marker requirement closes `/handoff` for every browser. A plain-HTTP proxy that rewrites `Host` to its loopback upstream and adds no forwarding header (nginx's default `proxy_pass`) looks exactly like a local client, so in front of an unauthenticated server it must add `X-Forwarded-For` or keep `proxy_set_header Host $host`, or the server must sit behind TLS or use a bearer token (`security.md`, `https-via-proxy.md`). Browsers that send fetch metadata no longer have the earlier link residuals: a link opened from another app (`Sec-Fetch-Site: none`) and a link clicked in a stored page (`same-origin` navigation) both carry a non-`empty` destination and are refused. With auth on, the bearer token and the session CSRF token are the gate and this layer is a no-op |
| 12d | The web UI and `/api/v1` cannot write, and render stored text inert | `crates/ai-memory-web/clippy.toml` `disallowed-methods`: every `Wiki` write and destructive method (`write_page`, `write_page_if`, `apply_batch`, the delete/evict/purge/restore/move/reindex/remove-dir helpers, `commit_all`, `approve_auto_improve_proposal`) and the `writer()` / `git()` accessors are lint errors in the crate, so the `Wiki` held by `WebState` stays read-only under `cargo clippy -D warnings`; only the integration-test module carries the `allow`, for fixtures. Templates are askama with HTML auto-escaping; the history diff (`templates/history.html`) and the session timeline (`templates/session.html`) print page lines, observation titles and bodies escaped, with no `|safe`, and no captured value is interpolated into a script | `ai-memory-web` `history_replay.rs` `session_timeline_renders_captured_markup_inert` (a `<script>` title and body plus `"><img onerror>` and `' onmouseover='` payloads, checked to survive ingest first, render escaped) and `history_diff_renders_page_markup_inert` (the same payloads in a page version's diff lines); `mount.rs` `web_surfaces_refuse_to_be_framed` covers the history, timeline and history-API routes (200 with both anti-framing headers) | STRONG. Bite checks: a `Wiki::write_page` and a `Wiki::delete_page` call added to `routes/history.rs` fail `cargo clippy -p ai-memory-web --all-targets -- -D warnings` with `use of a disallowed method`; `|safe` on the observation body or a diff line fails the matching inert-render test. The lint is per crate: a write reached through another crate's helper is outside it, which review and the `/api/v1` "zero writer calls" rule still cover |