Skip to content

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

Rust

fix(plugins): de-duplicate and skip folderless Droid plugin events

AkitaOnRails60894d88cbc9
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index 37fbfad0..ad80c5f9 100644
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@ -181,16 +181,30 @@ pub(crate) fn settings_file_carries_ai_memory_hooks(path: &Path) -> bool {
.is_some_and(|content| settings_carry_ai_memory_hooks(&content))
}
-/// Read bound for [`settings_file_carries_ai_memory_hook_for_event`]: it runs on the hook hot path, so a runaway
-/// settings file costs at most this much.
+/// Read bound for [`hooks_file_delivers_ai_memory_event`]: it runs on the hook
+/// hot path, so a runaway settings file costs at most this much.
const MAX_PLUGIN_DEDUP_SETTINGS_BYTES: u64 = 4 * 1024 * 1024;
-/// Whether the Claude-shaped settings file at `path` registers an ai-memory
-/// hook for `event` (`SessionStart`, ...). The Claude Code plugin's copy of
-/// an event is dropped only when a settings hook delivers that same event, so
-/// an older install that wires fewer events still gets the rest from the
-/// plugin. A missing, unreadable or malformed file registers nothing.
-pub(crate) fn settings_file_carries_ai_memory_hook_for_event(path: &Path, event: &str) -> bool {
+/// Where the event map sits in a hooks file a plugin event is checked against.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum HooksFileShape {
+ /// Claude-shaped: `{"hooks": {"SessionStart": [...]}}` (Claude Code
+ /// `settings.json`, Droid `settings.json`).
+ HooksKey,
+ /// The event map itself with no wrapper (Droid `hooks.json`).
+ EventMap,
+}
+
+/// Whether the hooks file at `path` registers an ai-memory hook for `event`
+/// (`SessionStart`, ...). A plugin's copy of an event is dropped only when
+/// such a hook delivers that same event, so an older install that wires fewer
+/// events still gets the rest from the plugin. A missing, unreadable or
+/// malformed file registers nothing.
+pub(crate) fn hooks_file_delivers_ai_memory_event(
+ path: &Path,
+ shape: HooksFileShape,
+ event: &str,
+) -> bool {
use std::io::Read as _;
let Ok(file) = fs::File::open(path) else {
return false;
@@ -203,11 +217,15 @@ pub(crate) fn settings_file_carries_ai_memory_hook_for_event(path: &Path, event:
{
return false;
}
- serde_json::from_str::<serde_json::Value>(&raw)
- .ok()
- .as_ref()
- .and_then(ai_memory_claude_hooks)
- .and_then(|hooks| hooks.get(event))
+ let Ok(document) = serde_json::from_str::<serde_json::Value>(&raw) else {
+ return false;
+ };
+ let event_map = match shape {
+ HooksFileShape::HooksKey => document.get("hooks"),
+ HooksFileShape::EventMap => Some(&document),
+ };
+ event_map
+ .and_then(|map| map.get(event))
.and_then(serde_json::Value::as_array)
.is_some_and(|entries| entries.iter().any(is_ai_memory_hook_entry))
}
diff --git a/crates/ai-memory-cli/src/commands/plugin_origin.rs b/crates/ai-memory-cli/src/commands/plugin_origin.rs
index 198073b4..c75638d6 100644
--- a/crates/ai-memory-cli/src/commands/plugin_origin.rs
+++ b/crates/ai-memory-cli/src/commands/plugin_origin.rs
@@ -20,8 +20,8 @@
use std::path::{Component, Path, PathBuf};
-use super::install_hooks;
-use super::render_shared::CLAUDE_CODE_EVENTS;
+use super::install_hooks::{self, HooksFileShape};
+use super::render_shared::{CLAUDE_CODE_EVENTS, DROID_EVENTS};
/// The environment variable the plugin launcher sets.
pub(crate) const HOOK_ORIGIN_ENV: &str = "AI_MEMORY_HOOK_ORIGIN";
@@ -33,6 +33,9 @@ pub(crate) enum PluginOrigin {
ClaudeCode,
/// The Codex plugin (`plugins/codex`).
Codex,
+ /// The Claude Code plugin loaded by Factory Droid through its Claude
+ /// plugin compatibility (the launcher re-attributes it to `droid`).
+ Droid,
}
impl PluginOrigin {
@@ -42,11 +45,16 @@ impl PluginOrigin {
match lookup(HOOK_ORIGIN_ENV)?.trim() {
"claude-code-plugin" => Some(Self::ClaudeCode),
"codex-plugin" => Some(Self::Codex),
+ "droid-plugin" => Some(Self::Droid),
_ => None,
}
}
}
+/// A file whose ai-memory hooks outrank the plugin, and where its event map
+/// sits.
+pub(crate) type SettingsHooks = (PathBuf, HooksFileShape);
+
/// Whether a plugin-launched event must be dropped before capture. `cwd` is
/// the payload's working directory; `settings_files` are the files whose
/// ai-memory hooks outrank the plugin (see [`settings_files_for`]).
@@ -54,7 +62,7 @@ pub(crate) fn drops_plugin_event(
origin: PluginOrigin,
event: &str,
cwd: Option<&str>,
- settings_files: &[PathBuf],
+ settings_files: &[SettingsHooks],
) -> bool {
if is_folderless(cwd) {
return true;
@@ -64,7 +72,7 @@ pub(crate) fn drops_plugin_event(
};
settings_files
.iter()
- .any(|path| install_hooks::settings_file_carries_ai_memory_hook_for_event(path, name))
+ .any(|(path, shape)| install_hooks::hooks_file_delivers_ai_memory_event(path, *shape, name))
}
/// The settings files that outrank the plugin for `origin`.
@@ -78,29 +86,58 @@ pub(crate) fn drops_plugin_event(
/// trusted, and nothing at hook time can tell a trusted one from a skipped
/// one, so dropping the plugin copy could lose the event entirely. `setup`
/// and `doctor` handle a double Codex install instead.
+///
+/// Droid: the one file Droid reads hooks from, as `install-hooks --agent
+/// droid` decides it. `~/.factory/hooks.json` (the bare event map) when it
+/// exists; otherwise the `hooks` key of `~/.factory/settings.json`, which
+/// Droid reads only while `hooks.json` is absent. Checking a file Droid
+/// ignores could drop the plugin copy of an event nothing else delivers.
pub(crate) fn settings_files_for(
origin: PluginOrigin,
cwd: Option<&str>,
mut lookup: impl FnMut(&str) -> Option<String>,
-) -> Vec<PathBuf> {
+) -> Vec<SettingsHooks> {
match origin {
PluginOrigin::Codex => Vec::new(),
PluginOrigin::ClaudeCode => {
let mut files = Vec::with_capacity(2);
let config_dir = lookup("CLAUDE_CONFIG_DIR").map(std::ffi::OsString::from);
if let Ok(user) = install_hooks::claude_settings_path_in(config_dir) {
- files.push(user);
+ files.push((user, HooksFileShape::HooksKey));
}
let project = lookup("CLAUDE_PROJECT_DIR")
.filter(|dir| !dir.trim().is_empty())
.or_else(|| cwd.map(str::to_owned));
if let Some(project) = project {
- files.push(install_hooks::project_claude_settings_local(Path::new(
- &project,
- )));
+ files.push((
+ install_hooks::project_claude_settings_local(Path::new(&project)),
+ HooksFileShape::HooksKey,
+ ));
}
files
}
+ PluginOrigin::Droid => {
+ // `AI_MEMORY_HOME` relocates every agent home ai-memory resolves
+ // (see `path_util::home_dir`); read it through the lookup so the
+ // check follows the same root `install-hooks` wrote under.
+ let hooks_json = match lookup("AI_MEMORY_HOME").filter(|home| !home.trim().is_empty()) {
+ Some(home) => {
+ Some(super::install_mcp::factory_home(Path::new(&home)).join("hooks.json"))
+ }
+ None => install_hooks::droid_hooks_path().ok(),
+ };
+ let Some(hooks_json) = hooks_json else {
+ return Vec::new();
+ };
+ if hooks_json.exists() {
+ vec![(hooks_json, HooksFileShape::EventMap)]
+ } else {
+ vec![(
+ hooks_json.with_file_name("settings.json"),
+ HooksFileShape::HooksKey,
+ )]
+ }
+ }
}
}
@@ -112,6 +149,10 @@ fn settings_event_name(origin: PluginOrigin, event: &str) -> Option<&'static str
.iter()
.find(|(_, script)| script.strip_suffix(".sh") == Some(event))
.map(|(name, _)| *name),
+ PluginOrigin::Droid => DROID_EVENTS
+ .iter()
+ .find(|(_, script)| script.strip_suffix(".sh") == Some(event))
+ .map(|(name, _)| *name),
PluginOrigin::Codex => None,
}
}
@@ -167,6 +208,10 @@ mod tests {
PluginOrigin::from_env(lookup(&[(HOOK_ORIGIN_ENV, " codex-plugin\n")])),
Some(PluginOrigin::Codex)
);
+ assert_eq!(
+ PluginOrigin::from_env(lookup(&[(HOOK_ORIGIN_ENV, "droid-plugin")])),
+ Some(PluginOrigin::Droid)
+ );
for other in ["", "claude-code", "cursor-plugin", "settings"] {
assert_eq!(
PluginOrigin::from_env(lookup(&[(HOOK_ORIGIN_ENV, other)])),
@@ -186,7 +231,7 @@ mod tests {
let settings = temp.path().join("settings.json");
std::fs::write(&settings, SETTINGS_HOOK).unwrap();
let cwd = Some("/work/repo");
- let files = vec![settings.clone()];
+ let files = vec![(settings.clone(), HooksFileShape::HooksKey)];
assert!(drops_plugin_event(
PluginOrigin::ClaudeCode,
@@ -202,7 +247,7 @@ mod tests {
PluginOrigin::ClaudeCode,
"session-start",
cwd,
- &[temp.path().join("missing.json")]
+ &[(temp.path().join("missing.json"), HooksFileShape::HooksKey)]
));
std::fs::write(
@@ -237,11 +282,93 @@ mod tests {
PluginOrigin::Codex,
"session-start",
Some("/work/repo"),
- &[settings]
+ &[(settings, HooksFileShape::HooksKey)]
));
assert!(settings_files_for(PluginOrigin::Codex, Some("/w"), lookup(&[])).is_empty());
}
+ const DROID_EVENT_MAP: &str = r#"{"SessionStart":[{"matcher":"","hooks":[{"type":"command","command":"/usr/bin/ai-memory hook --event session-start --agent droid --server-url http://127.0.0.1:49374"}]}]}"#;
+
+ fn droid_files(home: &Path) -> Vec<SettingsHooks> {
+ let home = home.to_string_lossy().into_owned();
+ settings_files_for(
+ PluginOrigin::Droid,
+ Some("/work/repo"),
+ lookup(&[("AI_MEMORY_HOME", home.as_str())]),
+ )
+ }
+
+ fn droid_drops(home: &Path, event: &str) -> bool {
+ drops_plugin_event(
+ PluginOrigin::Droid,
+ event,
+ Some("/work/repo"),
+ &droid_files(home),
+ )
+ }
+
+ /// Adversarial: Droid running the Claude Code plugin next to an
+ /// `install-hooks --agent droid` install delivers each event twice unless
+ /// the plugin copy is dropped. Controls: no Droid hooks at all, and an
+ /// event the Droid hooks do not wire, keep the plugin copy.
+ #[test]
+ fn droid_plugin_copy_is_dropped_when_droid_hooks_deliver_the_event() {
+ let temp = tempfile::tempdir().unwrap();
+ let factory = temp.path().join(".factory");
+ std::fs::create_dir_all(&factory).unwrap();
+ assert!(
+ !droid_drops(temp.path(), "session-start"),
+ "nothing installed"
+ );
+
+ std::fs::write(factory.join("hooks.json"), DROID_EVENT_MAP).unwrap();
+ assert!(droid_drops(temp.path(), "session-start"));
+ assert!(
+ !droid_drops(temp.path(), "stop"),
+ "an event hooks.json does not wire stays with the plugin"
+ );
+ assert!(
+ !droid_drops(temp.path(), "subagent-start"),
+ "Droid has no subagent hook, so the plugin keeps it"
+ );
+ }
+
+ /// Droid reads `settings.json` hooks only while `hooks.json` is absent, so
+ /// that is the only time they may suppress the plugin. Adversarial: an
+ /// ai-memory hook left in `settings.json` beside a `hooks.json` without
+ /// one is dead config and must not drop the plugin copy.
+ #[test]
+ fn droid_settings_hooks_count_only_while_hooks_json_is_absent() {
+ let temp = tempfile::tempdir().unwrap();
+ let factory = temp.path().join(".factory");
+ std::fs::create_dir_all(&factory).unwrap();
+ std::fs::write(
+ factory.join("settings.json"),
+ format!(r#"{{"model":"x","hooks":{DROID_EVENT_MAP}}}"#),
+ )
+ .unwrap();
+ assert!(droid_drops(temp.path(), "session-start"));
+
+ std::fs::write(factory.join("hooks.json"), "{}").unwrap();
+ assert!(!droid_drops(temp.path(), "session-start"));
+ }
+
+ #[test]
+ fn droid_plugin_skips_folderless_sessions() {
+ assert!(drops_plugin_event(
+ PluginOrigin::Droid,
+ "user-prompt-submit",
+ None,
+ &[]
+ ));
+ assert!(!drops_plugin_event(
+ PluginOrigin::Droid,
+ "user-prompt-submit",
+ Some("/work/repo"),
+ &[]
+ ));
+ }
+
#[test]
fn settings_files_honour_claude_config_dir_and_project_dir() {
let files = settings_files_for(
@@ -254,14 +381,19 @@ mod tests {
);
assert_eq!(
files[0],
- Path::new("/relocated/claude").join("settings.json")
+ (
+ Path::new("/relocated/claude").join("settings.json"),
+ HooksFileShape::HooksKey
+ )
);
assert!(
- files[1].ends_with(Path::new(".claude").join("settings.local.json")),
+ files[1]
+ .0
+ .ends_with(Path::new(".claude").join("settings.local.json")),
"{files:?}"
);
assert!(
- files[1].starts_with("/the/project"),
+ files[1].0.starts_with("/the/project"),
"CLAUDE_PROJECT_DIR outranks the payload cwd: {files:?}"
);
@@ -270,7 +402,7 @@ mod tests {
Some("/payload/cwd"),
lookup(&[("CLAUDE_PROJECT_DIR", " ")]),
);
- assert!(files[1].starts_with("/payload/cwd"), "{files:?}");
+ assert!(files[1].0.starts_with("/payload/cwd"), "{files:?}");
}
#[test]
diff --git a/crates/ai-memory-cli/tests/suite/plugins.rs b/crates/ai-memory-cli/tests/suite/plugins.rs
index 8c89f9ac..d71a7967 100644
--- a/crates/ai-memory-cli/tests/suite/plugins.rs
+++ b/crates/ai-memory-cli/tests/suite/plugins.rs
@@ -491,6 +491,69 @@ mod launcher {
);
}
+ /// Front door 4 for Droid (adversarial): Droid runs the Claude Code
+ /// plugin with `DROID_PLUGIN_ROOT`, and the launcher re-attributes it.
+ /// With the `install-hooks --agent droid` hook for the same event in
+ /// `~/.factory/hooks.json` the plugin copy is dropped. Controls: no Droid
+ /// hooks keeps it, and so does a Claude settings hook, which Droid never
+ /// runs. A folderless Droid session is not captured either.
+ #[test]
+ fn a_droid_hook_for_the_same_event_drops_the_droid_plugin_copy() {
+ let sb = Sandbox::new();
+ let root = sb.home.to_string_lossy().into_owned();
+ let droid = [
+ ("CLAUDE_PLUGIN_ROOT", ""),
+ ("DROID_PLUGIN_ROOT", root.as_str()),
+ ];
+
+ sb.settings_hook(
+ &sb.claude.join("settings.json"),
+ "UserPromptSubmit",
+ "user-prompt-submit",
+ );
+ sb.launch("user-prompt-submit", &sb.prompt(), &droid);
+ assert_eq!(sb.spooled().len(), 1, "control: no Droid hook");
+ assert!(
+ sb.spooled()[0]["url"]
+ .as_str()
+ .unwrap()
+ .contains("agent=droid")
+ );
+
+ let factory = sb.home.join(".factory");
+ std::fs::create_dir_all(&factory).unwrap();
+ let command = format!(
+ "{BIN} hook --event user-prompt-submit --agent droid --server-url {}",
+ sb.server
+ );
+ std::fs::write(
+ factory.join("hooks.json"),
+ json!({"UserPromptSubmit": [{"matcher": "", "hooks": [{"type": "command", "command": command}]}]})
+ .to_string(),
+ )
+ .unwrap();
+ sb.launch("user-prompt-submit", &sb.prompt(), &droid);
+ assert_eq!(
+ sb.spooled().len(),
+ 1,
+ "Droid hooks.json: plugin copy dropped"
+ );
+
+ sb.launch("post-tool-use", &sb.read_tool("README.md"), &droid);
+ assert_eq!(
+ sb.spooled().len(),
+ 2,
+ "an unwired event stays with the plugin"
+ );
+
+ sb.launch(
+ "user-prompt-submit",
+ &json!({"session_id": "s", "prompt": "no cwd"}),
+ &droid,
+ );
+ assert_eq!(sb.spooled().len(), 2, "folderless Droid session");
+ }
+
/// A session with no project folder is not captured through the plugin.
#[test]
fn folderless_sessions_are_not_captured_through_the_plugin() {
diff --git a/docs/design-marketplace-plugins.md b/docs/design-marketplace-plugins.md
index 761dcafd..3ae9479b 100644
--- a/docs/design-marketplace-plugins.md
+++ b/docs/design-marketplace-plugins.md
@@ -394,7 +394,11 @@ our repository would install the Claude plugin and send events tagged
the matching ai-memory agent when one exists, and otherwise prints `{}` and
exits. *Shipped:* `DROID_PLUGIN_ROOT` → `droid`; `PLUGIN_ROOT` without
`CLAUDE_PLUGIN_ROOT` → `codex`; neither `CLAUDE_PLUGIN_ROOT` nor
- `PLUGIN_ROOT` → `{}`. Cursor is not remapped: when Cursor runs Claude
+ `PLUGIN_ROOT` → `{}`. A Droid-launched event carries
+ `AI_MEMORY_HOOK_ORIGIN=droid-plugin` and gets the same folderless skip and
+ de-duplication as the Claude Code plugin, against the one file Droid reads
+ hooks from (`~/.factory/hooks.json`, else the `hooks` key of
+ `~/.factory/settings.json`). Cursor is not remapped: when Cursor runs Claude
hooks the event already reaches the existing #721 path as `claude-code`
with `cursor_version`, and whether Cursor runs *plugin* hooks at all is
one of the Cursor unknowns;
diff --git a/docs/install.md b/docs/install.md
index 534feb15..c97eae85 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -225,6 +225,11 @@ configure ai-memory@ai-memory`:
`install-mcp`, `install-skills`) to add them anyway.
- Folderless sessions (a desktop scratch workspace with no project folder)
are not captured through the plugin.
+- Factory Droid can install this plugin through its Claude marketplace
+ fallback. Its events are recorded as `droid`, and when `install-hooks
+ --agent droid` hooks deliver the same event (`~/.factory/hooks.json`, or
+ the `hooks` key of `~/.factory/settings.json` while `hooks.json` does not
+ exist) the plugin skips it, as it does for Claude's settings hooks.
- On Windows, Claude Code runs plugin hooks through Git Bash, which it
already requires, so the launcher needs nothing else.
- With the Docker wrapper, plugin hooks need a `bin/ai-memory` wrapper that runs
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index b24f8ca9..b1f6fdfb 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -82,7 +82,7 @@ means the boundary is not built yet.
| 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). 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` and Antigravity `toolCall.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 |
-| 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 and `exec`s `ai-memory hook` with `AI_MEMORY_HOOK_ORIGIN=<agent>-plugin`, `hook` first so the Docker wrapper routes it, 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::settings_file_carries_ai_memory_hook_for_event`), and 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), `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`); `hook.rs` `plugin_copy_is_dropped_only_with_the_plugin_origin`; `tests/hooks/test_plugin_launcher.sh`; `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`) |
+| 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 and `exec`s `ai-memory hook` with `AI_MEMORY_HOOK_ORIGIN=<agent>-plugin`, `hook` first so the Docker wrapper routes it, 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`); 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), `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`); `hook.rs` `plugin_copy_is_dropped_only_with_the_plugin_origin`; `tests/hooks/test_plugin_launcher.sh`; `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`) |
| 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 |
| 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 |