Skip to content

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

Rust

feat(uninstall): remove the user service setup installed, and only that

AkitaOnRailsdf61901399ae
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e6063a42..b22196b5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -57,7 +57,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
agent, and ends with a read-only check of `/healthz`, `memory_status` and
`doctor`. It shows the plan and asks first; without a terminal it changes
nothing unless given `--yes`. A second run changes nothing. Windows has no
- service step. `INSTALL_FOR_AGENTS.md` tells an AI agent how to install
+ service step. `ai-memory uninstall --apply` stops and removes that service,
+ but only a unit `setup` wrote and nobody edited since; any other unit at that
+ path is left alone and reported. `INSTALL_FOR_AGENTS.md` tells an AI agent how to install
ai-memory for its user, and `scripts/onboarding-acceptance.sh` measures the
path from a clean home to the first returned memory.
- Added page history and session replay to the read-only web UI. Each page
diff --git a/crates/ai-memory-cli/src/commands/uninstall.rs b/crates/ai-memory-cli/src/commands/uninstall.rs
index b92d940a..9650aed0 100644
--- a/crates/ai-memory-cli/src/commands/uninstall.rs
+++ b/crates/ai-memory-cli/src/commands/uninstall.rs
@@ -14,6 +14,7 @@ use crate::commands::apply_shared::{PrivateBackup, apply_atomic_with_backup};
use crate::commands::path_util::{
agent_config_home, claude_config_dir, claude_config_paths, home_dir,
};
+use crate::commands::user_service::{self, ServiceManager};
use crate::commands::{data_purge, install_hooks, install_mcp, openclaw_plugin};
use crate::config::Config;
use ai_memory_core::routing_skills::{
@@ -698,6 +699,15 @@ pub fn run(config: &Config, args: UninstallArgs) -> anyhow::Result<()> {
let plan = build_plan(&args, &config.data_dir)?;
print_plan(&plan);
+ let service = if args.only.is_none() {
+ setup_service(config)
+ } else {
+ None
+ };
+ if let Some((_, removal)) = &service {
+ print_service_plan(removal);
+ }
+ let remove_service = matches!(&service, Some((_, user_service::Removal::Removed(_))));
let hooks_removed = args.only.is_none() || args.only == Some(crate::cli::UninstallOnly::Hooks);
if hooks_removed {
// Only the current checkout's project file is reachable from here.
@@ -716,21 +726,10 @@ pub fn run(config: &Config, args: UninstallArgs) -> anyhow::Result<()> {
println!("(dry-run; pass --apply to remove)");
return Ok(());
}
- if plan.is_empty() && !args.purge_data {
+ if plan.is_empty() && !args.purge_data && !remove_service {
return Ok(());
}
- // All-or-nothing: when we're going to purge data, refuse before touching
- // anything if an ai-memory process is alive (matches reset's guard-at-top).
- // Wiring-only uninstall stays unguarded — it edits agent config files the
- // server never touches.
- if args.purge_data {
- let siblings = crate::process_guard::sibling_processes();
- if !siblings.is_empty() {
- anyhow::bail!(crate::process_guard::busy_message("purge data", &siblings));
- }
- }
-
if std::io::stdin().is_terminal() && !args.yes {
eprint!("Proceed with removal? [y/N] ");
use std::io::Write as _;
@@ -743,6 +742,28 @@ pub fn run(config: &Config, args: UninstallArgs) -> anyhow::Result<()> {
}
}
+ // The service `setup` installed runs the server this uninstall is taking
+ // away; stop it first, so a purge below does not find it alive.
+ if let Some((manager, user_service::Removal::Removed(path))) = &service {
+ match user_service::remove(*manager, path, &user_service::SystemRunner)? {
+ user_service::Removal::Removed(path) => {
+ println!("✓ stopped and removed the user service {}", path.display());
+ }
+ other => print_service_plan(&other),
+ }
+ }
+
+ // All-or-nothing: when we're going to purge data, refuse before touching
+ // the data if an ai-memory process is alive (matches reset's guard-at-top).
+ // Wiring-only uninstall stays unguarded — it edits agent config files the
+ // server never touches.
+ if args.purge_data {
+ let siblings = crate::process_guard::sibling_processes();
+ if !siblings.is_empty() {
+ anyhow::bail!(crate::process_guard::busy_message("purge data", &siblings));
+ }
+ }
+
// The current checkout's `.claude/settings.local.json` keeps its backup
// under the data dir, as `install-hooks --scope project` does: a sibling
// `.bak-<ts>` would sit untracked in the repository.
@@ -795,6 +816,35 @@ pub fn run(config: &Config, args: UninstallArgs) -> anyhow::Result<()> {
Ok(())
}
+/// The user service `setup` installs on this platform and what uninstall
+/// would do about it; `None` on a platform without one or with no home.
+fn setup_service(config: &Config) -> Option<(ServiceManager, user_service::Removal)> {
+ let manager = ServiceManager::current()?;
+ let home = crate::commands::run::native_home(config)?;
+ let xdg_config_home = config
+ .runtime_env
+ .process_env()
+ .iter()
+ .find(|(key, _)| key == "XDG_CONFIG_HOME")
+ .map(|(_, value)| PathBuf::from(value));
+ let path = user_service::unit_path(manager, &home, xdg_config_home.as_deref());
+ Some((manager, user_service::planned_removal(&path)))
+}
+
+fn print_service_plan(removal: &user_service::Removal) {
+ match removal {
+ user_service::Removal::Absent => {}
+ user_service::Removal::Removed(path) => {
+ println!("would stop and remove the user service {}", path.display());
+ }
+ user_service::Removal::NotOurs(path) => println!(
+ "leaving {}: `ai-memory setup` did not write it, or it was edited since; remove it \
+ yourself if it runs ai-memory",
+ path.display()
+ ),
+ }
+}
+
/// Print the manual Docker teardown steps (never executed). When the
/// data was purged locally, note that; otherwise remind how to wipe it.
fn print_docker_hint(data_purged: bool) {
diff --git a/crates/ai-memory-cli/src/commands/user_service.rs b/crates/ai-memory-cli/src/commands/user_service.rs
index bbc3da21..de783750 100644
--- a/crates/ai-memory-cli/src/commands/user_service.rs
+++ b/crates/ai-memory-cli/src/commands/user_service.rs
@@ -40,6 +40,12 @@ const SYSTEMD_CONFIG: &str = "%h/.config/ai-memory/config.toml";
const LAUNCHD_BIN: &str = "<string>__AI_MEMORY_BIN__</string>";
const LAUNCHD_HOME: &str = "<string>__HOME__/";
+/// Start of the identity line `setup` writes into every unit it renders. The
+/// rest of the line is the SHA-256 of the file without that line, so
+/// `uninstall` can tell a unit `setup` wrote, and nobody edited since, from a
+/// hand-written or hand-edited one, which it leaves alone.
+const IDENTITY_PREFIX: &str = "ai-memory-setup-unit sha256:";
+
/// Which service manager this platform uses.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum ServiceManager {
@@ -176,23 +182,90 @@ fn render_systemd(spec: &ServiceSpec) -> Result<ServiceUnit> {
1,
);
let body = SYSTEMD_USER_TEMPLATE.replacen(exec, &rendered_exec, 1);
- let contents = format!(
+ let unstamped = format!(
"# Written by `ai-memory setup` from packaging/systemd/ai-memory-user.service.\n\
- # Re-run `ai-memory setup` instead of editing; it rewrites this file.\n{body}"
+ # Re-run `ai-memory setup` instead of editing; `ai-memory uninstall` removes it.\n{body}"
);
- let config_home = spec
- .xdg_config_home
- .clone()
- .filter(|dir| dir.is_absolute())
- .unwrap_or_else(|| spec.home.join(".config"));
Ok(ServiceUnit {
manager: ServiceManager::SystemdUser,
- path: config_home
+ path: unit_path(
+ ServiceManager::SystemdUser,
+ &spec.home,
+ spec.xdg_config_home.as_deref(),
+ ),
+ contents: stamp(ServiceManager::SystemdUser, &unstamped),
+ })
+}
+
+/// Where `manager`'s unit for ai-memory lives: under `$XDG_CONFIG_HOME` (when
+/// absolute) or `~/.config` for systemd, `~/Library/LaunchAgents` for launchd.
+pub(crate) fn unit_path(
+ manager: ServiceManager,
+ home: &Path,
+ xdg_config_home: Option<&Path>,
+) -> PathBuf {
+ match manager {
+ ServiceManager::SystemdUser => xdg_config_home
+ .filter(|dir| dir.is_absolute())
+ .map_or_else(|| home.join(".config"), Path::to_path_buf)
.join("systemd")
.join("user")
.join(SYSTEMD_UNIT_NAME),
- contents,
- })
+ ServiceManager::Launchd => home
+ .join("Library")
+ .join("LaunchAgents")
+ .join(format!("{LAUNCHD_LABEL}.plist")),
+ }
+}
+
+fn identity_line(manager: ServiceManager, digest: &str) -> String {
+ match manager {
+ ServiceManager::SystemdUser => format!("# {IDENTITY_PREFIX}{digest}"),
+ ServiceManager::Launchd => format!("<!-- {IDENTITY_PREFIX}{digest} -->"),
+ }
+}
+
+fn sha256_hex(text: &str) -> String {
+ use sha2::{Digest as _, Sha256};
+ format!("{:x}", Sha256::digest(text.as_bytes()))
+}
+
+/// Insert the identity line: first in a systemd unit, right after the XML
+/// declaration in a plist (which must stay first).
+fn stamp(manager: ServiceManager, unstamped: &str) -> String {
+ let line = identity_line(manager, &sha256_hex(unstamped));
+ match manager {
+ ServiceManager::SystemdUser => format!("{line}\n{unstamped}"),
+ ServiceManager::Launchd => match unstamped.split_once('\n') {
+ Some((declaration, rest)) => format!("{declaration}\n{line}\n{rest}"),
+ None => format!("{line}\n{unstamped}"),
+ },
+ }
+}
+
+/// Whether `text` is a unit `setup` rendered and nobody changed since: exactly
+/// one identity line, whose digest matches the rest of the file.
+pub(crate) fn is_rendered_by_setup(text: &str) -> bool {
+ let mut identities = text
+ .split_inclusive('\n')
+ .enumerate()
+ .filter(|(_, line)| line.contains(IDENTITY_PREFIX));
+ let (Some((index, line)), None) = (identities.next(), identities.next()) else {
+ return false;
+ };
+ let Some(digest) = line
+ .split_once(IDENTITY_PREFIX)
+ .map(|(_, rest)| rest.trim_end_matches(['\n', '\r', ' ', '>', '-']))
+ else {
+ return false;
+ };
+ let rest: String = text
+ .split_inclusive('\n')
+ .enumerate()
+ .filter(|(i, _)| *i != index)
+ .map(|(_, line)| line)
+ .collect();
+ digest.len() == 64 && sha256_hex(&rest) == digest
}
fn xml_text(text: &str) -> String {
@@ -228,12 +301,8 @@ fn render_launchd(spec: &ServiceSpec) -> Result<ServiceUnit> {
}
Ok(ServiceUnit {
manager: ServiceManager::Launchd,
- path: spec
- .home
- .join("Library")
- .join("LaunchAgents")
- .join(format!("{LAUNCHD_LABEL}.plist")),
- contents,
+ path: unit_path(ServiceManager::Launchd, &spec.home, None),
+ contents: stamp(ServiceManager::Launchd, &contents),
})
}
@@ -422,6 +491,71 @@ fn start_launchd(unit: &ServiceUnit, runner: &dyn CommandRunner, loaded: bool) -
Ok(())
}
+/// What `uninstall` did about the user service.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) enum Removal {
+ /// There is no unit at the path `setup` writes.
+ Absent,
+ /// `setup`'s unit was stopped, disabled and deleted.
+ Removed(PathBuf),
+ /// A unit is there but `setup` did not write it, or it was edited since;
+ /// it was left alone.
+ NotOurs(PathBuf),
+}
+
+/// Whether the unit at `path` is one `uninstall` would remove; reads only.
+pub(crate) fn planned_removal(path: &Path) -> Removal {
+ match std::fs::read_to_string(path) {
+ Err(_) if !path.exists() => Removal::Absent,
+ Ok(text) if is_rendered_by_setup(&text) => Removal::Removed(path.to_path_buf()),
+ _ => Removal::NotOurs(path.to_path_buf()),
+ }
+}
+
+/// Stop, disable and delete the unit at `path` when `setup` wrote it and it
+/// is unedited; leave anything else alone. A second call finds nothing.
+///
+/// # Errors
+/// A service-manager command that fails (the file is then kept, so a still
+/// running service never loses its unit) or a failed delete.
+pub(crate) fn remove(
+ manager: ServiceManager,
+ path: &Path,
+ runner: &dyn CommandRunner,
+) -> Result<Removal> {
+ let planned = planned_removal(path);
+ if !matches!(planned, Removal::Removed(_)) {
+ return Ok(planned);
+ }
+ match manager {
+ ServiceManager::SystemdUser => {
+ require(
+ runner,
+ "systemctl",
+ &["--user", "disable", "--now", SYSTEMD_UNIT_NAME],
+ )?;
+ delete_unit(path)?;
+ require(runner, "systemctl", &["--user", "daemon-reload"])?;
+ }
+ ServiceManager::Launchd => {
+ let domain = launchd_domain(runner)?;
+ if launchd_loaded(runner, &domain) {
+ require(
+ runner,
+ "launchctl",
+ &["bootout", &format!("{domain}/{LAUNCHD_LABEL}")],
+ )?;
+ }
+ delete_unit(path)?;
+ }
+ }
+ Ok(planned)
+}
+
+fn delete_unit(path: &Path) -> Result<()> {
+ std::fs::remove_file(path).with_context(|| format!("removing {}", path.display()))
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -688,4 +822,117 @@ mod tests {
};
assert!(launchd_domain(&runner).is_err());
}
+
+ #[test]
+ fn rendered_units_carry_an_identity_that_survives_only_unedited() {
+ for manager in [ServiceManager::SystemdUser, ServiceManager::Launchd] {
+ let unit = render(manager, &spec(Path::new("/srv/u"))).unwrap();
+ assert!(is_rendered_by_setup(&unit.contents), "{manager:?}");
+ // Hand-edited: any byte changed outside the identity line.
+ let edited = unit.contents.replacen("serve", "serve --verbose", 1);
+ assert!(!is_rendered_by_setup(&edited), "{manager:?} edited");
+ // A copied identity line on a different body, or two of them.
+ let line = unit
+ .contents
+ .lines()
+ .find(|l| l.contains(IDENTITY_PREFIX))
+ .unwrap();
+ assert!(!is_rendered_by_setup(&format!(
+ "{line}\n[Service]\nExecStart=/bin/evil\n"
+ )));
+ assert!(!is_rendered_by_setup(&format!("{line}\n{}", unit.contents)));
+ }
+ // The packaged template itself (what a package or a person installs)
+ // is not ours.
+ assert!(!is_rendered_by_setup(SYSTEMD_USER_TEMPLATE));
+ assert!(!is_rendered_by_setup(LAUNCHD_TEMPLATE));
+ }
+
+ #[test]
+ fn removing_our_systemd_unit_stops_disables_deletes_and_reloads_once() {
+ let tmp = tempfile::tempdir().unwrap();
+ let unit = render(ServiceManager::SystemdUser, &spec(tmp.path())).unwrap();
+ write_unit(&unit).unwrap();
+ let runner = FakeRunner::default();
+ assert_eq!(
+ remove(ServiceManager::SystemdUser, &unit.path, &runner).unwrap(),
+ Removal::Removed(unit.path.clone())
+ );
+ assert!(!unit.path.exists());
+ assert_eq!(
+ runner.calls.borrow().clone(),
+ vec![
+ "systemctl --user disable --now ai-memory.service",
+ "systemctl --user daemon-reload",
+ ]
+ );
+
+ // A second removal finds nothing and calls nothing.
+ let again = FakeRunner::default();
+ assert_eq!(
+ remove(ServiceManager::SystemdUser, &unit.path, &again).unwrap(),
+ Removal::Absent
+ );
+ assert!(again.calls.borrow().is_empty());
+ }
+
+ /// Adversarial control: a unit `setup` did not write, or one edited after
+ /// it did, is neither stopped nor deleted.
+ #[test]
+ fn a_foreign_or_edited_unit_is_left_alone() {
+ let tmp = tempfile::tempdir().unwrap();
+ let unit = render(ServiceManager::SystemdUser, &spec(tmp.path())).unwrap();
+ std::fs::create_dir_all(unit.path.parent().unwrap()).unwrap();
+ for text in [
+ SYSTEMD_USER_TEMPLATE.to_owned(),
+ unit.contents
+ .replacen("Restart=on-failure", "Restart=always", 1),
+ ] {
+ std::fs::write(&unit.path, &text).unwrap();
+ let runner = FakeRunner::default();
+ assert_eq!(
+ remove(ServiceManager::SystemdUser, &unit.path, &runner).unwrap(),
+ Removal::NotOurs(unit.path.clone())
+ );
+ assert_eq!(std::fs::read_to_string(&unit.path).unwrap(), text);
+ assert!(runner.calls.borrow().is_empty());
+ }
+ }
+
+ #[test]
+ fn a_failed_disable_keeps_the_unit() {
+ let tmp = tempfile::tempdir().unwrap();
+ let unit = render(ServiceManager::SystemdUser, &spec(tmp.path())).unwrap();
+ write_unit(&unit).unwrap();
+ let runner = FakeRunner {
+ failing: vec!["systemctl --user disable"],
+ ..FakeRunner::default()
+ };
+ assert!(remove(ServiceManager::SystemdUser, &unit.path, &runner).is_err());
+ assert!(unit.is_current());
+ }
+
+ #[test]
+ fn removing_our_launch_agent_boots_it_out_then_deletes_it() {
+ let tmp = tempfile::tempdir().unwrap();
+ let unit = render(ServiceManager::Launchd, &spec(tmp.path())).unwrap();
+ write_unit(&unit).unwrap();
+ let runner = FakeRunner {
+ stdout: vec![("id -u", "501\n")],
+ ..FakeRunner::default()
+ };
+ assert_eq!(
+ remove(ServiceManager::Launchd, &unit.path, &runner).unwrap(),
+ Removal::Removed(unit.path.clone())
+ );
+ assert!(!unit.path.exists());
+ assert_eq!(
+ runner.calls.borrow().clone(),
+ vec![
+ "id -u",
+ "launchctl print gui/501/com.github.akitaonrails.ai-memory",
+ "launchctl bootout gui/501/com.github.akitaonrails.ai-memory",
+ ]
+ );
+ }
}
diff --git a/crates/ai-memory-cli/tests/suite/setup_e2e.rs b/crates/ai-memory-cli/tests/suite/setup_e2e.rs
index af8840f6..f926e23f 100644
--- a/crates/ai-memory-cli/tests/suite/setup_e2e.rs
+++ b/crates/ai-memory-cli/tests/suite/setup_e2e.rs
@@ -143,6 +143,9 @@ case "$1" in
enable) touch "$state/enabled" ;;
is-enabled) [ -f "$state/enabled" ] ;;
is-active) alive ;;
+ disable)
+ rm -f "$state/enabled"
+ if [ "$2" = "--now" ] && alive; then kill "$(cat "$state/pid")"; rm -f "$state/pid"; fi ;;
restart)
if alive; then kill "$(cat "$state/pid")"; sleep 0.2; fi
line="$(sed -n 's/^ExecStart=//p' "$unit")"
@@ -238,7 +241,7 @@ esac
/// passes its own self-check. A captured hook event reaches the server. A
/// second run changes no file and makes no state-changing service call.
#[tokio::test]
- async fn setup_installs_wires_and_a_second_run_changes_nothing() {
+ async fn setup_installs_wires_is_idempotent_and_uninstall_removes_its_unit() {
let sandbox = Sandbox::new();
let service = Service::new(&sandbox.root);
std::fs::create_dir_all(sandbox.home.join(".claude/projects")).unwrap();
@@ -396,5 +399,65 @@ esac
"--user is-enabled --quiet ai-memory.service",
]
);
+
+ // uninstall stops and removes the unit setup wrote, and only once.
+ let unit_path = sandbox.home.join(".config/systemd/user/ai-memory.service");
+ let calls_before = service.calls().len();
+ let removed = uninstall(&sandbox, &service, port);
+ assert!(removed.status.success(), "{}", text(&removed));
+ assert!(
+ String::from_utf8_lossy(&removed.stdout)
+ .contains("stopped and removed the user service"),
+ "{}",
+ text(&removed)
+ );
+ assert!(!unit_path.exists());
+ assert_eq!(
+ service.calls()[calls_before..].to_vec(),
+ vec![
+ "--user disable --now ai-memory.service",
+ "--user daemon-reload",
+ ]
+ );
+ let calls_before = service.calls().len();
+ let again = uninstall(&sandbox, &service, port);
+ assert!(again.status.success(), "{}", text(&again));
+ assert_eq!(
+ service.calls().len(),
+ calls_before,
+ "a second uninstall called systemctl"
+ );
+ }
+
+ fn uninstall(sandbox: &Sandbox, service: &Service, port: u16) -> Output {
+ let mut cmd = sandbox.cmd(Some(port));
+ service.apply(&mut cmd);
+ cmd.args(["uninstall", "--apply", "--yes"])
+ .output()
+ .unwrap()
+ }
+
+ /// Adversarial control: a unit at the same path that `setup` did not
+ /// write (the packaged one copied by hand), or one edited after `setup`
+ /// wrote it, is neither stopped nor deleted, and uninstall says so.
+ #[test]
+ fn uninstall_leaves_a_unit_it_did_not_write() {
+ let sandbox = Sandbox::new();
+ let service = Service::new(&sandbox.root);
+ let unit_path = sandbox.home.join(".config/systemd/user/ai-memory.service");
+ std::fs::create_dir_all(unit_path.parent().unwrap()).unwrap();
+ let foreign = include_str!("../../../../packaging/systemd/ai-memory-user.service");
+ std::fs::write(&unit_path, foreign).unwrap();
+ let port = crate::e2e_support::free_port();
+
+ let out = uninstall(&sandbox, &service, port);
+ assert!(out.status.success(), "{}", text(&out));
+ assert!(
+ String::from_utf8_lossy(&out.stdout).contains("did not write it"),
+ "{}",
+ text(&out)
+ );
+ assert_eq!(std::fs::read_to_string(&unit_path).unwrap(), foreign);
+ assert!(service.calls().is_empty(), "{:?}", service.calls());
}
}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index de7ce5f3..31f3fda4 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -794,7 +794,9 @@ session store or MCP config (the stores `doctor` scans). It finishes with a
read-only self-check: `/healthz`, a `memory_status` call over MCP, and
`doctor`. The service manager is reached through an injectable runner, so the
unit rendering and the `systemctl`/`launchctl` calls are tested without a real
-session. Windows has no service step. A second run changes no file.
+session. Windows has no service step. A second run changes no file. Each
+rendered unit carries an identity line with the SHA-256 of the rest of the
+file; `uninstall` stops and removes only a unit whose digest still matches.
`install.sh`, a release asset with its own `.sha256`, installs the release
tarball under `~/.local` after checking it against the published checksum.
diff --git a/docs/install.md b/docs/install.md
index 859c1738..1d11b6f5 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -130,13 +130,20 @@ is never printed or passed on a command line, and no harness config holds it:
hooks read the credential files `init` writes, and MCP clients reach the
server through `ai-memory mcp-bridge`.
-`uninstall --apply` removes the hooks, MCP entries and skills `setup` wired,
-but not the service. Remove that by hand:
+`uninstall --apply` removes what `setup` wired, the service included. Every
+unit `setup` renders carries an identity line holding the SHA-256 of the rest of
+the file, and `uninstall` removes only a unit whose line is there and still
+matches: on Linux it runs `systemctl --user disable --now ai-memory.service`,
+deletes the file and runs `systemctl --user daemon-reload`; on macOS it boots
+the LaunchAgent out and deletes the plist. A unit `setup` did not write, or one
+edited since, is left in place and `uninstall` says so. If you need to remove
+such a unit, or the service manager refused, do it by hand:
```bash
# Linux
systemctl --user disable --now ai-memory.service
rm ~/.config/systemd/user/ai-memory.service
+systemctl --user daemon-reload
# macOS
launchctl bootout "gui/$(id -u)/com.github.akitaonrails.ai-memory"
rm ~/Library/LaunchAgents/com.github.akitaonrails.ai-memory.plist
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index 7e55a181..bba6b5a4 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -79,7 +79,7 @@ means the boundary is not built yet.
| 11h | Docker-wrapper capture-policy capability (#1002) | `bin/ai-memory` routes ordinary Linux/macOS `install-hooks` and upgrade refreshes through the stable checksum-verified native host client, so the hook process executes the capture-policy boundary in 11b before spool/network. 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 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; `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); `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 |
-| 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); `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_and_a_second_run_changes_nothing` (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) | 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 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; `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 |
| 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 |