Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! `ai-memory backfill` — one-time import of a project's pre-hook local history.
//!
//! Capture is forward-only: hooks record events only from the moment they are
//! installed. If you have worked in a project for weeks and only now install
//! ai-memory, the tool that exists for cross-session continuity starts
//! amnesiac about the very session you are resuming. This command fills that
//! first-boot gap: when the project's store is **brand new (empty)**, it
//! imports the existing local harness transcript history once.
//!
//! For each local native session it **replays the transcript through `/hook`**,
//! the same ingress live capture uses (as the companion importer does for
//! external conversations):
//!
//! - `export_transcript` (ai-memory-workstream) reads the harness's native
//! transcript read-only into a normalized, bounded visible-event ledger,
//! doing all the per-harness parsing in one place;
//! - each event is posted to `/hook/batch` as a session-start, `user-prompt`,
//! or backfill-extension observation, attributed to the original harness and
//! its native session id — so it becomes a real session + observations that
//! consolidate into pages and are searchable via `memory_query`, exactly like
//! live capture. The server **sanitizes and bounds every event**, so
//! retroactive text crosses the same trust boundary as live capture.
//!
//! (An earlier revision imported through the managed-workstream begin/finish
//! endpoints, but that populates the `ai-memory run` continuity ledger, not the
//! searchable memory pipeline — verified by a live smoke where the observation
//! count stayed zero. `/hook` replay is what makes the history recall-able.)
//!
//! Safety: the automatic path only ever bootstraps an **empty** project (never
//! overwrites an established one — hook capture from install-time forward and
//! backfill of before-install history do not overlap), and it runs at most once
//! per checkout (a local sentinel).
use std::path::Path;
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};
use ai_memory_hooks::capture_policy::metadata_only_body;
use ai_memory_workstream::{
LaunchRoots, ManagedHarness, OVERSIZED_RECORD_LOSS, build_launch_plan_with_env,
export_transcript, export_transcript_delta, export_transcript_range, find_native_session,
list_native_sessions, wait_for_transcript_flush,
};
use super::doctor::{SCANNED_HARNESSES, relocated_session_dir};
use super::run;
use super::transcript_capture::{EventCapture, TranscriptCapture};
use crate::config::Config;
use crate::http_client::{ServerEndpoint, get_json, post_json};
/// Circuit breaker on total imported events across the whole bootstrap. Once
/// reached, no further sessions are started; the remaining sessions are
/// reported as skipped rather than partially imported.
const MAX_EVENTS_TOTAL: usize = 50_000;
/// Newest local sessions to enumerate per harness before applying `--max-sessions`.
const PER_HARNESS_SCAN_LIMIT: usize = 200;
/// One `POST /hook/batch` request carries at most this many events — matches the
/// server's `MAX_HOOK_BATCH_ITEMS` so a batch is never rejected for size.
const HOOK_BATCH_ITEMS: usize = 256;
const HOOK_BATCH_BYTES: usize = 8 * 1024 * 1024;
/// The extension label backfilled non-user events (assistant/tool) are recorded
/// under, mirroring the companion importer's replay-through-`/hook` mechanism.
const BACKFILL_EXTENSION: &str = "ai-memory-backfill";
/// A local native session eligible for import.
#[derive(Debug, Clone)]
pub(crate) struct SessionRef {
pub(crate) harness: ManagedHarness,
pub(crate) native_session_id: String,
pub(crate) updated_at: SystemTime,
}
/// The outcome of a backfill run, and the JSON output shape.
#[derive(Debug, Default, Serialize)]
struct BackfillReport {
workspace: String,
project: String,
/// Sessions selected for import (after `--max-sessions`).
selected: usize,
/// Sessions actually imported.
imported_sessions: usize,
/// Events imported across all sessions.
imported_events: usize,
/// Sessions skipped because the total-events circuit breaker tripped.
skipped_for_cap: usize,
/// Per-session failures (import errors); the run continues past them.
failed_sessions: usize,
/// True when the store was already populated (or `--force` off) and nothing
/// was imported.
skipped_non_empty: bool,
/// True when this install's capture mode admits nothing from this
/// checkout (allowlist mode without a marker), so nothing was imported.
skipped_not_admitted: bool,
/// True for a `--dry-run` (planning only, no import).
dry_run: bool,
}
/// The captured side: `GET /admin/sessions/by-agent` — summing its counts tells
/// us whether the project store is empty.
#[derive(Debug, Deserialize)]
struct ByAgentResponse {
by_agent: Vec<AgentCount>,
}
#[derive(Debug, Deserialize)]
struct AgentCount {
#[allow(dead_code)]
agent: String,
sessions: u64,
}
/// Newest-first, then cap to `max_sessions`. Pure, so the selection/cap policy
/// is unit-tested without a server.
pub(crate) fn select_sessions(mut all: Vec<SessionRef>, max_sessions: usize) -> Vec<SessionRef> {
all.sort_by(|a, b| {
b.updated_at
.cmp(&a.updated_at)
.then_with(|| a.native_session_id.cmp(&b.native_session_id))
});
all.truncate(max_sessions);
all
}
/// Filename under `<data_dir>/backfill-state/` marking that the automatic
/// backfill has already been attempted for this checkout on this machine, so
/// the SessionStart trigger does not re-spawn on every boot. Keyed by a hash of
/// the working directory — which both the hook (before it spawns) and the
/// worker (which inherits the hook's cwd) compute identically without resolving
/// scope — so arbitrary paths stay path-safe.
pub(crate) fn sentinel_path(data_dir: &Path, cwd: &Path) -> PathBuf {
use sha2::{Digest, Sha256};
let mut hasher = Sha256::new();
hasher.update(cwd.as_os_str().as_encoded_bytes());
let digest = hasher.finalize();
data_dir.join("backfill-state").join(format!("{digest:x}"))
}
/// How long an in-progress marker blocks a new automatic backfill for the same
/// checkout. A worker that died without releasing it (killed, crashed host)
/// stops blocking after this, so the marker can never wedge the trigger.
const INFLIGHT_STALE_AFTER: std::time::Duration = std::time::Duration::from_secs(30 * 60);
/// Cap on the emptiness probe. Without it a saturated server leaves every
/// spawned backfill parked on an open connection, which piles more load on it.
const EMPTINESS_PROBE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
fn inflight_path(data_dir: &Path, cwd: &Path) -> PathBuf {
let mut path = sentinel_path(data_dir, cwd).into_os_string();
path.push(".inflight");
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 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);
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());
}
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);
}
// An unwritable state dir must not turn into a spawn storm.
Err(_) => return None,
}
}
None
})
.flatten()
}
/// 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, 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, &self.claim);
}
}
fn write_sentinel(data_dir: &Path, cwd: &Path) {
let path = sentinel_path(data_dir, cwd);
if let Some(parent) = path.parent() {
let _ = std::fs::create_dir_all(parent);
}
// Best-effort: a missing sentinel only means a redundant future probe, not
// incorrect data, so a write failure is not worth failing the import over.
let _ = std::fs::write(&path, b"");
}
/// The server this backfill delivers to.
///
/// A SessionStart-spawned run names the hook's own target: a server profile
/// (#992), whose stored token is the only credential it will present, or the
/// install-time hook URL, authenticated exactly like the hook's own events to
/// it: the persisted hook token, then OIDC. The config/env bearer is never
/// used there, because it may belong to a different server than the one the
/// hook is installed against. A manual run keeps resolving from config.
async fn backfill_endpoint(
config: &Config,
args: &crate::cli::BackfillArgs,
) -> Result<ServerEndpoint> {
if let Some(raw) = args.server_profile.as_deref() {
let name = crate::server_profiles::ProfileName::parse(raw)
.with_context(|| format!("`{raw}` is not a valid server profile name"))?;
let profile = crate::server_profiles::lookup(&config.data_dir, &name)
.map_err(|r| anyhow::anyhow!("server profile `{name}` was refused ({})", r.as_str()))?;
return Ok(ServerEndpoint::for_hook_target(
profile.url,
Some(profile.token),
));
}
if let Some(url) = args.server_url.as_deref() {
let static_token = crate::config::read_hook_auth_token(&config.data_dir);
let token = super::hook_spool::resolve_bearer(
&reqwest::Client::new(),
&config.data_dir,
static_token.as_deref(),
)
.await;
return Ok(ServerEndpoint::for_hook_target(url.to_owned(), token));
}
Ok(ServerEndpoint::from_config_resolving_auth(config).await)
}
/// Run the backfill.
///
/// # Errors
/// Returns an error when the scope cannot be resolved, the working directory
/// cannot be read, the server is unreachable for the emptiness check, or any
/// selected session fails to import. The report is emitted before import errors
/// are returned, including in JSON mode.
pub async fn run(config: &Config, args: crate::cli::BackfillArgs) -> Result<()> {
let cwd = std::env::current_dir().context("resolving the current working directory")?;
run_in(config, args, cwd).await
}
/// [`run`] for the checkout at `cwd`.
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_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 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
// machine regardless of outcome. Manual runs ignore both.
if args.auto && !config.backfill_on_start {
if !args.dry_run {
write_sentinel(&config.data_dir, &cwd);
}
return Ok(());
}
let (workspace, project) =
super::resolve_scope(config, args.workspace.as_deref(), args.project.as_deref())?;
let home = run::native_home(config).context("locating the local harness session stores")?;
let mut report = BackfillReport {
workspace: workspace.clone(),
project: project.clone(),
dry_run: args.dry_run,
..BackfillReport::default()
};
// The live hook's admission gate and `[capture] ignore_paths`, applied to
// the import as the hook applies them to live events. A checkout the hook
// would emit nothing for (allowlist capture mode without a marker) imports
// nothing, before the server is contacted at all.
let capture = TranscriptCapture::for_checkout(&config.data_dir, &cwd);
if !capture.admits_capture() {
report.skipped_not_admitted = true;
return finish(&args, &report);
}
let endpoint = backfill_endpoint(config, &args).await?;
// Emptiness gate. Only bootstrap a brand-new store; an established project
// is never retro-imported (that would duplicate hook-captured history).
if !args.force {
let empty = project_is_empty(&endpoint, &workspace, &project).await?;
if !empty {
report.skipped_non_empty = true;
// Mark attempted so the auto-trigger stops probing this checkout.
if !args.dry_run {
write_sentinel(&config.data_dir, &cwd);
}
return finish(&args, &report);
}
}
// Enumerate local sessions for this cwd across every supported harness.
let (candidates, _limit_hit) =
collect_local_sessions(&home, &cwd, args.session.as_deref()).await;
let selected = select_sessions(candidates, args.max_sessions.max(1));
report.selected = selected.len();
if args.dry_run {
return finish(&args, &report);
}
// Import each selected session, oldest-first so the imported history reads
// chronologically, until the total-events circuit breaker trips.
let mut session_dirs: Vec<(ManagedHarness, Option<PathBuf>)> = Vec::new();
for session in selected.into_iter().rev() {
if report.imported_events >= MAX_EVENTS_TOTAL {
report.skipped_for_cap += 1;
continue;
}
let session_dir = cached_session_dir(&mut session_dirs, session.harness, || {
import_session_dir(&home, &cwd, session.harness)
});
match import_one_with_session_dir(
&endpoint,
&workspace,
&project,
&home,
&cwd,
&capture,
&session,
session_dir.as_deref(),
)
.await
{
Ok(events) => {
report.imported_sessions += 1;
report.imported_events += events;
if let Some(claim) = &inflight_claim {
refresh_inflight(&config.data_dir, &cwd, claim);
}
}
Err(error) => {
report.failed_sessions += 1;
// Quiet suppresses the success summary, not failures: the
// detached worker's stderr is the operator's diagnostic log.
eprintln!(
"ai-memory: backfill of {} session {} failed: {error:#}",
session.harness.as_str(),
display_id(&session.native_session_id)
);
}
}
}
write_sentinel(&config.data_dir, &cwd);
finish(&args, &report)?;
if report.failed_sessions > 0 {
bail!(
"backfill failed to import {} of {} selected session(s)",
report.failed_sessions,
report.selected
);
}
Ok(())
}
/// Sum the server's per-agent session counts for this scope; zero means empty.
async fn project_is_empty(
endpoint: &ServerEndpoint,
workspace: &str,
project: &str,
) -> Result<bool> {
let probe = tokio::time::timeout(
EMPTINESS_PROBE_TIMEOUT,
get_json::<ByAgentResponse>(
endpoint,
"/admin/sessions/by-agent",
&[("workspace", workspace), ("project", project)],
),
)
.await
.unwrap_or_else(|_| {
Err(anyhow::anyhow!(
"the server did not answer within {}s",
EMPTINESS_PROBE_TIMEOUT.as_secs()
))
});
match probe {
Ok(response) => Ok(response.by_agent.iter().map(|c| c.sessions).sum::<u64>() == 0),
// A project that has never been written to does not exist server-side
// yet, so the no-create lookup answers 404 — which is the strongest
// possible "empty", and the common case for a first-time backfill.
Err(error) if super::is_scope_not_found(&error) => Ok(true),
// A multi-user server keeps `/admin/*` for the operator, so a
// developer's own key is refused here. Ask the grant-checked web API
// instead: it answers for the sessions this caller can see.
Err(error) if is_forbidden(&error) => {
project_is_empty_for_member(endpoint, workspace, project).await
}
Err(error) => Err(error).with_context(|| {
format!("checking whether {workspace}/{project} already has captured sessions")
}),
}
}
fn is_forbidden(error: &anyhow::Error) -> bool {
error
.downcast_ref::<crate::http_client::ServerResponseError>()
.is_some_and(|response| response.status() == reqwest::StatusCode::FORBIDDEN)
}
/// The sessions the web API lists for a project, open ones included.
#[derive(Debug, Deserialize)]
struct SessionListResponse {
sessions: Vec<serde_json::Value>,
}
/// [`project_is_empty`] through `GET /api/v1/workspaces/{ws}/projects/{p}/sessions`,
/// which any member may read. Its 404 means the project does not exist (or is
/// not this caller's to see); either way the hook ingress, not this check,
/// decides whether an import may write there. A 404 whose body is not a JSON
/// error — a server without the web API — stays an error: guessing "empty"
/// there could import history twice.
async fn project_is_empty_for_member(
endpoint: &ServerEndpoint,
workspace: &str,
project: &str,
) -> Result<bool> {
let path = member_sessions_path(workspace, project)?;
match get_json::<SessionListResponse>(
endpoint,
&path,
&[("limit", "1"), ("include_open", "true")],
)
.await
{
Ok(response) => Ok(response.sessions.is_empty()),
Err(error) if is_json_not_found(&error) => Ok(true),
Err(error) => Err(error).with_context(|| {
format!("checking whether {workspace}/{project} already has captured sessions")
}),
}
}
/// The path with each name percent-encoded as one segment, so a name can
/// never reach another route.
fn member_sessions_path(workspace: &str, project: &str) -> Result<String> {
let mut url = reqwest::Url::parse("http://placeholder/")?;
url.path_segments_mut()
.map_err(|()| anyhow::anyhow!("placeholder URL cannot hold a path"))?
.clear()
.extend([
"api",
"v1",
"workspaces",
workspace,
"projects",
project,
"sessions",
]);
Ok(url.path().to_owned())
}
fn is_json_not_found(error: &anyhow::Error) -> bool {
error
.downcast_ref::<crate::http_client::ServerResponseError>()
.is_some_and(|response| {
response.status() == reqwest::StatusCode::NOT_FOUND
&& serde_json::from_str::<serde_json::Value>(response.body())
.is_ok_and(|body| body.get("error").is_some())
})
}
/// Enumerate local native sessions for `cwd` across every scanned harness.
/// Read-only; a harness whose store is absent/unreadable contributes nothing.
///
/// Returns, alongside the sessions, the harnesses whose scan came back at
/// exactly [`PER_HARNESS_SCAN_LIMIT`] — a caller that cares about missing
/// older sessions (as opposed to `backfill`'s own newest-first + cap
/// selection, which does not) can surface that.
pub(crate) async fn collect_local_sessions(
home: &Path,
cwd: &Path,
only_session: Option<&str>,
) -> (Vec<SessionRef>, Vec<ManagedHarness>) {
collect_local_sessions_with(home, cwd, only_session, relocated_session_dir).await
}
/// [`collect_local_sessions`] with the relocation lookup passed in, for the
/// same reason as `doctor::scan_local_with`: tests pass `|_| None` so a
/// developer's `CLAUDE_CONFIG_DIR` cannot hide a fixture planted under a
/// temporary `$HOME`.
pub(crate) async fn collect_local_sessions_with(
home: &Path,
cwd: &Path,
only_session: Option<&str>,
session_dir_for: impl Fn(ManagedHarness) -> Option<PathBuf>,
) -> (Vec<SessionRef>, Vec<ManagedHarness>) {
let mut out = Vec::new();
let mut limit_hit = Vec::new();
for &harness in SCANNED_HARNESSES {
let session_dir = session_dir_for(harness);
if let Some(id) = only_session {
// A named recovery target may be older than every session in the
// bounded listing. Resolve it directly, with the adapter's same
// checkout checks, rather than broadening the automatic scan.
if let Ok(Some(session)) =
find_native_session(harness, home, cwd, session_dir.as_deref(), id)
{
out.push(SessionRef {
harness,
native_session_id: session.native_session_id,
updated_at: session.updated_at,
});
}
continue;
}
let Ok(sessions) = list_native_sessions(
harness,
home,
cwd,
session_dir.as_deref(),
PER_HARNESS_SCAN_LIMIT,
)
.await
else {
continue;
};
if sessions.len() >= PER_HARNESS_SCAN_LIMIT {
limit_hit.push(harness);
}
for session in sessions {
out.push(SessionRef {
harness,
native_session_id: session.native_session_id,
updated_at: session.updated_at,
});
}
}
(out, limit_hit)
}
/// One item in a `POST /hook/batch` request: the full hook URL (whose query the
/// server parses for event/agent/scope/session) plus the JSON body.
#[derive(Clone, Debug, Serialize)]
struct HookItem {
url: String,
body: serde_json::Value,
}
/// The server's `/hook/batch` acknowledgement (subset we act on).
#[derive(Debug, Deserialize)]
struct HookBatchAck {
accepted: usize,
results: Vec<HookBatchResult>,
#[serde(default)]
accepted_indices: Option<Vec<usize>>,
#[serde(default)]
failed_index: Option<usize>,
}
#[derive(Debug, Deserialize)]
struct HookBatchResult {
index: usize,
outcome: String,
}
fn acknowledged_items(ack: &HookBatchAck, items: &[&HookItem]) -> Result<Vec<usize>> {
let indices = ack
.accepted_indices
.clone()
.unwrap_or_else(|| (0..ack.accepted).collect());
if ack.accepted > items.len()
|| indices.iter().any(|index| *index >= items.len())
|| indices.windows(2).any(|pair| pair[0] >= pair[1])
|| ack.accepted
!= indices
.iter()
.enumerate()
.take_while(|(pos, index)| *pos == **index)
.count()
|| ack.results.len() != indices.len()
|| ack
.failed_index
.is_some_and(|index| index >= items.len() || indices.contains(&index))
{
bail!("invalid hook acknowledgement; keeping transcript for retry");
}
for (result, index) in ack.results.iter().zip(&indices) {
if result.index != *index {
bail!("hook acknowledgement result indices disagree");
}
let is_end = reqwest::Url::parse(&items[*index].url)?
.query_pairs()
.any(|(key, value)| key == "event" && value == "session-end");
match result.outcome.as_str() {
"stored" | "replayed" => {}
"ignored_end" if is_end => {}
"resumed" => bail!("hook processing resumed; rerun to confirm durable replay"),
outcome => {
bail!("hook item {index} was not durably stored ({outcome}); keeping transcript")
}
}
}
if let Some(index) = ack.failed_index {
bail!("hook processing failed at item {index}; keeping transcript for retry");
}
Ok(indices)
}
/// Import one native session by replaying its transcript through `/hook`, the
/// same ingress live capture uses — so the events become real sanitized
/// observations that consolidate into pages and are searchable, attributed to
/// the original harness and its native session id. Returns the number of
/// content events (messages/tools) imported. The server sanitizes and bounds
/// every event, so retroactive text crosses the same trust boundary as live
/// capture, and `capture` drops or strips tool events the checkout's
/// `[capture] ignore_paths` excludes before anything is posted.
#[cfg(all(test, unix))]
async fn import_one(
endpoint: &ServerEndpoint,
workspace: &str,
project: &str,
home: &Path,
cwd: &Path,
capture: &TranscriptCapture,
session: &SessionRef,
) -> Result<usize> {
let session_dir = import_session_dir(home, cwd, session.harness);
import_one_with_session_dir(
endpoint,
workspace,
project,
home,
cwd,
capture,
session,
session_dir.as_deref(),
)
.await
}
fn import_session_dir(home: &Path, cwd: &Path, harness: ManagedHarness) -> Option<PathBuf> {
let roots = LaunchRoots { home, cwd };
build_launch_plan_with_env(harness, None, Vec::new(), None, &[], Some(roots))
.ok()
.and_then(|plan| plan.session_dir)
}
fn cached_session_dir(
cache: &mut Vec<(ManagedHarness, Option<PathBuf>)>,
harness: ManagedHarness,
resolve: impl FnOnce() -> Option<PathBuf>,
) -> Option<PathBuf> {
if let Some((_, session_dir)) = cache.iter().find(|(cached, _)| *cached == harness) {
return session_dir.clone();
}
let session_dir = resolve();
cache.push((harness, session_dir.clone()));
session_dir
}
#[allow(clippy::too_many_arguments)]
async fn import_one_with_session_dir(
endpoint: &ServerEndpoint,
workspace: &str,
project: &str,
home: &Path,
cwd: &Path,
capture: &TranscriptCapture,
session: &SessionRef,
session_dir: Option<&Path>,
) -> Result<usize> {
import_exact_session(
endpoint,
workspace,
project,
home,
cwd,
session.harness,
&session.native_session_id,
session_dir,
None,
capture,
)
.await
}
#[allow(clippy::too_many_arguments)]
pub(crate) async fn import_exact_session_range(
endpoint: &ServerEndpoint,
workspace: &str,
project: &str,
home: &Path,
cwd: &Path,
harness: ManagedHarness,
native_session_id: &str,
recovery_interval_id: &str,
session_dir: Option<&Path>,
source_cursor: Option<&str>,
final_cursor: &str,
expected_digests: &[String],
capture: &TranscriptCapture,
) -> Result<usize> {
let _ = wait_for_transcript_flush(harness, home, cwd, session_dir, native_session_id).await;
let transcript = export_transcript_range(
harness,
home,
cwd,
session_dir,
native_session_id,
source_cursor,
final_cursor,
)
.await
.with_context(|| format!("reading the {} transcript", harness.as_str()))?;
let actual = ai_memory_workstream::transcript_interval_digests(&transcript.events);
if actual != expected_digests {
bail!("native transcript range no longer matches its exact ordered semantic identity");
}
import_exported_transcript(
endpoint,
workspace,
project,
harness,
native_session_id,
Some(recovery_interval_id),
transcript,
capture,
)
.await
}
#[allow(clippy::too_many_arguments)]
pub(crate) async fn import_exact_session(
endpoint: &ServerEndpoint,
workspace: &str,
project: &str,
home: &Path,
cwd: &Path,
harness: ManagedHarness,
native_session_id: &str,
session_dir: Option<&Path>,
source_cursor: Option<&str>,
capture: &TranscriptCapture,
) -> Result<usize> {
let _ = wait_for_transcript_flush(harness, home, cwd, session_dir, native_session_id).await;
let transcript = if let Some(cursor) = source_cursor {
export_transcript_delta(harness, home, cwd, session_dir, native_session_id, cursor).await
} else {
export_transcript(harness, home, cwd, session_dir, native_session_id, None).await
}
.with_context(|| format!("reading the {} transcript", harness.as_str()))?;
import_exported_transcript(
endpoint,
workspace,
project,
harness,
native_session_id,
None,
transcript,
capture,
)
.await
}
#[allow(clippy::too_many_arguments)]
async fn import_exported_transcript(
endpoint: &ServerEndpoint,
workspace: &str,
project: &str,
harness: ManagedHarness,
native_session_id: &str,
recovery_interval_id: Option<&str>,
transcript: ai_memory_workstream::ExportedTranscript,
capture: &TranscriptCapture,
) -> Result<usize> {
let sid = native_session_id;
let agent = harness.agent_kind().as_str();
let resolved = resolve_occurred_at(&transcript.events);
let mut items = Vec::with_capacity(transcript.events.len() + 2);
items.push(hook_item(
endpoint,
workspace,
project,
agent,
"session-start",
sid,
&replay_ingest_key(recovery_interval_id, sid, "session-start", "boundary"),
None,
serde_json::json!({ "session_id": sid, "occurred_at": resolved.earliest }),
)?);
let mut content = 0usize;
let captures = capture.decide(&transcript.events);
for ((event, occurred_at), capture) in transcript
.events
.iter()
.zip(&resolved.per_event)
.zip(&captures)
{
if let Some(mapped) = map_event(
recovery_interval_id,
sid,
event,
occurred_at.as_deref(),
capture,
) {
items.push(hook_item(
endpoint,
workspace,
project,
agent,
&mapped.event,
sid,
&mapped.ingest_key,
mapped.source_event.as_deref(),
mapped.body,
)?);
content += 1;
}
}
items.push(hook_item(
endpoint,
workspace,
project,
agent,
"session-end",
sid,
&replay_ingest_key(recovery_interval_id, sid, "session-end", "boundary"),
None,
serde_json::json!({ "session_id": sid, "occurred_at": resolved.latest }),
)?);
post_hook_items(endpoint, &items).await?;
// The import is partial by design here, so it is reported on stderr even
// under `--quiet`: the automatic worker's stderr is the operator's log.
let skipped = transcript
.losses
.iter()
.filter(|loss| loss.starts_with(OVERSIZED_RECORD_LOSS))
.count();
if skipped > 0 {
eprintln!(
"ai-memory: {} session {}: skipped {skipped} oversized transcript record(s); the rest was imported",
harness.as_str(),
run::display_session_id(display_id(sid))
);
}
Ok(content)
}
/// Replay only the user prompts of one session the server already knows,
/// for harnesses whose live hooks carry no prompt event (Antigravity CLI).
/// `finalize-session` sends these before its synthetic `session-end`, so the
/// summary page and the automatic handoff are built with the prompts.
///
/// No session boundaries are sent: the caller owns the `session-end`, and a
/// keyed one would be deduplicated on a later `--reopen`. Each prompt carries
/// the same [`replay_ingest_key`] that `backfill` mints for that event, so
/// repeated finalizes (and a backfill of the same session) store it once.
/// Returns the number of prompts sent.
#[allow(clippy::too_many_arguments)]
pub(crate) async fn replay_session_prompts(
endpoint: &ServerEndpoint,
workspace: &str,
project: &str,
home: &Path,
cwd: &Path,
harness: ManagedHarness,
native_session_id: &str,
) -> Result<usize> {
let transcript = export_transcript(harness, home, cwd, None, native_session_id, None)
.await
.with_context(|| format!("reading the {} transcript", harness.as_str()))?;
let items = prompt_hook_items(
endpoint,
workspace,
project,
harness,
native_session_id,
&transcript.events,
)?;
if !items.is_empty() {
post_hook_items(endpoint, &items).await?;
}
Ok(items.len())
}
/// The `user-prompt` hook items of a transcript, in transcript order, each
/// dated at its own event time and keyed with [`replay_ingest_key`]. Every
/// other event kind is dropped.
fn prompt_hook_items(
endpoint: &ServerEndpoint,
workspace: &str,
project: &str,
harness: ManagedHarness,
native_session_id: &str,
events: &[NewWorkstreamEvent],
) -> Result<Vec<HookItem>> {
let agent = harness.agent_kind().as_str();
let resolved = resolve_occurred_at(events);
let mut items = Vec::new();
for (event, occurred_at) in events.iter().zip(&resolved.per_event) {
// Only user prompts are forwarded below, and `[capture] ignore_paths`
// governs file-tool events (the live hook does not filter prompts
// either), so no capture decision applies here.
let Some(mapped) = map_event(
None,
native_session_id,
event,
occurred_at.as_deref(),
&EventCapture::Keep,
) else {
continue;
};
if mapped.event != "user-prompt" {
continue;
}
items.push(hook_item(
endpoint,
workspace,
project,
agent,
&mapped.event,
native_session_id,
&mapped.ingest_key,
None,
mapped.body,
)?);
}
Ok(items)
}
/// Per-event `occurred_at` resolution for one transcript, plus the session's
/// overall boundary times.
struct ResolvedOccurredAt {
/// Effective `occurred_at` for each event, in transcript order (RFC 3339).
per_event: Vec<Option<String>>,
/// The earliest valid event time — the session-start's `occurred_at`.
/// A transcript is not guaranteed to be time-sorted (a reordered or
/// clock-skewed import), so the first *entry* is not reliably the
/// earliest *time*.
earliest: Option<String>,
/// The latest valid event time — the session-end's `occurred_at`, same
/// reasoning as `earliest`.
latest: Option<String>,
}
/// Resolve each event's effective `occurred_at`, letting one missing or
/// unparsable own timestamp inherit the nearest preceding *valid* one; an
/// event before the first valid timestamp inherits that first one instead of
/// staying unresolved (there is nothing earlier to inherit from). A value
/// that fails to parse as RFC 3339 is treated exactly like a missing one — it
/// never reaches the hook body, so a malformed transcript timestamp cannot
/// masquerade as a validated one downstream.
fn resolve_occurred_at(events: &[NewWorkstreamEvent]) -> ResolvedOccurredAt {
let valid: Vec<Option<jiff::Timestamp>> = events
.iter()
.map(|event| {
event
.occurred_at
.as_deref()
.and_then(|s| s.parse::<jiff::Timestamp>().ok())
})
.collect();
let mut per_event: Vec<Option<jiff::Timestamp>> = Vec::with_capacity(events.len());
let mut last_valid: Option<jiff::Timestamp> = None;
for ts in &valid {
if ts.is_some() {
last_valid = *ts;
}
per_event.push(last_valid);
}
// Backward-fill the leading gap: events before the first valid timestamp
// had nothing preceding them to inherit above.
if let Some(first_valid) = valid.iter().copied().flatten().next() {
for slot in per_event.iter_mut() {
match slot {
Some(_) => break,
None => *slot = Some(first_valid),
}
}
}
let (earliest, latest) = valid.into_iter().flatten().fold(
(None, None),
|(min, max): (Option<jiff::Timestamp>, Option<jiff::Timestamp>), ts| {
(
Some(min.map_or(ts, |m| m.min(ts))),
Some(max.map_or(ts, |m| m.max(ts))),
)
},
);
ResolvedOccurredAt {
per_event: per_event
.into_iter()
.map(|ts| ts.map(|t| t.to_string()))
.collect(),
earliest: earliest.map(|t| t.to_string()),
latest: latest.map(|t| t.to_string()),
}
}
/// A transcript event mapped to its `/hook` shape.
struct MappedEvent {
event: String,
source_event: Option<String>,
ingest_key: String,
body: serde_json::Value,
}
/// Map one transcript event to a hook event. User messages become the canonical
/// `user-prompt` observation; every other content-bearing event is recorded as
/// a backfill extension observation. Non-content boundary events (compaction,
/// checkpoint, annotation) are dropped — they are not session content.
///
/// `occurred_at` (RFC 3339), already resolved by the caller, rides in the hook
/// body so the imported observation is dated at the transcript's own event
/// time rather than at import time.
///
/// `capture` is the checkout's capture decision for this event: a dropped
/// event maps to nothing, and a metadata-only one carries the hook's
/// metadata-only body with its `_ai_memory_capture` protocol, which the server
/// validates and rebuilds from its allowlist exactly as for a live hook. A kept
/// event carries no protocol: its body is a normalized transcript record, not
/// the native tool payload the server's re-inspection reads, so a claim would
/// be judged against the wrong schema and stripped; the server never receives
/// the ignore patterns, so the client's decision is the only one possible.
/// An unrecognized tool's event carries only its family, as the live server
/// stores for an unknown-family tool, never its arguments or output.
fn map_event(
recovery_interval_id: Option<&str>,
session_id: &str,
event: &NewWorkstreamEvent,
occurred_at: Option<&str>,
capture: &EventCapture,
) -> Option<MappedEvent> {
let content = event.content.trim();
if content.is_empty() {
return None;
}
let decision = match capture {
EventCapture::Drop => return None,
EventCapture::MetadataOnly(decision) => Some(decision),
EventCapture::Keep | EventCapture::Unrecognized => None,
};
let role = event.role.as_deref().unwrap_or("");
let ingest_key = replay_ingest_key(
recovery_interval_id,
session_id,
event.kind.as_str(),
&event.event_id,
);
match event.kind {
WorkstreamEventKind::Message if role == "user" || role == "human" => Some(MappedEvent {
event: "user-prompt".to_string(),
source_event: None,
ingest_key,
body: serde_json::json!({
"session_id": session_id,
"prompt": event.content,
"occurred_at": occurred_at,
}),
}),
WorkstreamEventKind::Message
| WorkstreamEventKind::ToolCall
| WorkstreamEventKind::ToolResult => {
let source_event = match event.kind {
WorkstreamEventKind::ToolCall => "tool_call".to_string(),
WorkstreamEventKind::ToolResult => "tool_result".to_string(),
_ if role.is_empty() => "message".to_string(),
_ => format!("{role}-message"),
};
let body = match decision {
Some(decision) => {
let mut body = metadata_only_body(Some(session_id), None, decision);
if let Some(object) = body.as_object_mut() {
object.insert("occurred_at".into(), occurred_at.into());
}
body
}
None if matches!(capture, EventCapture::Unrecognized) => {
let outcome = if event.kind == WorkstreamEventKind::ToolResult {
"\noutcome: unknown"
} else {
""
};
serde_json::json!({
"session_id": session_id,
"title": "tool unknown",
"message": format!("tool_family: unknown{outcome}"),
"occurred_at": occurred_at,
})
}
None => serde_json::json!({
"session_id": session_id,
"title": first_line(content),
"message": event.content,
"occurred_at": occurred_at,
}),
};
Some(MappedEvent {
event: format!("backfill.{source_event}"),
source_event: Some(source_event),
ingest_key,
body,
})
}
WorkstreamEventKind::Compaction
| WorkstreamEventKind::Checkpoint
| WorkstreamEventKind::Annotation => None,
}
}
/// A short one-line title from the event content.
fn first_line(content: &str) -> String {
let line = content.lines().next().unwrap_or("").trim();
let capped: String = line.chars().take(120).collect();
if capped.is_empty() {
"(backfilled event)".to_string()
} else {
capped
}
}
fn replay_ingest_key(
recovery_interval_id: Option<&str>,
session_id: &str,
kind: &str,
event_id: &str,
) -> String {
use sha2::{Digest as _, Sha256};
let mut hasher = Sha256::new();
for value in [
recovery_interval_id.unwrap_or_default(),
session_id,
kind,
event_id,
] {
hasher.update(value.len().to_be_bytes());
hasher.update(value.as_bytes());
}
let digest = format!("{:x}", hasher.finalize());
format!("recovery_{}", &digest[..55])
}
/// Build a `/hook` URL whose query the server parses for event/agent/scope. The
/// URL is data the batch item carries, not the request target (that is
/// `/hook/batch`), so it is built against this server's origin exactly as a live
/// hook would have spooled it.
#[allow(clippy::too_many_arguments)]
fn hook_item(
endpoint: &ServerEndpoint,
workspace: &str,
project: &str,
agent: &str,
event: &str,
session_id: &str,
ingest_key: &str,
source_event: Option<&str>,
body: serde_json::Value,
) -> Result<HookItem> {
let mut url = reqwest::Url::parse(&endpoint.build_url("/hook"))
.context("building the hook URL for backfill")?;
{
let mut query = url.query_pairs_mut();
query
.append_pair("event", event)
.append_pair("agent", agent)
.append_pair("workspace", workspace)
.append_pair("project", project)
.append_pair("project_src", "marker")
.append_pair("session_id", session_id)
.append_pair("ingest_key", ingest_key);
if let Some(source_event) = source_event {
query
.append_pair("extension", BACKFILL_EXTENSION)
.append_pair("source_event", source_event);
}
}
Ok(HookItem {
url: url.into(),
body,
})
}
/// POST events in server-sized batches. Recovery requires a modern per-item
/// acknowledgement and fails closed on partial or terminal-drop outcomes.
fn hook_batch_end(items: &[HookItem], offset: usize) -> Result<usize> {
let mut end = offset;
let mut bytes = 2_usize;
while end < items.len() && end - offset < HOOK_BATCH_ITEMS {
let item_bytes = serde_json::to_vec(&items[end])?.len().saturating_add(1);
if item_bytes > HOOK_BATCH_BYTES {
bail!("one sanitized hook item exceeds the recovery request byte limit");
}
if end > offset && bytes.saturating_add(item_bytes) > HOOK_BATCH_BYTES {
break;
}
bytes = bytes.saturating_add(item_bytes);
end += 1;
}
Ok(end)
}
async fn post_hook_items(endpoint: &ServerEndpoint, items: &[HookItem]) -> Result<()> {
let mut offset = 0_usize;
while offset < items.len() {
let end = hook_batch_end(items, offset)?;
let chunk = &items[offset..end];
let mut stalled = 0u32;
loop {
let batch: Vec<&HookItem> = chunk.iter().collect();
let ack: HookBatchAck = post_json(endpoint, "/hook/batch", &batch)
.await
.context("replaying transcript events through /hook/batch")?;
let accepted = acknowledged_items(&ack, &batch)?;
if accepted.len() == batch.len() {
break;
}
if accepted.is_empty() {
stalled += 1;
if stalled >= 5 {
bail!(
"server acknowledged none of a hook batch after {stalled} attempts \
(rate limited or saturated); rerun to resume"
);
}
tokio::time::sleep(Duration::from_millis(200 * u64::from(stalled))).await;
continue;
}
bail!(
"server acknowledged only {} of {} transcript items; keeping transcript for a safe retry",
accepted.len(),
batch.len()
);
}
offset = end;
}
Ok(())
}
fn finish(args: &crate::cli::BackfillArgs, report: &BackfillReport) -> Result<()> {
if args.json {
println!("{}", serde_json::to_string_pretty(report)?);
return Ok(());
}
if args.quiet {
return Ok(());
}
if report.skipped_not_admitted {
println!(
"ai-memory: capture mode is allowlist and this checkout has no .ai-memory.toml marker opting in (or its marker is unreadable) — nothing to backfill for {}/{}.",
report.workspace, report.project
);
return Ok(());
}
if report.skipped_non_empty {
println!(
"ai-memory: {}/{} already has captured sessions — nothing to backfill (use --force to import anyway).",
report.workspace, report.project
);
return Ok(());
}
if report.dry_run {
println!(
"ai-memory: would import {} local session(s) into {}/{} (dry run).",
report.selected, report.workspace, report.project
);
return Ok(());
}
if report.imported_sessions == 0 && report.failed_sessions == 0 {
println!(
"ai-memory: no local session history found to backfill for {}/{}.",
report.workspace, report.project
);
return Ok(());
}
let mut line = format!(
"📼 ai-memory imported {} prior local session(s) (~{} events) for {}/{}.",
report.imported_sessions, report.imported_events, report.workspace, report.project
);
if report.failed_sessions > 0 {
line.push_str(&format!(" {} session(s) failed.", report.failed_sessions));
}
if report.skipped_for_cap > 0 {
line.push_str(&format!(
" {} older session(s) skipped (import cap).",
report.skipped_for_cap
));
}
line.push_str(" Opt out with AI_MEMORY_BACKFILL_ON_START=false.");
println!("{line}");
Ok(())
}
fn display_id(id: &str) -> &str {
id.get(..8).unwrap_or(id)
}
#[cfg(test)]
mod tests {
use super::*;
use std::time::Duration;
fn session(id: &str, secs_ago: u64) -> SessionRef {
SessionRef {
harness: ManagedHarness::Claude,
native_session_id: id.to_string(),
updated_at: SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000 - secs_ago),
}
}
#[test]
fn select_sessions_keeps_the_newest_up_to_the_cap() {
let all = vec![session("old", 300), session("new", 10), session("mid", 100)];
let picked = select_sessions(all, 2);
assert_eq!(
picked
.iter()
.map(|s| s.native_session_id.as_str())
.collect::<Vec<_>>(),
vec!["new", "mid"],
"newest first, capped to 2"
);
}
#[test]
fn session_directory_resolution_is_cached_per_harness() {
let mut cache = Vec::new();
let mut calls = 0;
let first = cached_session_dir(&mut cache, ManagedHarness::Crush, || {
calls += 1;
Some(PathBuf::from("crush-data"))
});
let second = cached_session_dir(&mut cache, ManagedHarness::Crush, || {
calls += 1;
Some(PathBuf::from("wrong"))
});
assert_eq!(first, Some(PathBuf::from("crush-data")));
assert_eq!(second, first);
assert_eq!(calls, 1);
}
#[test]
fn member_sessions_path_encodes_each_name_as_one_segment() {
assert_eq!(
member_sessions_path("team", "app").unwrap(),
"/api/v1/workspaces/team/projects/app/sessions"
);
assert_eq!(
member_sessions_path("a/b", "c d?").unwrap(),
"/api/v1/workspaces/a%2Fb/projects/c%20d%3F/sessions"
);
}
#[test]
fn select_sessions_cap_zero_is_raised_to_one_by_caller_contract() {
// The caller passes max_sessions.max(1); select_sessions itself honors
// whatever it is given, so a literal 0 yields nothing.
assert!(select_sessions(vec![session("a", 1)], 0).is_empty());
assert_eq!(select_sessions(vec![session("a", 1)], 1).len(), 1);
}
/// #1287: a burst of SessionStart hooks in one directory must spawn one
/// backfill. Only the first claim wins; another directory is unaffected.
#[test]
fn only_one_session_start_claims_the_backfill_per_checkout() {
let data = tempfile::tempdir().unwrap();
let app = Path::new("/home/me/projects/app");
let other = Path::new("/home/me/projects/other");
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"
);
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
/// checkout forever.
#[test]
fn a_stale_inflight_marker_is_replaced() {
let data = tempfile::tempdir().unwrap();
let cwd = Path::new("/home/me/projects/app");
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();
assert!(
claim_inflight(data.path(), cwd).is_some(),
"stale marker is taken over"
);
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 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");
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()
.write(true)
.open(&marker)
.unwrap()
.set_modified(old)
.unwrap();
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(),
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
/// marker in place.
#[test]
fn a_stale_takeover_leaves_one_marker_and_no_debris() {
let data = tempfile::tempdir().unwrap();
let cwd = Path::new("/home/me/projects/app");
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();
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(), 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]
fn sentinel_path_is_cwd_specific_and_path_safe() {
let dir = Path::new("/data");
let a = sentinel_path(dir, Path::new("/home/me/projects/app"));
let b = sentinel_path(dir, Path::new("/home/me/projects/other"));
let c = sentinel_path(dir, Path::new("/home/me/projects/app"));
assert_eq!(a, c, "same cwd -> same path");
assert_ne!(a, b, "different cwd -> different path");
assert!(
a.starts_with("/data/backfill-state/"),
"under the data dir: {a:?}"
);
// A path with separators hashes to a single flat, path-safe leaf.
assert_eq!(
a.strip_prefix("/data/backfill-state/")
.unwrap()
.components()
.count(),
1,
"the hashed leaf must be a single path component: {a:?}"
);
}
fn event(kind: WorkstreamEventKind, role: Option<&str>, content: &str) -> NewWorkstreamEvent {
NewWorkstreamEvent {
event_id: "evt-1".to_string(),
agent: ai_memory_core::AgentKind::ClaudeCode,
native_session_id: "sid".to_string(),
source_record_id: None,
kind,
role: role.map(str::to_string),
content: content.to_string(),
occurred_at: None,
metadata: serde_json::Value::Null,
}
}
#[test]
fn user_message_maps_to_the_canonical_user_prompt() {
let m = map_event(
None,
"sid",
&event(WorkstreamEventKind::Message, Some("user"), "do the thing"),
Some("2026-09-10T12:00:00Z"),
&EventCapture::Keep,
)
.expect("user message maps");
assert_eq!(m.event, "user-prompt");
assert!(
m.source_event.is_none(),
"user-prompt is a lifecycle event, not an extension"
);
assert_eq!(m.body["prompt"], "do the thing");
assert_eq!(m.body["occurred_at"], "2026-09-10T12:00:00Z");
assert_eq!(
m.ingest_key,
replay_ingest_key(None, "sid", "message", "evt-1"),
"ingest key is stable per source event"
);
assert_eq!(m.ingest_key.len(), 64);
assert!(
m.ingest_key
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'-' || byte == b'_')
);
}
#[test]
fn replay_keys_are_deterministic_valid_and_bounded_for_long_native_ids() {
let session = "native:".repeat(200);
let event = "event/with spaces:".repeat(200);
let first = replay_ingest_key(None, &session, "message", &event);
let second = replay_ingest_key(None, &session, "message", &event);
assert_eq!(first, second);
assert_eq!(first.len(), 64);
assert!(first.starts_with("recovery_"));
assert!(
first
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'-' || byte == b'_')
);
assert_ne!(
first,
replay_ingest_key(None, &session, "tool_call", &event)
);
let other_interval = replay_ingest_key(Some("journal-2"), &session, "message", &event);
assert_ne!(first, other_interval);
assert_eq!(
other_interval,
replay_ingest_key(Some("journal-2"), &session, "message", &event),
"one journal interval must replay stably"
);
}
#[test]
fn prompt_replay_keeps_only_user_prompts_with_backfill_keys() {
let endpoint = ServerEndpoint::for_hook_target("http://127.0.0.1:1".into(), None);
let with_id = |id: &str, mut e: NewWorkstreamEvent| {
e.event_id = id.to_string();
e
};
let events = [
with_id(
"p1",
event(WorkstreamEventKind::Message, Some("user"), "first ask"),
),
with_id(
"a1",
event(WorkstreamEventKind::Message, Some("assistant"), "an answer"),
),
with_id(
"t1",
event(WorkstreamEventKind::ToolCall, None, "run tests"),
),
with_id(
"p2",
event(WorkstreamEventKind::Message, Some("user"), "second ask"),
),
];
let items = prompt_hook_items(
&endpoint,
"ws",
"proj",
ManagedHarness::Antigravity,
"sid",
&events,
)
.unwrap();
assert_eq!(items.len(), 2, "only the two user prompts are replayed");
for (item, (id, prompt)) in items
.iter()
.zip([("p1", "first ask"), ("p2", "second ask")])
{
let url = reqwest::Url::parse(&item.url).unwrap();
let query = |name: &str| {
url.query_pairs()
.find(|(key, _)| key == name)
.map(|(_, value)| value.into_owned())
};
assert_eq!(query("event").as_deref(), Some("user-prompt"));
assert_eq!(query("agent").as_deref(), Some("antigravity-cli"));
assert_eq!(
query("extension"),
None,
"a prompt is not a backfill extension"
);
assert_eq!(
query("ingest_key"),
Some(replay_ingest_key(None, "sid", "message", id)),
"the key matches what backfill mints for the same event"
);
assert_eq!(item.body["prompt"], prompt);
}
}
#[test]
fn recovery_hook_batches_respect_count_and_serialized_byte_limits() {
let endpoint = ServerEndpoint::for_hook_target("http://127.0.0.1:1".into(), None);
let make = |size| HookItem {
url: endpoint.build_url("/hook?event=user-prompt"),
body: serde_json::json!({"prompt": "x".repeat(size)}),
};
let items = (0..HOOK_BATCH_ITEMS + 1)
.map(|_| make(1))
.collect::<Vec<_>>();
assert_eq!(hook_batch_end(&items, 0).unwrap(), HOOK_BATCH_ITEMS);
let large = vec![make(HOOK_BATCH_BYTES / 2), make(HOOK_BATCH_BYTES / 2)];
assert_eq!(hook_batch_end(&large, 0).unwrap(), 1);
assert!(
hook_batch_end(&[make(HOOK_BATCH_BYTES)], 0)
.unwrap_err()
.to_string()
.contains("exceeds")
);
}
#[test]
fn acknowledgement_requires_results_and_rejects_terminal_drops() {
let endpoint = ServerEndpoint::for_hook_target("http://127.0.0.1:1".into(), None);
let item = hook_item(
&endpoint,
"ws",
"project",
"claude-code",
"user-prompt",
"sid",
"key",
None,
serde_json::json!({"session_id": "sid", "prompt": "hello"}),
)
.unwrap();
let items = [&item];
for outcome in [
"dropped_policy",
"dropped_subagent",
"dropped_unauthorized",
"dropped_collision",
"dropped_invalid",
"resumed",
] {
let ack = HookBatchAck {
accepted: 1,
results: vec![HookBatchResult {
index: 0,
outcome: outcome.into(),
}],
accepted_indices: None,
failed_index: None,
};
assert!(acknowledged_items(&ack, &items).is_err(), "{outcome}");
}
let legacy = HookBatchAck {
accepted: 1,
results: Vec::new(),
accepted_indices: None,
failed_index: None,
};
assert!(acknowledged_items(&legacy, &items).is_err());
}
#[test]
fn acknowledgement_allows_stored_replayed_and_only_terminal_ignored_end() {
let endpoint = ServerEndpoint::for_hook_target("http://127.0.0.1:1".into(), None);
let make = |event| {
hook_item(
&endpoint,
"ws",
"project",
"claude-code",
event,
"sid",
"key",
None,
serde_json::json!({"session_id": "sid"}),
)
.unwrap()
};
let prompt = make("user-prompt");
let end = make("session-end");
for outcome in ["stored", "replayed"] {
let ack = HookBatchAck {
accepted: 1,
results: vec![HookBatchResult {
index: 0,
outcome: outcome.into(),
}],
accepted_indices: Some(vec![0]),
failed_index: None,
};
assert_eq!(acknowledged_items(&ack, &[&prompt]).unwrap(), vec![0]);
}
let ignored = HookBatchAck {
accepted: 1,
results: vec![HookBatchResult {
index: 0,
outcome: "ignored_end".into(),
}],
accepted_indices: Some(vec![0]),
failed_index: None,
};
assert!(acknowledged_items(&ignored, &[&prompt]).is_err());
assert_eq!(acknowledged_items(&ignored, &[&end]).unwrap(), vec![0]);
}
#[tokio::test]
async fn real_hook_router_replay_is_idempotent_and_reports_outcomes() {
use ai_memory_core::{ActiveProject, IngestMetrics, Sanitizer, SessionId};
use ai_memory_hooks::{
CwdProbes, HookState, IngestGates, IngestRateLimiter, ProjectCacheStore,
SubagentSessionSet, hook_router,
};
use ai_memory_store::Store;
use ai_memory_wiki::Wiki;
use std::sync::Arc;
use tower::ServiceExt as _;
let temp = tempfile::tempdir().unwrap();
let store = Store::open(temp.path()).unwrap();
let workspace_id = store.writer.get_or_create_workspace("ws").await.unwrap();
let project_id = store
.writer
.get_or_create_project(workspace_id, "project", None)
.await
.unwrap();
let state = HookState {
workspace_id,
project_id,
writer: store.writer.clone(),
reader: store.reader.clone(),
wiki: Wiki::new(temp.path(), store.writer.clone()).unwrap(),
consolidator: None,
sanitizer: Sanitizer::default(),
project_cache: Arc::new(tokio::sync::Mutex::new(ProjectCacheStore::default())),
active_project: ActiveProject::new(),
ingest_metrics: Arc::new(IngestMetrics::default()),
ingest_semaphore: Arc::new(tokio::sync::Semaphore::new(16)),
ingest_gates: IngestGates::default(),
cwd_probes: CwdProbes::default(),
ingest_rate: Arc::new(tokio::sync::Mutex::new(IngestRateLimiter::disabled())),
consolidate_on_session_end: false,
session_consolidation_notify: None,
profile_notify: None,
capture_assistant_enabled: false,
claim_handoff_on_session_start: true,
create_handoff_on_session_end: false,
subagent_sessions: Arc::new(tokio::sync::Mutex::new(SubagentSessionSet::default())),
home_dir: None,
trusted_proxy_identity: false,
per_user_slots: false,
mid_session_routing: ai_memory_core::MidSessionRouting::default(),
profile: ai_memory_core::profile::ProfileSettings::default(),
ingest_drop_list: ai_memory_hooks::IngestDropList::default(),
record_tool_names: false,
skip_wiki_checkpoints: false,
};
let endpoint = ServerEndpoint::for_hook_target("http://localhost".into(), None);
let sid = "native-session-with-a-very-long-identifier-that-would-break-the-old-key";
let recovery_interval_id = Some("journal");
let items = vec![
hook_item(
&endpoint,
"ws",
"project",
"claude-code",
"session-start",
sid,
&replay_ingest_key(recovery_interval_id, sid, "session-start", "boundary"),
None,
serde_json::json!({"session_id": sid, "cwd": "/repo"}),
)
.unwrap(),
hook_item(
&endpoint,
"ws",
"project",
"claude-code",
"user-prompt",
sid,
&replay_ingest_key(recovery_interval_id, sid, "message", "event-1"),
None,
serde_json::json!({"session_id": sid, "cwd": "/repo", "prompt": "same prompt"}),
)
.unwrap(),
hook_item(
&endpoint,
"ws",
"project",
"claude-code",
"session-end",
sid,
&replay_ingest_key(recovery_interval_id, sid, "session-end", "boundary"),
None,
serde_json::json!({"session_id": sid, "cwd": "/repo"}),
)
.unwrap(),
];
let spool = crate::commands::hook_spool::spool_dir(temp.path());
let overlapping = hook_item(
&endpoint,
"ws",
"project",
"claude-code",
"user-prompt",
sid,
"random_live_key",
None,
serde_json::json!({"session_id": sid, "cwd": "/repo", "prompt": "same prompt"}),
)
.unwrap();
crate::commands::hook_spool::enqueue(
&spool,
&crate::commands::hook_spool::entry_for(
overlapping.url,
overlapping.body.to_string(),
None,
false,
),
)
.unwrap();
let quarantine = crate::commands::hook_spool::quarantine_session_entries(
&Config::default(),
&spool,
"journal",
0,
u64::MAX,
&endpoint.identity(),
"claude-code",
"ws",
"project",
Path::new("/repo"),
sid,
)
.unwrap();
assert_eq!(crate::commands::hook_spool::spool_len(&spool), 0);
let body = serde_json::to_vec(&items).unwrap();
let first = hook_router(state.clone())
.oneshot(
axum::http::Request::post("/hook/batch")
.header("content-type", "application/json")
.body(axum::body::Body::from(body.clone()))
.unwrap(),
)
.await
.unwrap();
assert_eq!(first.status(), axum::http::StatusCode::OK);
let first: HookBatchAck = serde_json::from_slice(
&axum::body::to_bytes(first.into_body(), usize::MAX)
.await
.unwrap(),
)
.unwrap();
assert_eq!(
acknowledged_items(&first, &items.iter().collect::<Vec<_>>())
.unwrap()
.len(),
3
);
let second = hook_router(state.clone())
.oneshot(
axum::http::Request::post("/hook/batch")
.header("content-type", "application/json")
.body(axum::body::Body::from(body))
.unwrap(),
)
.await
.unwrap();
let second: HookBatchAck = serde_json::from_slice(
&axum::body::to_bytes(second.into_body(), usize::MAX)
.await
.unwrap(),
)
.unwrap();
assert!(
second
.results
.iter()
.any(|result| result.outcome == "replayed")
);
assert!(
second
.results
.iter()
.any(|result| result.outcome == "ignored_end")
);
let observations = store
.reader
.observations_for_session(SessionId::from_native(sid))
.await
.unwrap();
assert_eq!(observations.len(), 3);
assert_eq!(
observations
.iter()
.filter(|observation| observation.body == "same prompt")
.count(),
1
);
quarantine.complete().unwrap();
}
/// Two sequential offline intervals on one resumed native session: the
/// second interval's journal id gives its boundary and content keys their
/// own identity, so its session-end is STORED (re-closing the session with
/// its end-of-session effects) instead of being short-circuited as a
/// replay of the first interval's end, while re-running either interval
/// stays a pure replay.
#[tokio::test]
async fn two_sequential_recovery_intervals_on_one_resumed_session_replay_exactly_once() {
use ai_memory_core::{ActiveProject, IngestMetrics, ObservationKind, Sanitizer, SessionId};
use ai_memory_hooks::{
CwdProbes, HookState, IngestGates, IngestRateLimiter, ProjectCacheStore,
SubagentSessionSet, hook_router,
};
use ai_memory_store::Store;
use ai_memory_wiki::Wiki;
use std::sync::Arc;
use tower::ServiceExt as _;
let temp = tempfile::tempdir().unwrap();
let store = Store::open(temp.path()).unwrap();
let workspace_id = store.writer.get_or_create_workspace("ws").await.unwrap();
let project_id = store
.writer
.get_or_create_project(workspace_id, "project", None)
.await
.unwrap();
let state = HookState {
workspace_id,
project_id,
writer: store.writer.clone(),
reader: store.reader.clone(),
wiki: Wiki::new(temp.path(), store.writer.clone()).unwrap(),
consolidator: None,
sanitizer: Sanitizer::default(),
project_cache: Arc::new(tokio::sync::Mutex::new(ProjectCacheStore::default())),
active_project: ActiveProject::new(),
ingest_metrics: Arc::new(IngestMetrics::default()),
ingest_semaphore: Arc::new(tokio::sync::Semaphore::new(16)),
ingest_gates: IngestGates::default(),
cwd_probes: CwdProbes::default(),
ingest_rate: Arc::new(tokio::sync::Mutex::new(IngestRateLimiter::disabled())),
consolidate_on_session_end: false,
session_consolidation_notify: None,
profile_notify: None,
capture_assistant_enabled: false,
claim_handoff_on_session_start: true,
create_handoff_on_session_end: false,
subagent_sessions: Arc::new(tokio::sync::Mutex::new(SubagentSessionSet::default())),
home_dir: None,
trusted_proxy_identity: false,
per_user_slots: false,
mid_session_routing: ai_memory_core::MidSessionRouting::default(),
profile: ai_memory_core::profile::ProfileSettings::default(),
ingest_drop_list: ai_memory_hooks::IngestDropList::default(),
record_tool_names: false,
skip_wiki_checkpoints: false,
};
let endpoint = ServerEndpoint::for_hook_target("http://localhost".into(), None);
let sid = "native-session-resumed-across-two-offline-intervals";
let interval_items = |journal: &str, prompt: &str, event_id: &str| {
vec![
hook_item(
&endpoint,
"ws",
"project",
"claude-code",
"session-start",
sid,
&replay_ingest_key(Some(journal), sid, "session-start", "boundary"),
None,
serde_json::json!({"session_id": sid, "cwd": "/repo"}),
)
.unwrap(),
hook_item(
&endpoint,
"ws",
"project",
"claude-code",
"user-prompt",
sid,
&replay_ingest_key(Some(journal), sid, "message", event_id),
None,
serde_json::json!({"session_id": sid, "cwd": "/repo", "prompt": prompt}),
)
.unwrap(),
hook_item(
&endpoint,
"ws",
"project",
"claude-code",
"session-end",
sid,
&replay_ingest_key(Some(journal), sid, "session-end", "boundary"),
None,
serde_json::json!({"session_id": sid, "cwd": "/repo"}),
)
.unwrap(),
]
};
let router_state = state.clone();
let post = move |items: Vec<HookItem>| {
let state = router_state.clone();
async move {
let response = hook_router(state)
.oneshot(
axum::http::Request::post("/hook/batch")
.header("content-type", "application/json")
.body(axum::body::Body::from(serde_json::to_vec(&items).unwrap()))
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), axum::http::StatusCode::OK);
let ack: HookBatchAck = serde_json::from_slice(
&axum::body::to_bytes(response.into_body(), usize::MAX)
.await
.unwrap(),
)
.unwrap();
assert_eq!(
acknowledged_items(&ack, &items.iter().collect::<Vec<_>>())
.unwrap()
.len(),
items.len()
);
ack.results
.into_iter()
.map(|result| result.outcome)
.collect::<Vec<_>>()
}
};
let first = interval_items("journal-a", "first interval prompt", "event-1");
assert_eq!(
post(first.clone()).await,
vec!["stored", "stored", "stored"],
"the first offline interval recovers exactly once"
);
let second = interval_items("journal-b", "second interval prompt", "event-2");
assert_eq!(
post(second.clone()).await,
vec!["stored", "stored", "stored"],
"the resumed interval's content and session-end must be stored, not replayed"
);
let observations = store
.reader
.observations_for_session(SessionId::from_native(sid))
.await
.unwrap();
assert_eq!(observations.len(), 6, "two start/end pairs and two prompts");
assert_eq!(
observations
.iter()
.filter(|observation| observation.body == "first interval prompt")
.count(),
1
);
assert_eq!(
observations
.iter()
.filter(|observation| observation.body == "second interval prompt")
.count(),
1
);
assert_eq!(
observations
.iter()
.filter(|observation| observation.kind == ObservationKind::SessionEnd)
.count(),
2,
"each interval's session-end is its own stored observation"
);
for rerun in [first, second] {
assert!(
rerun
.iter()
.zip(post(rerun.clone()).await)
.all(|(item, outcome)| {
let is_end = reqwest::Url::parse(&item.url)
.unwrap()
.query_pairs()
.any(|(key, value)| key == "event" && value == "session-end");
outcome == "replayed" || (is_end && outcome == "ignored_end")
}),
"re-running a recovered interval is a pure replay"
);
}
let observations = store
.reader
.observations_for_session(SessionId::from_native(sid))
.await
.unwrap();
assert_eq!(observations.len(), 6, "replays add no observations");
}
#[test]
fn assistant_and_tool_events_map_to_backfill_extension_observations() {
let a = map_event(
None,
"sid",
&event(
WorkstreamEventKind::Message,
Some("assistant"),
"here is the plan\nline2",
),
None,
&EventCapture::Keep,
)
.expect("assistant maps");
assert_eq!(a.event, "backfill.assistant-message");
assert_eq!(a.source_event.as_deref(), Some("assistant-message"));
assert_eq!(
a.body["title"], "here is the plan",
"title is the first line"
);
assert_eq!(a.body["message"], "here is the plan\nline2");
assert!(
a.body["occurred_at"].is_null(),
"no occurred_at was supplied"
);
let t = map_event(
None,
"sid",
&event(WorkstreamEventKind::ToolCall, None, "grep foo"),
None,
&EventCapture::Keep,
)
.expect("tool call maps");
assert_eq!(t.event, "backfill.tool_call");
assert_eq!(t.source_event.as_deref(), Some("tool_call"));
}
/// Round-trips a literal RFC 3339 string through `jiff::Timestamp` so
/// expectations match `resolve_occurred_at`'s own parse-then-format
/// output rather than assuming it echoes the input string verbatim.
fn ts(literal: &str) -> String {
literal.parse::<jiff::Timestamp>().unwrap().to_string()
}
#[test]
fn resolve_occurred_at_fills_gaps_from_the_preceding_event() {
let mut e1 = event(WorkstreamEventKind::Message, Some("user"), "one");
e1.occurred_at = Some("2026-09-10T12:00:00Z".to_string());
let e2 = event(WorkstreamEventKind::Message, Some("assistant"), "two"); // no timestamp
let mut e3 = event(WorkstreamEventKind::ToolCall, None, "three");
e3.occurred_at = Some("2026-09-10T12:05:00Z".to_string());
let e4 = event(WorkstreamEventKind::ToolResult, None, "four"); // no timestamp
let resolved = resolve_occurred_at(&[e1, e2, e3, e4]);
assert_eq!(
resolved.per_event,
vec![
Some(ts("2026-09-10T12:00:00Z")),
Some(ts("2026-09-10T12:00:00Z")),
Some(ts("2026-09-10T12:05:00Z")),
Some(ts("2026-09-10T12:05:00Z")),
],
"an event without its own timestamp inherits the nearest preceding one"
);
assert_eq!(resolved.earliest, Some(ts("2026-09-10T12:00:00Z")));
assert_eq!(resolved.latest, Some(ts("2026-09-10T12:05:00Z")));
}
#[test]
fn resolve_occurred_at_backfills_the_leading_gap_from_the_first_valid_timestamp() {
let e1 = event(WorkstreamEventKind::Message, Some("user"), "one"); // no timestamp
let e2 = event(WorkstreamEventKind::Message, Some("assistant"), "two"); // no timestamp
let mut e3 = event(WorkstreamEventKind::ToolCall, None, "three");
e3.occurred_at = Some("2026-09-10T12:05:00Z".to_string());
let resolved = resolve_occurred_at(&[e1, e2, e3]);
assert_eq!(
resolved.per_event,
vec![
Some(ts("2026-09-10T12:05:00Z")),
Some(ts("2026-09-10T12:05:00Z")),
Some(ts("2026-09-10T12:05:00Z")),
],
"events before the first valid timestamp inherit it backward, \
not just the ones after"
);
}
#[test]
fn resolve_occurred_at_treats_an_unparsable_timestamp_as_missing() {
let mut e1 = event(WorkstreamEventKind::Message, Some("user"), "one");
e1.occurred_at = Some("2026-09-10T12:00:00Z".to_string());
let mut e2 = event(WorkstreamEventKind::Message, Some("assistant"), "two");
e2.occurred_at = Some("not-a-timestamp".to_string());
let resolved = resolve_occurred_at(&[e1, e2]);
assert_eq!(
resolved.per_event,
vec![
Some(ts("2026-09-10T12:00:00Z")),
Some(ts("2026-09-10T12:00:00Z"))
],
"an unparsable timestamp must not reach the hook body; the \
preceding valid one is inherited instead"
);
assert_eq!(resolved.latest, Some(ts("2026-09-10T12:00:00Z")));
}
#[test]
fn resolve_occurred_at_uses_min_and_max_not_first_and_last_when_out_of_order() {
// A transcript is not guaranteed to be time-sorted (clock skew,
// reordering); the session boundary must reflect the actual extremes,
// not just the first/last entries.
let mut e1 = event(WorkstreamEventKind::Message, Some("user"), "one");
e1.occurred_at = Some("2026-09-10T12:05:00Z".to_string());
let mut e2 = event(WorkstreamEventKind::Message, Some("assistant"), "two");
e2.occurred_at = Some("2026-09-10T12:00:00Z".to_string());
let resolved = resolve_occurred_at(&[e1, e2]);
assert_eq!(
resolved.earliest,
Some(ts("2026-09-10T12:00:00Z")),
"earliest must be the minimum valid time, not the first entry"
);
assert_eq!(
resolved.latest,
Some(ts("2026-09-10T12:05:00Z")),
"latest must be the maximum valid time, not the last entry"
);
}
#[test]
fn resolve_occurred_at_stays_none_when_nothing_has_a_timestamp() {
let events = vec![
event(WorkstreamEventKind::Message, Some("user"), "one"),
event(WorkstreamEventKind::Message, Some("assistant"), "two"),
];
let resolved = resolve_occurred_at(&events);
assert_eq!(resolved.per_event, vec![None, None]);
assert_eq!(resolved.earliest, None);
assert_eq!(resolved.latest, None);
}
#[test]
fn empty_and_boundary_events_are_dropped() {
assert!(
map_event(
None,
"sid",
&event(WorkstreamEventKind::Message, Some("user"), " "),
None,
&EventCapture::Keep,
)
.is_none(),
"whitespace-only content is not an observation"
);
for kind in [
WorkstreamEventKind::Compaction,
WorkstreamEventKind::Checkpoint,
WorkstreamEventKind::Annotation,
] {
assert!(
map_event(
None,
"sid",
&event(kind, None, "boundary"),
None,
&EventCapture::Keep
)
.is_none(),
"{kind:?} is not session content"
);
}
}
/// End-to-end proof that `collect_local_sessions` wires to the real
/// workstream path encoder: a Claude transcript planted under the actual
/// `~/.claude/projects/<enc-cwd>/` layout for this cwd is discovered, and a
/// transcript for a different cwd is ignored.
///
/// Unix-gated: the fixture uses a POSIX-encoded projects path; cross-platform
/// native-store discovery is owned and tested by `ai-memory-workstream`. The
/// pure selection/cap tests above run on every platform.
#[cfg(unix)]
#[tokio::test]
async fn collect_local_sessions_finds_a_planted_claude_session_for_this_cwd() {
let home = tempfile::tempdir().unwrap();
let cwd = tempfile::tempdir().unwrap();
let other_cwd = tempfile::tempdir().unwrap();
let session_dir = home
.path()
.join(".claude")
.join("projects")
.join(cwd.path().to_string_lossy().replace('/', "-"));
std::fs::create_dir_all(&session_dir).unwrap();
let header = serde_json::json!({
"sessionId": "11111111-2222-3333-4444-555555555555",
"cwd": cwd.path().to_string_lossy(),
});
std::fs::write(session_dir.join("sess.jsonl"), format!("{header}\n")).unwrap();
let foreign = serde_json::json!({
"sessionId": "99999999-8888-7777-6666-555555555555",
"cwd": other_cwd.path().to_string_lossy(),
});
std::fs::write(session_dir.join("foreign.jsonl"), format!("{foreign}\n")).unwrap();
let (found, _limit_hit) =
collect_local_sessions_with(home.path(), cwd.path(), None, |_| None).await;
let claude: Vec<_> = found
.iter()
.filter(|s| s.harness == ManagedHarness::Claude)
.collect();
assert_eq!(claude.len(), 1, "only the matching-cwd session: {found:?}");
assert_eq!(
claude[0].native_session_id,
"11111111-2222-3333-4444-555555555555"
);
// `--session` narrows to one id.
let (only, _limit_hit) =
collect_local_sessions_with(home.path(), cwd.path(), Some("nope"), |_| None).await;
assert!(only.is_empty(), "no session matches the filter: {only:?}");
}
// These exercise the real listing cap with more than 200 files/rows.
// Setup, listing and cleanup take more than a second alone on macOS,
// even with the SQLite fixture inserted in one transaction.
mod slow_explicit_session_lookup {
use super::*;
#[tokio::test]
async fn collect_local_sessions_explicit_file_target_bypasses_listing_cap() {
let home = tempfile::tempdir().unwrap();
let cwd = tempfile::tempdir().unwrap();
let session_dir = home
.path()
.join(".claude/projects")
.join(ai_memory_workstream::claude_project_dir_name(cwd.path()));
std::fs::create_dir_all(&session_dir).unwrap();
let target = "11111111-2222-4333-8444-000000000000";
for index in 0..=PER_HARNESS_SCAN_LIMIT {
let id = format!("11111111-2222-4333-8444-{index:012}");
let header = serde_json::json!({ "sessionId": id, "cwd": cwd.path() });
let path = session_dir.join(format!("{id}.jsonl"));
std::fs::write(&path, format!("{header}\n")).unwrap();
std::fs::File::options()
.write(true)
.open(path)
.unwrap()
.set_times(std::fs::FileTimes::new().set_modified(
SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000 + index as u64),
))
.unwrap();
}
let (listed, limit_hit) =
collect_local_sessions_with(home.path(), cwd.path(), None, |_| None).await;
assert_eq!(listed.len(), PER_HARNESS_SCAN_LIMIT);
assert_eq!(limit_hit, vec![ManagedHarness::Claude]);
assert!(
listed
.iter()
.all(|session| session.native_session_id != target)
);
let (selected, limit_hit) =
collect_local_sessions_with(home.path(), cwd.path(), Some(target), |_| None).await;
assert_eq!(selected.len(), 1, "the explicit old session must be found");
assert_eq!(selected[0].harness, ManagedHarness::Claude);
assert_eq!(selected[0].native_session_id, target);
assert_eq!(
selected[0].updated_at,
SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000),
);
assert!(
limit_hit.is_empty(),
"an exact lookup is not a capped listing"
);
for missing in ["no-such-session", "../outside", ""] {
let (selected, _) =
collect_local_sessions_with(home.path(), cwd.path(), Some(missing), |_| None)
.await;
assert!(selected.is_empty(), "must not select {missing:?}");
}
let foreign = tempfile::tempdir().unwrap();
let (selected, _) =
collect_local_sessions_with(home.path(), foreign.path(), Some(target), |_| None)
.await;
assert!(
selected.is_empty(),
"the exact ID must still belong to this cwd"
);
}
#[tokio::test]
async fn collect_local_sessions_explicit_sql_target_bypasses_listing_cap() {
let home = tempfile::tempdir().unwrap();
let cwd = tempfile::tempdir().unwrap();
let store = home.path().join("opencode");
std::fs::create_dir_all(&store).unwrap();
let mut db = rusqlite::Connection::open(store.join("opencode.db")).unwrap();
let transaction = db.transaction().unwrap();
for table in ["session", "session_v2"] {
transaction.execute_batch(&format!(
"CREATE TABLE {table}(id TEXT PRIMARY KEY, directory TEXT, time_updated INTEGER);"
))
.unwrap();
for index in 0..=PER_HARNESS_SCAN_LIMIT {
transaction
.execute(
&format!("INSERT INTO {table} VALUES (?1, ?2, ?3)"),
rusqlite::params![
format!("{table}-{index:04}"),
cwd.path().to_string_lossy(),
1_700_000_000_000_i64 + index as i64,
],
)
.unwrap();
}
}
transaction.commit().unwrap();
let session_dir_for = |harness| {
matches!(
harness,
ManagedHarness::OpenCode | ManagedHarness::OpenCode2
)
.then(|| store.clone())
};
let (listed, limit_hit) =
collect_local_sessions_with(home.path(), cwd.path(), None, session_dir_for).await;
assert_eq!(listed.len(), 2 * PER_HARNESS_SCAN_LIMIT);
assert_eq!(
limit_hit,
vec![ManagedHarness::OpenCode, ManagedHarness::OpenCode2]
);
for (table, harness) in [
("session", ManagedHarness::OpenCode),
("session_v2", ManagedHarness::OpenCode2),
] {
let target = format!("{table}-0000");
let (selected, limit_hit) = collect_local_sessions_with(
home.path(),
cwd.path(),
Some(&target),
session_dir_for,
)
.await;
assert_eq!(selected.len(), 1, "the explicit old {harness:?} session");
assert_eq!(selected[0].harness, harness);
assert_eq!(selected[0].native_session_id, target);
assert_eq!(
selected[0].updated_at,
SystemTime::UNIX_EPOCH + Duration::from_millis(1_700_000_000_000),
);
assert!(limit_hit.is_empty());
let foreign = tempfile::tempdir().unwrap();
let (selected, _) = collect_local_sessions_with(
home.path(),
foreign.path(),
Some(&target),
session_dir_for,
)
.await;
assert!(
selected.is_empty(),
"must not import a foreign {harness:?} session"
);
}
}
}
#[tokio::test]
async fn collect_local_sessions_explicit_crush_target_keeps_subagents_excluded() {
let home = tempfile::tempdir().unwrap();
let cwd = tempfile::tempdir().unwrap();
let store = cwd.path().join(".crush");
std::fs::create_dir_all(&store).unwrap();
let db = rusqlite::Connection::open(store.join("crush.db")).unwrap();
db.execute_batch(
"CREATE TABLE sessions(id TEXT PRIMARY KEY, parent_session_id TEXT, updated_at INTEGER); \
INSERT INTO sessions VALUES ('parent', NULL, 1700000000); \
INSERT INTO sessions VALUES ('child', 'parent', 1700000001); \
INSERT INTO sessions VALUES ('invalid-time', NULL, -1);",
)
.unwrap();
let session_dir_for = |harness| (harness == ManagedHarness::Crush).then(|| store.clone());
let (selected, limit_hit) =
collect_local_sessions_with(home.path(), cwd.path(), Some("parent"), session_dir_for)
.await;
assert_eq!(selected.len(), 1);
assert_eq!(selected[0].harness, ManagedHarness::Crush);
assert_eq!(selected[0].native_session_id, "parent");
assert_eq!(
selected[0].updated_at,
SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000),
);
assert!(limit_hit.is_empty());
for id in ["child", "invalid-time", "missing"] {
let (selected, _) =
collect_local_sessions_with(home.path(), cwd.path(), Some(id), session_dir_for)
.await;
assert!(selected.is_empty(), "must not select {id}");
}
}
/// GHSA-gcpc-88hm-3xqr: a planted Claude transcript reads one file under
/// the checkout's `[capture] ignore_paths` and one outside it. The
/// excluded read's call and output never reach `/hook/batch`; the public
/// read's do. A malformed read is posted as the hook's metadata-only body.
#[cfg(unix)]
#[tokio::test]
async fn backfill_never_posts_tool_content_the_capture_policy_excludes() {
use axum::{Router, routing::post};
use std::sync::{Arc, Mutex};
let posted = Arc::new(Mutex::new(Vec::<serde_json::Value>::new()));
let captured = posted.clone();
let app = Router::new().route(
"/hook/batch",
post(
move |axum::Json(items): axum::Json<Vec<serde_json::Value>>| {
let captured = captured.clone();
async move {
let accepted = items.len();
captured.lock().unwrap().extend(items);
let results: Vec<_> = (0..accepted)
.map(|index| serde_json::json!({ "index": index, "outcome": "stored" }))
.collect();
axum::Json(serde_json::json!({ "accepted": accepted, "results": results }))
}
},
),
);
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
let home = tempfile::tempdir().unwrap();
let repo = tempfile::tempdir().unwrap();
std::fs::write(
repo.path().join(".ai-memory.toml"),
"[capture]\nignore_paths = [\"docs/adr/**\"]\n",
)
.unwrap();
let session_dir = home
.path()
.join(".claude")
.join("projects")
.join(repo.path().to_string_lossy().replace('/', "-"));
std::fs::create_dir_all(&session_dir).unwrap();
let sid = "11111111-2222-3333-4444-555555555555";
let cwd = repo.path().to_string_lossy();
let record = |uuid: &str, kind: &str, content: serde_json::Value| {
serde_json::json!({
"type": kind, "uuid": uuid, "sessionId": sid, "cwd": cwd,
"timestamp": "2026-09-01T10:00:00Z",
"message": {"role": kind, "content": content},
})
.to_string()
};
let read = |id: &str, input: serde_json::Value| serde_json::json!({"type": "tool_use", "id": id, "name": "Read", "input": input});
let output = |id: &str, text: &str| serde_json::json!({"type": "tool_result", "tool_use_id": id, "content": text});
let lines = [
record("u1", "user", serde_json::json!("read the adr and lib")),
record(
"a1",
"assistant",
serde_json::json!([
read(
"toolu_adr",
serde_json::json!({"file_path": repo.path().join("docs/adr/1.md")})
),
read(
"toolu_pub",
serde_json::json!({"file_path": repo.path().join("src/lib.rs")})
),
read(
"toolu_bad",
serde_json::json!({"file_path": 7, "note": "ARGSENTINEL"})
),
]),
),
record(
"u2",
"user",
serde_json::json!([
output("toolu_adr", "ADRSENTINEL private decision"),
output("toolu_pub", "PUBLICCONTROL public code"),
output("toolu_bad", "BADSENTINEL unprovable output"),
]),
),
];
std::fs::write(
session_dir.join(format!("{sid}.jsonl")),
lines.join("\n") + "\n",
)
.unwrap();
let endpoint = ServerEndpoint::for_hook_target(format!("http://{address}"), None);
let session = SessionRef {
harness: ManagedHarness::Claude,
native_session_id: sid.into(),
updated_at: SystemTime::now(),
};
let capture = TranscriptCapture::for_checkout(home.path(), repo.path());
import_one(
&endpoint,
"ws",
"proj",
home.path(),
repo.path(),
&capture,
&session,
)
.await
.unwrap();
server.abort();
let posted = posted.lock().unwrap();
let text = serde_json::to_string(&*posted).unwrap();
for sentinel in ["ADRSENTINEL", "docs/adr", "ARGSENTINEL", "BADSENTINEL"] {
assert!(!text.contains(sentinel), "{sentinel} was posted: {text}");
}
assert!(text.contains("PUBLICCONTROL"), "public output: {text}");
assert!(text.contains("src/lib.rs"), "public call: {text}");
let stripped: Vec<_> = posted
.iter()
.filter(|item| item["body"].get("_ai_memory_capture").is_some())
.collect();
assert_eq!(
stripped.len(),
2,
"the malformed call and its output: {text}"
);
for item in stripped {
assert_eq!(
item["body"]["_ai_memory_capture"]["disposition"],
"metadata-only"
);
assert_eq!(item["body"]["tool_family"], "file");
assert_eq!(item["body"]["tool_call_id"], "toolu_bad");
}
}
/// Allowlist capture mode (#446) makes an unmarked checkout emit nothing
/// from the live hook, so a manual backfill of it must not contact the
/// server at all. Controls: the same checkout with a marker, and the same
/// unmarked checkout under the default denylist mode, both proceed to the
/// server.
#[tokio::test]
async fn allowlist_mode_backfills_nothing_from_an_unmarked_checkout() {
use axum::{Router, extract::Request};
use std::sync::{Arc, Mutex};
let requests = Arc::new(Mutex::new(Vec::<String>::new()));
let seen = requests.clone();
let app = Router::new().fallback(move |request: Request| {
let seen = seen.clone();
async move {
seen.lock().unwrap().push(request.uri().path().to_owned());
axum::Json(serde_json::json!({ "by_agent": [], "accepted": 0 }))
}
});
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
let attempt = |mode: Option<&'static str>, marked: bool| {
let requests = requests.clone();
async move {
let home = tempfile::tempdir().unwrap();
let data_dir = tempfile::tempdir().unwrap();
let repo = tempfile::tempdir().unwrap();
if let Some(mode) = mode {
std::fs::write(
data_dir.path().join(super::super::hook::CAPTURE_MODE_FILE),
mode,
)
.unwrap();
}
if marked {
std::fs::write(repo.path().join(".ai-memory.toml"), "[capture]\n").unwrap();
}
let mut config =
crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();
config.data_dir = data_dir.path().to_path_buf();
config.home_dir = Some(home.path().to_string_lossy().into_owned());
config.server_url = format!("http://{address}");
config.auth.bearer_token = None;
let mut args = spawned_args(None, None);
args.auto = false;
args.workspace = Some("ws".into());
args.project = Some("proj".into());
requests.lock().unwrap().clear();
run_in(&config, args, repo.path().to_path_buf())
.await
.unwrap();
requests.lock().unwrap().clone()
}
};
assert!(
attempt(Some("allowlist\n"), false).await.is_empty(),
"allowlist + unmarked checkout must not reach the server"
);
assert!(
!attempt(Some("allowlist\n"), true).await.is_empty(),
"control: a marked checkout proceeds under allowlist"
);
assert!(
!attempt(None, false).await.is_empty(),
"control: denylist (default) is unchanged"
);
server.abort();
}
/// Plant `lines` as one native session and backfill it from `repo`,
/// returning everything posted to `/hook/batch` as one JSON string.
#[cfg(unix)]
async fn backfill_posted(
harness: ManagedHarness,
home: &Path,
data_dir: &Path,
repo: &Path,
sid: &str,
lines: &[serde_json::Value],
) -> String {
use axum::{Router, routing::post};
use std::sync::{Arc, Mutex};
let session_file = match harness {
ManagedHarness::Claude => home
.join(".claude/projects")
.join(repo.to_string_lossy().replace('/', "-"))
.join(format!("{sid}.jsonl")),
ManagedHarness::Codex => home
.join(".codex/sessions/2026/09/01")
.join(format!("rollout-2026-09-01T10-00-00-{sid}.jsonl")),
other => panic!("no fixture layout for {}", other.as_str()),
};
std::fs::create_dir_all(session_file.parent().unwrap()).unwrap();
let body: String = lines.iter().map(|line| format!("{line}\n")).collect();
std::fs::write(&session_file, body).unwrap();
let posted = Arc::new(Mutex::new(Vec::<serde_json::Value>::new()));
let captured = posted.clone();
let app = Router::new().route(
"/hook/batch",
post(
move |axum::Json(items): axum::Json<Vec<serde_json::Value>>| {
let captured = captured.clone();
async move {
let accepted = items.len();
captured.lock().unwrap().extend(items);
let results: Vec<_> = (0..accepted)
.map(|index| serde_json::json!({ "index": index, "outcome": "stored" }))
.collect();
axum::Json(serde_json::json!({ "accepted": accepted, "results": results }))
}
},
),
);
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
let endpoint = ServerEndpoint::for_hook_target(format!("http://{address}"), None);
let session = SessionRef {
harness,
native_session_id: sid.into(),
updated_at: SystemTime::now(),
};
let capture = TranscriptCapture::for_checkout(data_dir, repo);
import_one(&endpoint, "ws", "proj", home, repo, &capture, &session)
.await
.unwrap();
server.abort();
serde_json::to_string(&*posted.lock().unwrap()).unwrap()
}
#[cfg(unix)]
fn marked_checkout(marker: &str) -> tempfile::TempDir {
let dir = tempfile::tempdir().unwrap();
std::fs::write(dir.path().join(".ai-memory.toml"), marker).unwrap();
dir
}
/// Codex records its shell tool as `exec_command` with `{cmd, workdir}`;
/// the live hook receives it as `Bash`. A command whose `workdir`-relative
/// argument names an ignored path never reaches `/hook/batch`, call or
/// output; the same command run from a public directory does.
#[cfg(unix)]
#[tokio::test]
async fn backfill_inspects_codex_exec_command_as_the_hook_shell_call() {
let home = tempfile::tempdir().unwrap();
let repo = marked_checkout("[capture]\nignore_paths = [\"docs/adr/**\"]\n");
for dir in ["docs/adr", "src/adr"] {
std::fs::create_dir_all(repo.path().join(dir)).unwrap();
}
let sid = "019a0000-0000-7000-8000-000000000001";
let item = |payload: serde_json::Value| {
serde_json::json!({
"type": "response_item", "timestamp": "2026-09-01T10:00:00Z", "payload": payload,
})
};
let exec = |id: &str, workdir: &str| {
item(serde_json::json!({
"type": "function_call", "name": "exec_command", "call_id": id,
"arguments": serde_json::json!({
"cmd": "cat adr/x.md", "workdir": repo.path().join(workdir),
}).to_string(),
}))
};
let output = |id: &str, text: &str| {
item(serde_json::json!({"type": "function_call_output", "call_id": id, "output": text}))
};
let lines = [
serde_json::json!({"type": "session_meta", "payload": {"id": sid, "cwd": repo.path()}}),
item(serde_json::json!({
"type": "message", "role": "user",
"content": [{"type": "input_text", "text": "show both adr notes"}],
})),
exec("call_adr", "docs"),
output("call_adr", "ADRSENTINEL private decision"),
exec("call_pub", "src"),
output("call_pub", "PUBLICCONTROL public note"),
];
let posted = backfill_posted(
ManagedHarness::Codex,
home.path(),
home.path(),
repo.path(),
sid,
&lines,
)
.await;
assert!(!posted.contains("ADRSENTINEL"), "excluded output: {posted}");
assert!(!posted.contains("/docs\\\""), "excluded call: {posted}");
assert!(posted.contains("PUBLICCONTROL"), "public output: {posted}");
assert!(posted.contains("/src"), "public call: {posted}");
}
/// A Claude Code transcript record: `content` is the message content.
#[cfg(unix)]
fn claude_record(
sid: &str,
uuid: &str,
cwd: &Path,
role: &str,
content: serde_json::Value,
) -> serde_json::Value {
serde_json::json!({
"type": role, "uuid": uuid, "sessionId": sid, "cwd": cwd,
"timestamp": "2026-09-01T10:00:00Z",
"message": {"role": role, "content": content},
})
}
#[cfg(unix)]
fn claude_tool(name: &str, id: &str, input: serde_json::Value) -> serde_json::Value {
serde_json::json!({"type": "tool_use", "id": id, "name": name, "input": input})
}
#[cfg(unix)]
fn claude_output(id: &str, text: &str) -> serde_json::Value {
serde_json::json!({"type": "tool_result", "tool_use_id": id, "content": text})
}
/// Claude Code records each line's `cwd`, which follows the session as it
/// moves. The live hook resolves a relative argument from that cwd, so an
/// import must too: `cat adr/x.md` run from `docs/` reads an ignored file
/// and is never posted, while the same command run from the checkout root
/// names a public path and is.
#[cfg(unix)]
#[tokio::test]
async fn backfill_resolves_each_call_from_its_record_cwd() {
let home = tempfile::tempdir().unwrap();
let repo = marked_checkout("[capture]\nignore_paths = [\"docs/adr/**\"]\n");
let docs = repo.path().join("docs");
std::fs::create_dir_all(docs.join("adr")).unwrap();
let sid = "11111111-2222-3333-4444-555555555556";
let cat = |id| claude_tool("Bash", id, serde_json::json!({"command": "cat adr/x.md"}));
let lines = [
claude_record(sid, "u1", repo.path(), "user", "read the adr".into()),
claude_record(
sid,
"a1",
&docs,
"assistant",
serde_json::json!([cat("toolu_docs")]),
),
claude_record(
sid,
"u2",
&docs,
"user",
serde_json::json!([claude_output("toolu_docs", "ADRSENTINEL private decision")]),
),
claude_record(
sid,
"a2",
repo.path(),
"assistant",
serde_json::json!([cat("toolu_root")]),
),
claude_record(
sid,
"u3",
repo.path(),
"user",
serde_json::json!([claude_output("toolu_root", "PUBLICCONTROL root note")]),
),
];
let posted = backfill_posted(
ManagedHarness::Claude,
home.path(),
home.path(),
repo.path(),
sid,
&lines,
)
.await;
assert!(!posted.contains("ADRSENTINEL"), "excluded output: {posted}");
assert!(posted.contains("PUBLICCONTROL"), "control output: {posted}");
assert_eq!(
posted.matches("cat adr/x.md").count(),
2,
"only the root call, as title and message: {posted}"
);
}
/// A call the live hook would reroute to another checkout must pass that
/// checkout's admission gate and reach the same server, or it is never
/// posted: under allowlist mode an unmarked repository admits nothing, a
/// marker selecting an unregistered profile emits nothing, and a marker
/// selecting a registered profile sends to another server. Control: a read
/// in a marked checkout of the same project with no server selection is
/// posted.
#[cfg(unix)]
#[tokio::test]
async fn backfill_drops_reroutes_the_live_hook_would_not_deliver_here() {
let home = tempfile::tempdir().unwrap();
let data_dir = tempfile::tempdir().unwrap();
std::fs::write(
data_dir.path().join(super::super::hook::CAPTURE_MODE_FILE),
"allowlist\n",
)
.unwrap();
let name = crate::server_profiles::ProfileName::parse("team-e").unwrap();
crate::server_profiles::add(data_dir.path(), &name, "https://e.example", &[], Some("E"))
.unwrap();
let source = marked_checkout("workspace = \"w\"\nproject = \"p\"\n");
let unmarked = tempfile::tempdir().unwrap();
let init = std::process::Command::new("git")
.args(["init", "-q"])
.arg(unmarked.path())
.status()
.unwrap();
assert!(init.success());
let unknown_profile = marked_checkout("server = \"team-b\"\n");
let other_server = marked_checkout("server = \"team-e\"\n");
let same_server = marked_checkout("workspace = \"w\"\nproject = \"p\"\n");
let sid = "11111111-2222-3333-4444-555555555557";
let reads = [
(&unmarked, "UNMARKEDSENTINEL"),
(&unknown_profile, "UNKNOWNPROFILESENTINEL"),
(&other_server, "OTHERSERVERSENTINEL"),
(&same_server, "SAMESERVERCONTROL"),
];
let mut lines = vec![claude_record(
sid,
"u0",
source.path(),
"user",
"read the notes".into(),
)];
for (index, (repo, text)) in reads.iter().enumerate() {
let file = repo.path().join(format!("{text}.txt"));
std::fs::write(&file, text).unwrap();
let id = format!("toolu_{index}");
lines.push(claude_record(
sid,
&format!("a{index}"),
source.path(),
"assistant",
serde_json::json!([claude_tool(
"Read",
&id,
serde_json::json!({"file_path": file})
)]),
));
lines.push(claude_record(
sid,
&format!("u{}", index + 1),
source.path(),
"user",
serde_json::json!([claude_output(&id, &format!("{text} content"))]),
));
}
let posted = backfill_posted(
ManagedHarness::Claude,
home.path(),
data_dir.path(),
source.path(),
sid,
&lines,
)
.await;
for sentinel in [
"UNMARKEDSENTINEL",
"UNKNOWNPROFILESENTINEL",
"OTHERSERVERSENTINEL",
] {
assert!(
!posted.contains(sentinel),
"{sentinel} was posted: {posted}"
);
}
assert!(
posted.contains("SAMESERVERCONTROL content"),
"control: {posted}"
);
assert!(posted.contains("read the notes"), "prompt kept: {posted}");
}
/// The live server stores only the family of an unknown-family tool, with
/// no policy at all. A backfilled Codex MCP call and its output therefore
/// post only `tool_family: unknown`, never their arguments or output, while
/// a recognized shell call's output is posted as before.
#[cfg(unix)]
#[tokio::test]
async fn backfill_posts_no_content_for_unrecognized_tools() {
let home = tempfile::tempdir().unwrap();
let repo = tempfile::tempdir().unwrap();
let sid = "019a0000-0000-7000-8000-000000000002";
let item = |payload: serde_json::Value| {
serde_json::json!({
"type": "response_item", "timestamp": "2026-09-01T10:00:00Z", "payload": payload,
})
};
let call = |id: &str, name: &str, arguments: serde_json::Value| {
item(serde_json::json!({
"type": "function_call", "name": name, "call_id": id,
"arguments": arguments.to_string(),
}))
};
let output = |id: &str, text: &str| {
item(serde_json::json!({"type": "function_call_output", "call_id": id, "output": text}))
};
let lines = [
serde_json::json!({"type": "session_meta", "payload": {"id": sid, "cwd": repo.path()}}),
call(
"call_mcp",
"mcp__vault__fetch",
serde_json::json!({"query": "ARGSENTINEL"}),
),
output("call_mcp", "MCPSENTINEL private record"),
call(
"call_pub",
"exec_command",
serde_json::json!({"cmd": "cargo test"}),
),
output("call_pub", "PUBLICCONTROL test result"),
];
let posted = backfill_posted(
ManagedHarness::Codex,
home.path(),
home.path(),
repo.path(),
sid,
&lines,
)
.await;
for sentinel in ["ARGSENTINEL", "MCPSENTINEL", "mcp__vault"] {
assert!(
!posted.contains(sentinel),
"{sentinel} was posted: {posted}"
);
}
assert_eq!(
posted.matches("\"title\":\"tool unknown\"").count(),
2,
"the call and its output are still recorded: {posted}"
);
assert!(posted.contains("PUBLICCONTROL"), "control: {posted}");
}
/// A reroute is delivered only when the destination's marker selects the
/// same registered server profile as the source and the same project: a
/// different registered profile is dropped, and so is a checkout of
/// another project on the same profile, whose events the live hook files
/// under that project. The same holds for records written in such a
/// checkout, whatever their tool calls name.
#[cfg(unix)]
#[tokio::test]
async fn backfill_keeps_reroutes_to_the_same_server_profile_only() {
let home = tempfile::tempdir().unwrap();
let data_dir = tempfile::tempdir().unwrap();
let base = tempfile::tempdir().unwrap();
let checkout = |name: &str, profile: &str, project: &str| {
let dir = base.path().join(name);
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(
dir.join(".ai-memory.toml"),
format!("server = \"{profile}\"\nworkspace = \"w\"\nproject = \"{project}\"\n"),
)
.unwrap();
dir
};
let source = checkout("source", "team-a", "p");
let same = checkout("same", "team-a", "p");
let other = checkout("other", "team-e", "p");
let sibling = checkout("sibling", "team-a", "q");
let root = |dir: &Path| dir.to_string_lossy().into_owned();
for (name, roots) in [
("team-a", vec![root(&source), root(&same), root(&sibling)]),
("team-e", vec![root(&other)]),
] {
let name = crate::server_profiles::ProfileName::parse(name).unwrap();
crate::server_profiles::add(
data_dir.path(),
&name,
"https://a.example",
&roots,
Some("T"),
)
.unwrap();
}
let sid = "11111111-2222-3333-4444-555555555558";
let mut lines = vec![claude_record(sid, "u0", &source, "user", "read".into())];
for (index, (repo, text)) in [
(&same, "SAMEPROFILECONTROL"),
(&other, "OTHERPROFILESENTINEL"),
(&sibling, "OTHERPROJECTSENTINEL"),
]
.into_iter()
.enumerate()
{
let file = repo.join(format!("{text}.txt"));
let id = format!("toolu_{index}");
lines.push(claude_record(
sid,
&format!("a{index}"),
&source,
"assistant",
serde_json::json!([claude_tool(
"Read",
&id,
serde_json::json!({"file_path": file})
)]),
));
lines.push(claude_record(
sid,
&format!("u{}", index + 1),
&source,
"user",
serde_json::json!([claude_output(&id, &format!("{text} content"))]),
));
}
lines.push(claude_record(
sid,
"moved",
&sibling,
"user",
"SIBLINGPROMPTSENTINEL".into(),
));
let posted = backfill_posted(
ManagedHarness::Claude,
home.path(),
data_dir.path(),
&source,
sid,
&lines,
)
.await;
assert!(
posted.contains("SAMEPROFILECONTROL content"),
"same profile: {posted}"
);
for sentinel in [
"OTHERPROFILESENTINEL",
"OTHERPROJECTSENTINEL",
"SIBLINGPROMPTSENTINEL",
] {
assert!(!posted.contains(sentinel), "{sentinel}: {posted}");
}
}
/// Claude Code writes a monitored command's streamed output and a
/// background agent's report as user turns, and its compact summary too;
/// no prompt hook fires for any of them, so none is posted as a prompt.
/// Control: the operator's own prompt is.
#[cfg(unix)]
#[tokio::test]
async fn backfill_posts_no_task_notification_or_compact_summary_as_a_prompt() {
let home = tempfile::tempdir().unwrap();
let repo = tempfile::tempdir().unwrap();
let sid = "11111111-2222-3333-4444-555555555559";
let mut monitor = claude_record(
sid,
"n1",
repo.path(),
"user",
"<task-notification>\n<event>MONITORSENTINEL stdout line</event>\n</task-notification>"
.into(),
);
monitor["origin"] = serde_json::json!({"kind": "task-notification"});
let report = claude_record(
sid,
"n2",
repo.path(),
"user",
"<task-notification>\n<result>AGENTSENTINEL report</result>\n</task-notification>"
.into(),
);
let mut summary = claude_record(
sid,
"c1",
repo.path(),
"user",
"This session is being continued. SUMMARYSENTINEL".into(),
);
summary["isCompactSummary"] = true.into();
let lines = [
claude_record(sid, "u1", repo.path(), "user", "PROMPTCONTROL".into()),
monitor,
report,
summary,
];
let posted = backfill_posted(
ManagedHarness::Claude,
home.path(),
home.path(),
repo.path(),
sid,
&lines,
)
.await;
for sentinel in ["MONITORSENTINEL", "AGENTSENTINEL", "SUMMARYSENTINEL"] {
assert!(!posted.contains(sentinel), "{sentinel}: {posted}");
}
assert!(posted.contains("PROMPTCONTROL"), "control: {posted}");
}
fn spawned_args(
server_url: Option<&str>,
server_profile: Option<&str>,
) -> crate::cli::BackfillArgs {
crate::cli::BackfillArgs {
workspace: None,
project: None,
session: None,
force: false,
dry_run: false,
max_sessions: 25,
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),
}
}
/// #992: a SessionStart-spawned backfill presents only the credential the
/// hook itself uses for that server — never the config/env bearer, which
/// may belong to another server entirely.
#[tokio::test]
async fn a_spawned_backfill_authenticates_like_the_hook_that_spawned_it() {
let home = tempfile::tempdir().unwrap();
let data_dir = tempfile::tempdir().unwrap();
let mut config =
crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();
config.data_dir = data_dir.path().to_path_buf();
config.auth.bearer_token = Some("CONFIG-SERVER-TOKEN".into());
let url = "https://hook.example/wiki";
let endpoint = backfill_endpoint(&config, &spawned_args(Some(url), None))
.await
.unwrap();
assert_eq!(
endpoint.auth_token, None,
"no hook token: nothing, not config's"
);
assert_eq!(endpoint.url, "https://hook.example");
assert_eq!(endpoint.base_path, "/wiki");
crate::config::store_hook_auth_token(data_dir.path(), "HOOK-TOKEN").unwrap();
let endpoint = backfill_endpoint(&config, &spawned_args(Some(url), None))
.await
.unwrap();
assert_eq!(endpoint.auth_token.as_deref(), Some("HOOK-TOKEN"));
let name = crate::server_profiles::ProfileName::parse("team-b").unwrap();
crate::server_profiles::add(data_dir.path(), &name, "https://b.example", &[], Some("B"))
.unwrap();
let endpoint = backfill_endpoint(&config, &spawned_args(None, Some("team-b")))
.await
.unwrap();
assert_eq!(endpoint.url, "https://b.example");
assert_eq!(endpoint.auth_token.as_deref(), Some("B"));
assert!(
backfill_endpoint(&config, &spawned_args(None, Some("nobody")))
.await
.is_err(),
"an unregistered profile is refused, not replaced by config"
);
}
/// The automatic path must honor the `backfill_on_start` opt-out: it records
/// the attempt (so it never re-spawns) and returns without contacting the
/// server at all.
#[tokio::test]
async fn auto_run_opted_out_writes_sentinel_and_makes_no_request() {
let home = tempfile::tempdir().unwrap();
let data_dir = tempfile::tempdir().unwrap();
let mut config =
crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();
config.data_dir = data_dir.path().to_path_buf();
config.backfill_on_start = false;
// An unroutable server would make any request hang/fail; the opt-out
// must return before we ever build the endpoint.
config.server_url = "http://127.0.0.1:9".to_string();
run(&config, spawned_args(None, None))
.await
.expect("opted-out auto run must succeed without contacting the server");
let cwd = std::env::current_dir().unwrap();
assert!(
sentinel_path(&config.data_dir, &cwd).exists(),
"the opt-out must still record the attempt so it does not re-spawn"
);
}
/// The worker frees the marker the hook claimed, however it ends, so the
/// next SessionStart can spawn again when one is needed.
#[tokio::test]
async fn an_auto_run_releases_the_marker_its_hook_claimed() {
let home = tempfile::tempdir().unwrap();
let data_dir = tempfile::tempdir().unwrap();
let mut config =
crate::config::Config::load(None, Some(home.path().to_path_buf())).unwrap();
config.data_dir = data_dir.path().to_path_buf();
config.backfill_on_start = false;
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();
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, 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).is_some(),
"free for the next run"
);
}
}